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.
447 Simple audio dynamic range compression/expansion filter.
449 The filter accepts the following options:
453 Set contrast. Default is 33. Allowed range is between 0 and 100.
458 Copy the input audio source unchanged to the output. This is mainly useful for
463 Apply cross fade from one input audio stream to another input audio stream.
464 The cross fade is applied for specified duration near the end of first stream.
466 The filter accepts the following options:
470 Specify the number of samples for which the cross fade effect has to last.
471 At the end of the cross fade effect the first input audio will be completely
472 silent. Default is 44100.
475 Specify the duration of the cross fade effect. See
476 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
477 for the accepted syntax.
478 By default the duration is determined by @var{nb_samples}.
479 If set this option is used instead of @var{nb_samples}.
482 Should first stream end overlap with second stream start. Default is enabled.
485 Set curve for cross fade transition for first stream.
488 Set curve for cross fade transition for second stream.
490 For description of available curve types see @ref{afade} filter description.
497 Cross fade from one input to another:
499 ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:c1=exp:c2=exp output.flac
503 Cross fade from one input to another but without overlapping:
505 ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:o=0:c1=exp:c2=exp output.flac
510 Split audio stream into several bands.
512 This filter splits audio stream into two or more frequency ranges.
513 Summing all streams back will give flat output.
515 The filter accepts the following options:
519 Set split frequencies. Those must be positive and increasing.
522 Set filter order, can be @var{2nd}, @var{4th} or @var{8th}.
523 Default is @var{4th}.
528 Reduce audio bit resolution.
530 This filter is bit crusher with enhanced functionality. A bit crusher
531 is used to audibly reduce number of bits an audio signal is sampled
532 with. This doesn't change the bit depth at all, it just produces the
533 effect. Material reduced in bit depth sounds more harsh and "digital".
534 This filter is able to even round to continuous values instead of discrete
536 Additionally it has a D/C offset which results in different crushing of
537 the lower and the upper half of the signal.
538 An Anti-Aliasing setting is able to produce "softer" crushing sounds.
540 Another feature of this filter is the logarithmic mode.
541 This setting switches from linear distances between bits to logarithmic ones.
542 The result is a much more "natural" sounding crusher which doesn't gate low
543 signals for example. The human ear has a logarithmic perception,
544 so this kind of crushing is much more pleasant.
545 Logarithmic crushing is also able to get anti-aliased.
547 The filter accepts the following options:
563 Can be linear: @code{lin} or logarithmic: @code{log}.
572 Set sample reduction.
575 Enable LFO. By default disabled.
586 Delay audio filtering until a given wallclock timestamp. See the @ref{cue}
590 Remove impulsive noise from input audio.
592 Samples detected as impulsive noise are replaced by interpolated samples using
593 autoregressive modelling.
597 Set window size, in milliseconds. Allowed range is from @code{10} to
598 @code{100}. Default value is @code{55} milliseconds.
599 This sets size of window which will be processed at once.
602 Set window overlap, in percentage of window size. Allowed range is from
603 @code{50} to @code{95}. Default value is @code{75} percent.
604 Setting this to a very high value increases impulsive noise removal but makes
605 whole process much slower.
608 Set autoregression order, in percentage of window size. Allowed range is from
609 @code{0} to @code{25}. Default value is @code{2} percent. This option also
610 controls quality of interpolated samples using neighbour good samples.
613 Set threshold value. Allowed range is from @code{1} to @code{100}.
614 Default value is @code{2}.
615 This controls the strength of impulsive noise which is going to be removed.
616 The lower value, the more samples will be detected as impulsive noise.
619 Set burst fusion, in percentage of window size. Allowed range is @code{0} to
620 @code{10}. Default value is @code{2}.
621 If any two samples detected as noise are spaced less than this value then any
622 sample between those two samples will be also detected as noise.
627 It accepts the following values:
630 Select overlap-add method. Even not interpolated samples are slightly
631 changed with this method.
634 Select overlap-save method. Not interpolated samples remain unchanged.
637 Default value is @code{a}.
641 Remove clipped samples from input audio.
643 Samples detected as clipped are replaced by interpolated samples using
644 autoregressive modelling.
648 Set window size, in milliseconds. Allowed range is from @code{10} to @code{100}.
649 Default value is @code{55} milliseconds.
650 This sets size of window which will be processed at once.
653 Set window overlap, in percentage of window size. Allowed range is from @code{50}
654 to @code{95}. Default value is @code{75} percent.
657 Set autoregression order, in percentage of window size. Allowed range is from
658 @code{0} to @code{25}. Default value is @code{8} percent. This option also controls
659 quality of interpolated samples using neighbour good samples.
662 Set threshold value. Allowed range is from @code{1} to @code{100}.
663 Default value is @code{10}. Higher values make clip detection less aggressive.
666 Set size of histogram used to detect clips. Allowed range is from @code{100} to @code{9999}.
667 Default value is @code{1000}. Higher values make clip detection less aggressive.
672 It accepts the following values:
675 Select overlap-add method. Even not interpolated samples are slightly changed
679 Select overlap-save method. Not interpolated samples remain unchanged.
682 Default value is @code{a}.
687 Delay one or more audio channels.
689 Samples in delayed channel are filled with silence.
691 The filter accepts the following option:
695 Set list of delays in milliseconds for each channel separated by '|'.
696 Unused delays will be silently ignored. If number of given delays is
697 smaller than number of channels all remaining channels will not be delayed.
698 If you want to delay exact number of samples, append 'S' to number.
699 If you want instead to delay in seconds, append 's' to number.
702 Use last set delay for all remaining channels. By default is disabled.
703 This option if enabled changes how option @code{delays} is interpreted.
710 Delay first channel by 1.5 seconds, the third channel by 0.5 seconds and leave
711 the second channel (and any other channels that may be present) unchanged.
717 Delay second channel by 500 samples, the third channel by 700 samples and leave
718 the first channel (and any other channels that may be present) unchanged.
724 Delay all channels by same number of samples:
726 adelay=delays=64S:all=1
730 @section aderivative, aintegral
732 Compute derivative/integral of audio stream.
734 Applying both filters one after another produces original audio.
738 Apply echoing to the input audio.
740 Echoes are reflected sound and can occur naturally amongst mountains
741 (and sometimes large buildings) when talking or shouting; digital echo
742 effects emulate this behaviour and are often used to help fill out the
743 sound of a single instrument or vocal. The time difference between the
744 original signal and the reflection is the @code{delay}, and the
745 loudness of the reflected signal is the @code{decay}.
746 Multiple echoes can have different delays and decays.
748 A description of the accepted parameters follows.
752 Set input gain of reflected signal. Default is @code{0.6}.
755 Set output gain of reflected signal. Default is @code{0.3}.
758 Set list of time intervals in milliseconds between original signal and reflections
759 separated by '|'. Allowed range for each @code{delay} is @code{(0 - 90000.0]}.
760 Default is @code{1000}.
763 Set list of loudness of reflected signals separated by '|'.
764 Allowed range for each @code{decay} is @code{(0 - 1.0]}.
765 Default is @code{0.5}.
772 Make it sound as if there are twice as many instruments as are actually playing:
774 aecho=0.8:0.88:60:0.4
778 If delay is very short, then it sounds like a (metallic) robot playing music:
784 A longer delay will sound like an open air concert in the mountains:
786 aecho=0.8:0.9:1000:0.3
790 Same as above but with one more mountain:
792 aecho=0.8:0.9:1000|1800:0.3|0.25
797 Audio emphasis filter creates or restores material directly taken from LPs or
798 emphased CDs with different filter curves. E.g. to store music on vinyl the
799 signal has to be altered by a filter first to even out the disadvantages of
800 this recording medium.
801 Once the material is played back the inverse filter has to be applied to
802 restore the distortion of the frequency response.
804 The filter accepts the following options:
814 Set filter mode. For restoring material use @code{reproduction} mode, otherwise
815 use @code{production} mode. Default is @code{reproduction} mode.
818 Set filter type. Selects medium. Can be one of the following:
830 select Compact Disc (CD).
836 select 50µs (FM-KF).
838 select 75µs (FM-KF).
844 Modify an audio signal according to the specified expressions.
846 This filter accepts one or more expressions (one for each channel),
847 which are evaluated and used to modify a corresponding audio signal.
849 It accepts the following parameters:
853 Set the '|'-separated expressions list for each separate channel. If
854 the number of input channels is greater than the number of
855 expressions, the last specified expression is used for the remaining
858 @item channel_layout, c
859 Set output channel layout. If not specified, the channel layout is
860 specified by the number of expressions. If set to @samp{same}, it will
861 use by default the same input channel layout.
864 Each expression in @var{exprs} can contain the following constants and functions:
868 channel number of the current expression
871 number of the evaluated sample, starting from 0
877 time of the evaluated sample expressed in seconds
880 @item nb_out_channels
881 input and output number of channels
884 the value of input channel with number @var{CH}
887 Note: this filter is slow. For faster processing you should use a
896 aeval=val(ch)/2:c=same
900 Invert phase of the second channel:
909 Apply fade-in/out effect to input audio.
911 A description of the accepted parameters follows.
915 Specify the effect type, can be either @code{in} for fade-in, or
916 @code{out} for a fade-out effect. Default is @code{in}.
918 @item start_sample, ss
919 Specify the number of the start sample for starting to apply the fade
920 effect. Default is 0.
923 Specify the number of samples for which the fade effect has to last. At
924 the end of the fade-in effect the output audio will have the same
925 volume as the input audio, at the end of the fade-out transition
926 the output audio will be silence. Default is 44100.
929 Specify the start time of the fade effect. Default is 0.
930 The value must be specified as a time duration; see
931 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
932 for the accepted syntax.
933 If set this option is used instead of @var{start_sample}.
936 Specify the duration of the fade effect. See
937 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
938 for the accepted syntax.
939 At the end of the fade-in effect the output audio will have the same
940 volume as the input audio, at the end of the fade-out transition
941 the output audio will be silence.
942 By default the duration is determined by @var{nb_samples}.
943 If set this option is used instead of @var{nb_samples}.
946 Set curve for fade transition.
948 It accepts the following values:
951 select triangular, linear slope (default)
953 select quarter of sine wave
955 select half of sine wave
957 select exponential sine wave
961 select inverted parabola
975 select inverted quarter of sine wave
977 select inverted half of sine wave
979 select double-exponential seat
981 select double-exponential sigmoid
983 select logistic sigmoid
993 Fade in first 15 seconds of audio:
999 Fade out last 25 seconds of a 900 seconds audio:
1001 afade=t=out:st=875:d=25
1006 Denoise audio samples with FFT.
1008 A description of the accepted parameters follows.
1012 Set the noise reduction in dB, allowed range is 0.01 to 97.
1013 Default value is 12 dB.
1016 Set the noise floor in dB, allowed range is -80 to -20.
1017 Default value is -50 dB.
1022 It accepts the following values:
1031 Select shellac noise.
1034 Select custom noise, defined in @code{bn} option.
1036 Default value is white noise.
1040 Set custom band noise for every one of 15 bands.
1041 Bands are separated by ' ' or '|'.
1044 Set the residual floor in dB, allowed range is -80 to -20.
1045 Default value is -38 dB.
1048 Enable noise tracking. By default is disabled.
1049 With this enabled, noise floor is automatically adjusted.
1052 Enable residual tracking. By default is disabled.
1055 Set the output mode.
1057 It accepts the following values:
1060 Pass input unchanged.
1063 Pass noise filtered out.
1068 Default value is @var{o}.
1072 @subsection Commands
1074 This filter supports the following commands:
1076 @item sample_noise, sn
1077 Start or stop measuring noise profile.
1078 Syntax for the command is : "start" or "stop" string.
1079 After measuring noise profile is stopped it will be
1080 automatically applied in filtering.
1082 @item noise_reduction, nr
1083 Change noise reduction. Argument is single float number.
1084 Syntax for the command is : "@var{noise_reduction}"
1086 @item noise_floor, nf
1087 Change noise floor. Argument is single float number.
1088 Syntax for the command is : "@var{noise_floor}"
1090 @item output_mode, om
1091 Change output mode operation.
1092 Syntax for the command is : "i", "o" or "n" string.
1096 Apply arbitrary expressions to samples in frequency domain.
1100 Set frequency domain real expression for each separate channel separated
1101 by '|'. Default is "re".
1102 If the number of input channels is greater than the number of
1103 expressions, the last specified expression is used for the remaining
1107 Set frequency domain imaginary expression for each separate channel
1108 separated by '|'. Default is "im".
1110 Each expression in @var{real} and @var{imag} can contain the following
1111 constants and functions:
1118 current frequency bin number
1121 number of available bins
1124 channel number of the current expression
1133 current real part of frequency bin of current channel
1136 current imaginary part of frequency bin of current channel
1139 Return the value of real part of frequency bin at location (@var{bin},@var{channel})
1142 Return the value of imaginary part of frequency bin at location (@var{bin},@var{channel})
1146 Set window size. Allowed range is from 16 to 131072.
1147 Default is @code{4096}
1150 Set window function. Default is @code{hann}.
1153 Set window overlap. If set to 1, the recommended overlap for selected
1154 window function will be picked. Default is @code{0.75}.
1157 @subsection Examples
1161 Leave almost only low frequencies in audio:
1163 afftfilt="'real=re * (1-clip((b/nb)*b,0,1))':imag='im * (1-clip((b/nb)*b,0,1))'"
1167 Apply robotize effect:
1169 afftfilt="real='hypot(re,im)*sin(0)':imag='hypot(re,im)*cos(0)':win_size=512:overlap=0.75"
1173 Apply whisper effect:
1175 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"
1182 Apply an arbitrary Frequency Impulse Response filter.
1184 This filter is designed for applying long FIR filters,
1185 up to 60 seconds long.
1187 It can be used as component for digital crossover filters,
1188 room equalization, cross talk cancellation, wavefield synthesis,
1189 auralization, ambiophonics, ambisonics and spatialization.
1191 This filter uses the second stream as FIR coefficients.
1192 If the second stream holds a single channel, it will be used
1193 for all input channels in the first stream, otherwise
1194 the number of channels in the second stream must be same as
1195 the number of channels in the first stream.
1197 It accepts the following parameters:
1201 Set dry gain. This sets input gain.
1204 Set wet gain. This sets final output gain.
1207 Set Impulse Response filter length. Default is 1, which means whole IR is processed.
1210 Enable applying gain measured from power of IR.
1212 Set which approach to use for auto gain measurement.
1216 Do not apply any gain.
1219 select peak gain, very conservative approach. This is default value.
1222 select DC gain, limited application.
1225 select gain to noise approach, this is most popular one.
1229 Set gain to be applied to IR coefficients before filtering.
1230 Allowed range is 0 to 1. This gain is applied after any gain applied with @var{gtype} option.
1233 Set format of IR stream. Can be @code{mono} or @code{input}.
1234 Default is @code{input}.
1237 Set max allowed Impulse Response filter duration in seconds. Default is 30 seconds.
1238 Allowed range is 0.1 to 60 seconds.
1241 Show IR frequency response, magnitude(magenta), phase(green) and group delay(yellow) in additional video stream.
1242 By default it is disabled.
1245 Set for which IR channel to display frequency response. By default is first channel
1246 displayed. This option is used only when @var{response} is enabled.
1249 Set video stream size. This option is used only when @var{response} is enabled.
1252 Set video stream frame rate. This option is used only when @var{response} is enabled.
1255 Set minimal partition size used for convolution. Default is @var{8192}.
1256 Allowed range is from @var{8} to @var{32768}.
1257 Lower values decreases latency at cost of higher CPU usage.
1260 Set maximal partition size used for convolution. Default is @var{8192}.
1261 Allowed range is from @var{8} to @var{32768}.
1262 Lower values may increase CPU usage.
1265 @subsection Examples
1269 Apply reverb to stream using mono IR file as second input, complete command using ffmpeg:
1271 ffmpeg -i input.wav -i middle_tunnel_1way_mono.wav -lavfi afir output.wav
1278 Set output format constraints for the input audio. The framework will
1279 negotiate the most appropriate format to minimize conversions.
1281 It accepts the following parameters:
1285 A '|'-separated list of requested sample formats.
1288 A '|'-separated list of requested sample rates.
1290 @item channel_layouts
1291 A '|'-separated list of requested channel layouts.
1293 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
1294 for the required syntax.
1297 If a parameter is omitted, all values are allowed.
1299 Force the output to either unsigned 8-bit or signed 16-bit stereo
1301 aformat=sample_fmts=u8|s16:channel_layouts=stereo
1306 A gate is mainly used to reduce lower parts of a signal. This kind of signal
1307 processing reduces disturbing noise between useful signals.
1309 Gating is done by detecting the volume below a chosen level @var{threshold}
1310 and dividing it by the factor set with @var{ratio}. The bottom of the noise
1311 floor is set via @var{range}. Because an exact manipulation of the signal
1312 would cause distortion of the waveform the reduction can be levelled over
1313 time. This is done by setting @var{attack} and @var{release}.
1315 @var{attack} determines how long the signal has to fall below the threshold
1316 before any reduction will occur and @var{release} sets the time the signal
1317 has to rise above the threshold to reduce the reduction again.
1318 Shorter signals than the chosen attack time will be left untouched.
1322 Set input level before filtering.
1323 Default is 1. Allowed range is from 0.015625 to 64.
1326 Set the mode of operation. Can be @code{upward} or @code{downward}.
1327 Default is @code{downward}. If set to @code{upward} mode, higher parts of signal
1328 will be amplified, expanding dynamic range in upward direction.
1329 Otherwise, in case of @code{downward} lower parts of signal will be reduced.
1332 Set the level of gain reduction when the signal is below the threshold.
1333 Default is 0.06125. Allowed range is from 0 to 1.
1334 Setting this to 0 disables reduction and then filter behaves like expander.
1337 If a signal rises above this level the gain reduction is released.
1338 Default is 0.125. Allowed range is from 0 to 1.
1341 Set a ratio by which the signal is reduced.
1342 Default is 2. Allowed range is from 1 to 9000.
1345 Amount of milliseconds the signal has to rise above the threshold before gain
1347 Default is 20 milliseconds. Allowed range is from 0.01 to 9000.
1350 Amount of milliseconds the signal has to fall below the threshold before the
1351 reduction is increased again. Default is 250 milliseconds.
1352 Allowed range is from 0.01 to 9000.
1355 Set amount of amplification of signal after processing.
1356 Default is 1. Allowed range is from 1 to 64.
1359 Curve the sharp knee around the threshold to enter gain reduction more softly.
1360 Default is 2.828427125. Allowed range is from 1 to 8.
1363 Choose if exact signal should be taken for detection or an RMS like one.
1364 Default is @code{rms}. Can be @code{peak} or @code{rms}.
1367 Choose if the average level between all channels or the louder channel affects
1369 Default is @code{average}. Can be @code{average} or @code{maximum}.
1374 Apply an arbitrary Infinite Impulse Response filter.
1376 It accepts the following parameters:
1380 Set numerator/zeros coefficients.
1383 Set denominator/poles coefficients.
1395 Set coefficients format.
1401 Z-plane zeros/poles, cartesian (default)
1403 Z-plane zeros/poles, polar radians
1405 Z-plane zeros/poles, polar degrees
1409 Set kind of processing.
1410 Can be @code{d} - direct or @code{s} - serial cascading. Default is @code{s}.
1413 Set filtering precision.
1417 double-precision floating-point (default)
1419 single-precision floating-point
1427 How much to use filtered signal in output. Default is 1.
1428 Range is between 0 and 1.
1431 Show IR frequency response, magnitude(magenta), phase(green) and group delay(yellow) in additional video stream.
1432 By default it is disabled.
1435 Set for which IR channel to display frequency response. By default is first channel
1436 displayed. This option is used only when @var{response} is enabled.
1439 Set video stream size. This option is used only when @var{response} is enabled.
1442 Coefficients in @code{tf} format are separated by spaces and are in ascending
1445 Coefficients in @code{zp} format are separated by spaces and order of coefficients
1446 doesn't matter. Coefficients in @code{zp} format are complex numbers with @var{i}
1449 Different coefficients and gains can be provided for every channel, in such case
1450 use '|' to separate coefficients or gains. Last provided coefficients will be
1451 used for all remaining channels.
1453 @subsection Examples
1457 Apply 2 pole elliptic notch at around 5000Hz for 48000 Hz sample rate:
1459 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
1463 Same as above but in @code{zp} format:
1465 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
1471 The limiter prevents an input signal from rising over a desired threshold.
1472 This limiter uses lookahead technology to prevent your signal from distorting.
1473 It means that there is a small delay after the signal is processed. Keep in mind
1474 that the delay it produces is the attack time you set.
1476 The filter accepts the following options:
1480 Set input gain. Default is 1.
1483 Set output gain. Default is 1.
1486 Don't let signals above this level pass the limiter. Default is 1.
1489 The limiter will reach its attenuation level in this amount of time in
1490 milliseconds. Default is 5 milliseconds.
1493 Come back from limiting to attenuation 1.0 in this amount of milliseconds.
1494 Default is 50 milliseconds.
1497 When gain reduction is always needed ASC takes care of releasing to an
1498 average reduction level rather than reaching a reduction of 0 in the release
1502 Select how much the release time is affected by ASC, 0 means nearly no changes
1503 in release time while 1 produces higher release times.
1506 Auto level output signal. Default is enabled.
1507 This normalizes audio back to 0dB if enabled.
1510 Depending on picked setting it is recommended to upsample input 2x or 4x times
1511 with @ref{aresample} before applying this filter.
1515 Apply a two-pole all-pass filter with central frequency (in Hz)
1516 @var{frequency}, and filter-width @var{width}.
1517 An all-pass filter changes the audio's frequency to phase relationship
1518 without changing its frequency to amplitude relationship.
1520 The filter accepts the following options:
1524 Set frequency in Hz.
1527 Set method to specify band-width of filter.
1542 Specify the band-width of a filter in width_type units.
1545 How much to use filtered signal in output. Default is 1.
1546 Range is between 0 and 1.
1549 Specify which channels to filter, by default all available are filtered.
1552 @subsection Commands
1554 This filter supports the following commands:
1557 Change allpass frequency.
1558 Syntax for the command is : "@var{frequency}"
1561 Change allpass width_type.
1562 Syntax for the command is : "@var{width_type}"
1565 Change allpass width.
1566 Syntax for the command is : "@var{width}"
1570 Syntax for the command is : "@var{mix}"
1577 The filter accepts the following options:
1581 Set the number of loops. Setting this value to -1 will result in infinite loops.
1585 Set maximal number of samples. Default is 0.
1588 Set first sample of loop. Default is 0.
1594 Merge two or more audio streams into a single multi-channel stream.
1596 The filter accepts the following options:
1601 Set the number of inputs. Default is 2.
1605 If the channel layouts of the inputs are disjoint, and therefore compatible,
1606 the channel layout of the output will be set accordingly and the channels
1607 will be reordered as necessary. If the channel layouts of the inputs are not
1608 disjoint, the output will have all the channels of the first input then all
1609 the channels of the second input, in that order, and the channel layout of
1610 the output will be the default value corresponding to the total number of
1613 For example, if the first input is in 2.1 (FL+FR+LF) and the second input
1614 is FC+BL+BR, then the output will be in 5.1, with the channels in the
1615 following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the
1616 first input, b1 is the first channel of the second input).
1618 On the other hand, if both input are in stereo, the output channels will be
1619 in the default order: a1, a2, b1, b2, and the channel layout will be
1620 arbitrarily set to 4.0, which may or may not be the expected value.
1622 All inputs must have the same sample rate, and format.
1624 If inputs do not have the same duration, the output will stop with the
1627 @subsection Examples
1631 Merge two mono files into a stereo stream:
1633 amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge
1637 Multiple merges assuming 1 video stream and 6 audio streams in @file{input.mkv}:
1639 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
1645 Mixes multiple audio inputs into a single output.
1647 Note that this filter only supports float samples (the @var{amerge}
1648 and @var{pan} audio filters support many formats). If the @var{amix}
1649 input has integer samples then @ref{aresample} will be automatically
1650 inserted to perform the conversion to float samples.
1654 ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT
1656 will mix 3 input audio streams to a single output with the same duration as the
1657 first input and a dropout transition time of 3 seconds.
1659 It accepts the following parameters:
1663 The number of inputs. If unspecified, it defaults to 2.
1666 How to determine the end-of-stream.
1670 The duration of the longest input. (default)
1673 The duration of the shortest input.
1676 The duration of the first input.
1680 @item dropout_transition
1681 The transition time, in seconds, for volume renormalization when an input
1682 stream ends. The default value is 2 seconds.
1685 Specify weight of each input audio stream as sequence.
1686 Each weight is separated by space. By default all inputs have same weight.
1691 Multiply first audio stream with second audio stream and store result
1692 in output audio stream. Multiplication is done by multiplying each
1693 sample from first stream with sample at same position from second stream.
1695 With this element-wise multiplication one can create amplitude fades and
1696 amplitude modulations.
1698 @section anequalizer
1700 High-order parametric multiband equalizer for each channel.
1702 It accepts the following parameters:
1706 This option string is in format:
1707 "c@var{chn} f=@var{cf} w=@var{w} g=@var{g} t=@var{f} | ..."
1708 Each equalizer band is separated by '|'.
1712 Set channel number to which equalization will be applied.
1713 If input doesn't have that channel the entry is ignored.
1716 Set central frequency for band.
1717 If input doesn't have that frequency the entry is ignored.
1720 Set band width in hertz.
1723 Set band gain in dB.
1726 Set filter type for band, optional, can be:
1730 Butterworth, this is default.
1741 With this option activated frequency response of anequalizer is displayed
1745 Set video stream size. Only useful if curves option is activated.
1748 Set max gain that will be displayed. Only useful if curves option is activated.
1749 Setting this to a reasonable value makes it possible to display gain which is derived from
1750 neighbour bands which are too close to each other and thus produce higher gain
1751 when both are activated.
1754 Set frequency scale used to draw frequency response in video output.
1755 Can be linear or logarithmic. Default is logarithmic.
1758 Set color for each channel curve which is going to be displayed in video stream.
1759 This is list of color names separated by space or by '|'.
1760 Unrecognised or missing colors will be replaced by white color.
1763 @subsection Examples
1767 Lower gain by 10 of central frequency 200Hz and width 100 Hz
1768 for first 2 channels using Chebyshev type 1 filter:
1770 anequalizer=c0 f=200 w=100 g=-10 t=1|c1 f=200 w=100 g=-10 t=1
1774 @subsection Commands
1776 This filter supports the following commands:
1779 Alter existing filter parameters.
1780 Syntax for the commands is : "@var{fN}|f=@var{freq}|w=@var{width}|g=@var{gain}"
1782 @var{fN} is existing filter number, starting from 0, if no such filter is available
1784 @var{freq} set new frequency parameter.
1785 @var{width} set new width parameter in herz.
1786 @var{gain} set new gain parameter in dB.
1788 Full filter invocation with asendcmd may look like this:
1789 asendcmd=c='4.0 anequalizer change 0|f=200|w=50|g=1',anequalizer=...
1794 Reduce broadband noise in audio samples using Non-Local Means algorithm.
1796 Each sample is adjusted by looking for other samples with similar contexts. This
1797 context similarity is defined by comparing their surrounding patches of size
1798 @option{p}. Patches are searched in an area of @option{r} around the sample.
1800 The filter accepts the following options:
1804 Set denoising strength. Allowed range is from 0.00001 to 10. Default value is 0.00001.
1807 Set patch radius duration. Allowed range is from 1 to 100 milliseconds.
1808 Default value is 2 milliseconds.
1811 Set research radius duration. Allowed range is from 2 to 300 milliseconds.
1812 Default value is 6 milliseconds.
1815 Set the output mode.
1817 It accepts the following values:
1820 Pass input unchanged.
1823 Pass noise filtered out.
1828 Default value is @var{o}.
1832 Set smooth factor. Default value is @var{11}. Allowed range is from @var{1} to @var{15}.
1835 @subsection Commands
1837 This filter supports the following commands:
1840 Change denoise strength. Argument is single float number.
1841 Syntax for the command is : "@var{s}"
1845 Syntax for the command is : "i", "o" or "n" string.
1849 Apply Normalized Least-Mean-Squares algorithm to the first audio stream using the second audio stream.
1851 This adaptive filter is used to mimic a desired filter by finding the filter coefficients that
1852 relate to producing the least mean square of the error signal (difference between the desired,
1853 2nd input audio stream and the actual signal, the 1st input audio stream).
1855 A description of the accepted options follows.
1868 Set the filter leakage.
1871 It accepts the following values:
1880 Pass filtered samples.
1883 Pass difference between desired and filtered samples.
1885 Default value is @var{o}.
1889 @subsection Examples
1893 One of many usages of this filter is noise reduction, input audio is filtered
1894 with same samples that are delayed by fixed amount, one such example for stereo audio is:
1896 asplit[a][b],[a]adelay=32S|32S[a],[b][a]anlms=order=128:leakage=0.0005:mu=.5:out_mode=o
1900 @subsection Commands
1902 This filter supports the same commands as options, excluding option @code{order}.
1906 Pass the audio source unchanged to the output.
1910 Pad the end of an audio stream with silence.
1912 This can be used together with @command{ffmpeg} @option{-shortest} to
1913 extend audio streams to the same length as the video stream.
1915 A description of the accepted options follows.
1919 Set silence packet size. Default value is 4096.
1922 Set the number of samples of silence to add to the end. After the
1923 value is reached, the stream is terminated. This option is mutually
1924 exclusive with @option{whole_len}.
1927 Set the minimum total number of samples in the output audio stream. If
1928 the value is longer than the input audio length, silence is added to
1929 the end, until the value is reached. This option is mutually exclusive
1930 with @option{pad_len}.
1933 Specify the duration of samples of silence to add. See
1934 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
1935 for the accepted syntax. Used only if set to non-zero value.
1938 Specify the minimum total duration in the output audio stream. See
1939 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
1940 for the accepted syntax. Used only if set to non-zero value. If the value is longer than
1941 the input audio length, silence is added to the end, until the value is reached.
1942 This option is mutually exclusive with @option{pad_dur}
1945 If neither the @option{pad_len} nor the @option{whole_len} nor @option{pad_dur}
1946 nor @option{whole_dur} option is set, the filter will add silence to the end of
1947 the input stream indefinitely.
1949 @subsection Examples
1953 Add 1024 samples of silence to the end of the input:
1959 Make sure the audio output will contain at least 10000 samples, pad
1960 the input with silence if required:
1962 apad=whole_len=10000
1966 Use @command{ffmpeg} to pad the audio input with silence, so that the
1967 video stream will always result the shortest and will be converted
1968 until the end in the output file when using the @option{shortest}
1971 ffmpeg -i VIDEO -i AUDIO -filter_complex "[1:0]apad" -shortest OUTPUT
1976 Add a phasing effect to the input audio.
1978 A phaser filter creates series of peaks and troughs in the frequency spectrum.
1979 The position of the peaks and troughs are modulated so that they vary over time, creating a sweeping effect.
1981 A description of the accepted parameters follows.
1985 Set input gain. Default is 0.4.
1988 Set output gain. Default is 0.74
1991 Set delay in milliseconds. Default is 3.0.
1994 Set decay. Default is 0.4.
1997 Set modulation speed in Hz. Default is 0.5.
2000 Set modulation type. Default is triangular.
2002 It accepts the following values:
2011 Audio pulsator is something between an autopanner and a tremolo.
2012 But it can produce funny stereo effects as well. Pulsator changes the volume
2013 of the left and right channel based on a LFO (low frequency oscillator) with
2014 different waveforms and shifted phases.
2015 This filter have the ability to define an offset between left and right
2016 channel. An offset of 0 means that both LFO shapes match each other.
2017 The left and right channel are altered equally - a conventional tremolo.
2018 An offset of 50% means that the shape of the right channel is exactly shifted
2019 in phase (or moved backwards about half of the frequency) - pulsator acts as
2020 an autopanner. At 1 both curves match again. Every setting in between moves the
2021 phase shift gapless between all stages and produces some "bypassing" sounds with
2022 sine and triangle waveforms. The more you set the offset near 1 (starting from
2023 the 0.5) the faster the signal passes from the left to the right speaker.
2025 The filter accepts the following options:
2029 Set input gain. By default it is 1. Range is [0.015625 - 64].
2032 Set output gain. By default it is 1. Range is [0.015625 - 64].
2035 Set waveform shape the LFO will use. Can be one of: sine, triangle, square,
2036 sawup or sawdown. Default is sine.
2039 Set modulation. Define how much of original signal is affected by the LFO.
2042 Set left channel offset. Default is 0. Allowed range is [0 - 1].
2045 Set right channel offset. Default is 0.5. Allowed range is [0 - 1].
2048 Set pulse width. Default is 1. Allowed range is [0 - 2].
2051 Set possible timing mode. Can be one of: bpm, ms or hz. Default is hz.
2054 Set bpm. Default is 120. Allowed range is [30 - 300]. Only used if timing
2058 Set ms. Default is 500. Allowed range is [10 - 2000]. Only used if timing
2062 Set frequency in Hz. Default is 2. Allowed range is [0.01 - 100]. Only used
2063 if timing is set to hz.
2069 Resample the input audio to the specified parameters, using the
2070 libswresample library. If none are specified then the filter will
2071 automatically convert between its input and output.
2073 This filter is also able to stretch/squeeze the audio data to make it match
2074 the timestamps or to inject silence / cut out audio to make it match the
2075 timestamps, do a combination of both or do neither.
2077 The filter accepts the syntax
2078 [@var{sample_rate}:]@var{resampler_options}, where @var{sample_rate}
2079 expresses a sample rate and @var{resampler_options} is a list of
2080 @var{key}=@var{value} pairs, separated by ":". See the
2081 @ref{Resampler Options,,"Resampler Options" section in the
2082 ffmpeg-resampler(1) manual,ffmpeg-resampler}
2083 for the complete list of supported options.
2085 @subsection Examples
2089 Resample the input audio to 44100Hz:
2095 Stretch/squeeze samples to the given timestamps, with a maximum of 1000
2096 samples per second compensation:
2098 aresample=async=1000
2104 Reverse an audio clip.
2106 Warning: This filter requires memory to buffer the entire clip, so trimming
2109 @subsection Examples
2113 Take the first 5 seconds of a clip, and reverse it.
2115 atrim=end=5,areverse
2119 @section asetnsamples
2121 Set the number of samples per each output audio frame.
2123 The last output packet may contain a different number of samples, as
2124 the filter will flush all the remaining samples when the input audio
2127 The filter accepts the following options:
2131 @item nb_out_samples, n
2132 Set the number of frames per each output audio frame. The number is
2133 intended as the number of samples @emph{per each channel}.
2134 Default value is 1024.
2137 If set to 1, the filter will pad the last audio frame with zeroes, so
2138 that the last frame will contain the same number of samples as the
2139 previous ones. Default value is 1.
2142 For example, to set the number of per-frame samples to 1234 and
2143 disable padding for the last frame, use:
2145 asetnsamples=n=1234:p=0
2150 Set the sample rate without altering the PCM data.
2151 This will result in a change of speed and pitch.
2153 The filter accepts the following options:
2156 @item sample_rate, r
2157 Set the output sample rate. Default is 44100 Hz.
2162 Show a line containing various information for each input audio frame.
2163 The input audio is not modified.
2165 The shown line contains a sequence of key/value pairs of the form
2166 @var{key}:@var{value}.
2168 The following values are shown in the output:
2172 The (sequential) number of the input frame, starting from 0.
2175 The presentation timestamp of the input frame, in time base units; the time base
2176 depends on the filter input pad, and is usually 1/@var{sample_rate}.
2179 The presentation timestamp of the input frame in seconds.
2182 position of the frame in the input stream, -1 if this information in
2183 unavailable and/or meaningless (for example in case of synthetic audio)
2192 The sample rate for the audio frame.
2195 The number of samples (per channel) in the frame.
2198 The Adler-32 checksum (printed in hexadecimal) of the audio data. For planar
2199 audio, the data is treated as if all the planes were concatenated.
2201 @item plane_checksums
2202 A list of Adler-32 checksums for each data plane.
2206 Apply audio soft clipping.
2208 Soft clipping is a type of distortion effect where the amplitude of a signal is saturated
2209 along a smooth curve, rather than the abrupt shape of hard-clipping.
2211 This filter accepts the following options:
2215 Set type of soft-clipping.
2217 It accepts the following values:
2229 Set additional parameter which controls sigmoid function.
2233 Automatic Speech Recognition
2235 This filter uses PocketSphinx for speech recognition. To enable
2236 compilation of this filter, you need to configure FFmpeg with
2237 @code{--enable-pocketsphinx}.
2239 It accepts the following options:
2243 Set sampling rate of input audio. Defaults is @code{16000}.
2244 This need to match speech models, otherwise one will get poor results.
2247 Set dictionary containing acoustic model files.
2250 Set pronunciation dictionary.
2253 Set language model file.
2256 Set language model set.
2259 Set which language model to use.
2262 Set output for log messages.
2265 The filter exports recognized speech as the frame metadata @code{lavfi.asr.text}.
2270 Display time domain statistical information about the audio channels.
2271 Statistics are calculated and displayed for each audio channel and,
2272 where applicable, an overall figure is also given.
2274 It accepts the following option:
2277 Short window length in seconds, used for peak and trough RMS measurement.
2278 Default is @code{0.05} (50 milliseconds). Allowed range is @code{[0.01 - 10]}.
2282 Set metadata injection. All the metadata keys are prefixed with @code{lavfi.astats.X},
2283 where @code{X} is channel number starting from 1 or string @code{Overall}. Default is
2286 Available keys for each channel are:
2328 For example full key look like this @code{lavfi.astats.1.DC_offset} or
2329 this @code{lavfi.astats.Overall.Peak_count}.
2331 For description what each key means read below.
2334 Set number of frame after which stats are going to be recalculated.
2335 Default is disabled.
2337 @item measure_perchannel
2338 Select the entries which need to be measured per channel. The metadata keys can
2339 be used as flags, default is @option{all} which measures everything.
2340 @option{none} disables all per channel measurement.
2342 @item measure_overall
2343 Select the entries which need to be measured overall. The metadata keys can
2344 be used as flags, default is @option{all} which measures everything.
2345 @option{none} disables all overall measurement.
2349 A description of each shown parameter follows:
2353 Mean amplitude displacement from zero.
2356 Minimal sample level.
2359 Maximal sample level.
2361 @item Min difference
2362 Minimal difference between two consecutive samples.
2364 @item Max difference
2365 Maximal difference between two consecutive samples.
2367 @item Mean difference
2368 Mean difference between two consecutive samples.
2369 The average of each difference between two consecutive samples.
2371 @item RMS difference
2372 Root Mean Square difference between two consecutive samples.
2376 Standard peak and RMS level measured in dBFS.
2380 Peak and trough values for RMS level measured over a short window.
2383 Standard ratio of peak to RMS level (note: not in dB).
2386 Flatness (i.e. consecutive samples with the same value) of the signal at its peak levels
2387 (i.e. either @var{Min level} or @var{Max level}).
2390 Number of occasions (not the number of samples) that the signal attained either
2391 @var{Min level} or @var{Max level}.
2394 Overall bit depth of audio. Number of bits used for each sample.
2397 Measured dynamic range of audio in dB.
2399 @item Zero crossings
2400 Number of points where the waveform crosses the zero level axis.
2402 @item Zero crossings rate
2403 Rate of Zero crossings and number of audio samples.
2410 The filter accepts exactly one parameter, the audio tempo. If not
2411 specified then the filter will assume nominal 1.0 tempo. Tempo must
2412 be in the [0.5, 100.0] range.
2414 Note that tempo greater than 2 will skip some samples rather than
2415 blend them in. If for any reason this is a concern it is always
2416 possible to daisy-chain several instances of atempo to achieve the
2417 desired product tempo.
2419 @subsection Examples
2423 Slow down audio to 80% tempo:
2429 To speed up audio to 300% tempo:
2435 To speed up audio to 300% tempo by daisy-chaining two atempo instances:
2437 atempo=sqrt(3),atempo=sqrt(3)
2441 @subsection Commands
2443 This filter supports the following commands:
2446 Change filter tempo scale factor.
2447 Syntax for the command is : "@var{tempo}"
2452 Trim the input so that the output contains one continuous subpart of the input.
2454 It accepts the following parameters:
2457 Timestamp (in seconds) of the start of the section to keep. I.e. the audio
2458 sample with the timestamp @var{start} will be the first sample in the output.
2461 Specify time of the first audio sample that will be dropped, i.e. the
2462 audio sample immediately preceding the one with the timestamp @var{end} will be
2463 the last sample in the output.
2466 Same as @var{start}, except this option sets the start timestamp in samples
2470 Same as @var{end}, except this option sets the end timestamp in samples instead
2474 The maximum duration of the output in seconds.
2477 The number of the first sample that should be output.
2480 The number of the first sample that should be dropped.
2483 @option{start}, @option{end}, and @option{duration} are expressed as time
2484 duration specifications; see
2485 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}.
2487 Note that the first two sets of the start/end options and the @option{duration}
2488 option look at the frame timestamp, while the _sample options simply count the
2489 samples that pass through the filter. So start/end_pts and start/end_sample will
2490 give different results when the timestamps are wrong, inexact or do not start at
2491 zero. Also note that this filter does not modify the timestamps. If you wish
2492 to have the output timestamps start at zero, insert the asetpts filter after the
2495 If multiple start or end options are set, this filter tries to be greedy and
2496 keep all samples that match at least one of the specified constraints. To keep
2497 only the part that matches all the constraints at once, chain multiple atrim
2500 The defaults are such that all the input is kept. So it is possible to set e.g.
2501 just the end values to keep everything before the specified time.
2506 Drop everything except the second minute of input:
2508 ffmpeg -i INPUT -af atrim=60:120
2512 Keep only the first 1000 samples:
2514 ffmpeg -i INPUT -af atrim=end_sample=1000
2521 Apply a two-pole Butterworth band-pass filter with central
2522 frequency @var{frequency}, and (3dB-point) band-width width.
2523 The @var{csg} option selects a constant skirt gain (peak gain = Q)
2524 instead of the default: constant 0dB peak gain.
2525 The filter roll off at 6dB per octave (20dB per decade).
2527 The filter accepts the following options:
2531 Set the filter's central frequency. Default is @code{3000}.
2534 Constant skirt gain if set to 1. Defaults to 0.
2537 Set method to specify band-width of filter.
2552 Specify the band-width of a filter in width_type units.
2555 How much to use filtered signal in output. Default is 1.
2556 Range is between 0 and 1.
2559 Specify which channels to filter, by default all available are filtered.
2562 @subsection Commands
2564 This filter supports the following commands:
2567 Change bandpass frequency.
2568 Syntax for the command is : "@var{frequency}"
2571 Change bandpass width_type.
2572 Syntax for the command is : "@var{width_type}"
2575 Change bandpass width.
2576 Syntax for the command is : "@var{width}"
2579 Change bandpass mix.
2580 Syntax for the command is : "@var{mix}"
2585 Apply a two-pole Butterworth band-reject filter with central
2586 frequency @var{frequency}, and (3dB-point) band-width @var{width}.
2587 The filter roll off at 6dB per octave (20dB per decade).
2589 The filter accepts the following options:
2593 Set the filter's central frequency. Default is @code{3000}.
2596 Set method to specify band-width of filter.
2611 Specify the band-width of a filter in width_type units.
2614 How much to use filtered signal in output. Default is 1.
2615 Range is between 0 and 1.
2618 Specify which channels to filter, by default all available are filtered.
2621 @subsection Commands
2623 This filter supports the following commands:
2626 Change bandreject frequency.
2627 Syntax for the command is : "@var{frequency}"
2630 Change bandreject width_type.
2631 Syntax for the command is : "@var{width_type}"
2634 Change bandreject width.
2635 Syntax for the command is : "@var{width}"
2638 Change bandreject mix.
2639 Syntax for the command is : "@var{mix}"
2642 @section bass, lowshelf
2644 Boost or cut the bass (lower) frequencies of the audio using a two-pole
2645 shelving filter with a response similar to that of a standard
2646 hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
2648 The filter accepts the following options:
2652 Give the gain at 0 Hz. Its useful range is about -20
2653 (for a large cut) to +20 (for a large boost).
2654 Beware of clipping when using a positive gain.
2657 Set the filter's central frequency and so can be used
2658 to extend or reduce the frequency range to be boosted or cut.
2659 The default value is @code{100} Hz.
2662 Set method to specify band-width of filter.
2677 Determine how steep is the filter's shelf transition.
2680 How much to use filtered signal in output. Default is 1.
2681 Range is between 0 and 1.
2684 Specify which channels to filter, by default all available are filtered.
2687 @subsection Commands
2689 This filter supports the following commands:
2692 Change bass frequency.
2693 Syntax for the command is : "@var{frequency}"
2696 Change bass width_type.
2697 Syntax for the command is : "@var{width_type}"
2701 Syntax for the command is : "@var{width}"
2705 Syntax for the command is : "@var{gain}"
2709 Syntax for the command is : "@var{mix}"
2714 Apply a biquad IIR filter with the given coefficients.
2715 Where @var{b0}, @var{b1}, @var{b2} and @var{a0}, @var{a1}, @var{a2}
2716 are the numerator and denominator coefficients respectively.
2717 and @var{channels}, @var{c} specify which channels to filter, by default all
2718 available are filtered.
2720 @subsection Commands
2722 This filter supports the following commands:
2730 Change biquad parameter.
2731 Syntax for the command is : "@var{value}"
2734 How much to use filtered signal in output. Default is 1.
2735 Range is between 0 and 1.
2739 Bauer stereo to binaural transformation, which improves headphone listening of
2740 stereo audio records.
2742 To enable compilation of this filter you need to configure FFmpeg with
2743 @code{--enable-libbs2b}.
2745 It accepts the following parameters:
2749 Pre-defined crossfeed level.
2753 Default level (fcut=700, feed=50).
2756 Chu Moy circuit (fcut=700, feed=60).
2759 Jan Meier circuit (fcut=650, feed=95).
2764 Cut frequency (in Hz).
2773 Remap input channels to new locations.
2775 It accepts the following parameters:
2778 Map channels from input to output. The argument is a '|'-separated list of
2779 mappings, each in the @code{@var{in_channel}-@var{out_channel}} or
2780 @var{in_channel} form. @var{in_channel} can be either the name of the input
2781 channel (e.g. FL for front left) or its index in the input channel layout.
2782 @var{out_channel} is the name of the output channel or its index in the output
2783 channel layout. If @var{out_channel} is not given then it is implicitly an
2784 index, starting with zero and increasing by one for each mapping.
2786 @item channel_layout
2787 The channel layout of the output stream.
2790 If no mapping is present, the filter will implicitly map input channels to
2791 output channels, preserving indices.
2793 @subsection Examples
2797 For example, assuming a 5.1+downmix input MOV file,
2799 ffmpeg -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav
2801 will create an output WAV file tagged as stereo from the downmix channels of
2805 To fix a 5.1 WAV improperly encoded in AAC's native channel order
2807 ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:5.1' out.wav
2811 @section channelsplit
2813 Split each channel from an input audio stream into a separate output stream.
2815 It accepts the following parameters:
2817 @item channel_layout
2818 The channel layout of the input stream. The default is "stereo".
2820 A channel layout describing the channels to be extracted as separate output streams
2821 or "all" to extract each input channel as a separate stream. The default is "all".
2823 Choosing channels not present in channel layout in the input will result in an error.
2826 @subsection Examples
2830 For example, assuming a stereo input MP3 file,
2832 ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv
2834 will create an output Matroska file with two audio streams, one containing only
2835 the left channel and the other the right channel.
2838 Split a 5.1 WAV file into per-channel files:
2840 ffmpeg -i in.wav -filter_complex
2841 'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]'
2842 -map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]'
2843 front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]'
2848 Extract only LFE from a 5.1 WAV file:
2850 ffmpeg -i in.wav -filter_complex 'channelsplit=channel_layout=5.1:channels=LFE[LFE]'
2851 -map '[LFE]' lfe.wav
2856 Add a chorus effect to the audio.
2858 Can make a single vocal sound like a chorus, but can also be applied to instrumentation.
2860 Chorus resembles an echo effect with a short delay, but whereas with echo the delay is
2861 constant, with chorus, it is varied using using sinusoidal or triangular modulation.
2862 The modulation depth defines the range the modulated delay is played before or after
2863 the delay. Hence the delayed sound will sound slower or faster, that is the delayed
2864 sound tuned around the original one, like in a chorus where some vocals are slightly
2867 It accepts the following parameters:
2870 Set input gain. Default is 0.4.
2873 Set output gain. Default is 0.4.
2876 Set delays. A typical delay is around 40ms to 60ms.
2888 @subsection Examples
2894 chorus=0.7:0.9:55:0.4:0.25:2
2900 chorus=0.6:0.9:50|60:0.4|0.32:0.25|0.4:2|1.3
2904 Fuller sounding chorus with three delays:
2906 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
2911 Compress or expand the audio's dynamic range.
2913 It accepts the following parameters:
2919 A list of times in seconds for each channel over which the instantaneous level
2920 of the input signal is averaged to determine its volume. @var{attacks} refers to
2921 increase of volume and @var{decays} refers to decrease of volume. For most
2922 situations, the attack time (response to the audio getting louder) should be
2923 shorter than the decay time, because the human ear is more sensitive to sudden
2924 loud audio than sudden soft audio. A typical value for attack is 0.3 seconds and
2925 a typical value for decay is 0.8 seconds.
2926 If specified number of attacks & decays is lower than number of channels, the last
2927 set attack/decay will be used for all remaining channels.
2930 A list of points for the transfer function, specified in dB relative to the
2931 maximum possible signal amplitude. Each key points list must be defined using
2932 the following syntax: @code{x0/y0|x1/y1|x2/y2|....} or
2933 @code{x0/y0 x1/y1 x2/y2 ....}
2935 The input values must be in strictly increasing order but the transfer function
2936 does not have to be monotonically rising. The point @code{0/0} is assumed but
2937 may be overridden (by @code{0/out-dBn}). Typical values for the transfer
2938 function are @code{-70/-70|-60/-20|1/0}.
2941 Set the curve radius in dB for all joints. It defaults to 0.01.
2944 Set the additional gain in dB to be applied at all points on the transfer
2945 function. This allows for easy adjustment of the overall gain.
2949 Set an initial volume, in dB, to be assumed for each channel when filtering
2950 starts. This permits the user to supply a nominal level initially, so that, for
2951 example, a very large gain is not applied to initial signal levels before the
2952 companding has begun to operate. A typical value for audio which is initially
2953 quiet is -90 dB. It defaults to 0.
2956 Set a delay, in seconds. The input audio is analyzed immediately, but audio is
2957 delayed before being fed to the volume adjuster. Specifying a delay
2958 approximately equal to the attack/decay times allows the filter to effectively
2959 operate in predictive rather than reactive mode. It defaults to 0.
2963 @subsection Examples
2967 Make music with both quiet and loud passages suitable for listening to in a
2970 compand=.3|.3:1|1:-90/-60|-60/-40|-40/-30|-20/-20:6:0:-90:0.2
2973 Another example for audio with whisper and explosion parts:
2975 compand=0|0:1|1:-90/-900|-70/-70|-30/-9|0/-3:6:0:0:0
2979 A noise gate for when the noise is at a lower level than the signal:
2981 compand=.1|.1:.2|.2:-900/-900|-50.1/-900|-50/-50:.01:0:-90:.1
2985 Here is another noise gate, this time for when the noise is at a higher level
2986 than the signal (making it, in some ways, similar to squelch):
2988 compand=.1|.1:.1|.1:-45.1/-45.1|-45/-900|0/-900:.01:45:-90:.1
2992 2:1 compression starting at -6dB:
2994 compand=points=-80/-80|-6/-6|0/-3.8|20/3.5
2998 2:1 compression starting at -9dB:
3000 compand=points=-80/-80|-9/-9|0/-5.3|20/2.9
3004 2:1 compression starting at -12dB:
3006 compand=points=-80/-80|-12/-12|0/-6.8|20/1.9
3010 2:1 compression starting at -18dB:
3012 compand=points=-80/-80|-18/-18|0/-9.8|20/0.7
3016 3:1 compression starting at -15dB:
3018 compand=points=-80/-80|-15/-15|0/-10.8|20/-5.2
3024 compand=points=-80/-105|-62/-80|-15.4/-15.4|0/-12|20/-7.6
3030 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
3034 Hard limiter at -6dB:
3036 compand=attacks=0:points=-80/-80|-6/-6|20/-6
3040 Hard limiter at -12dB:
3042 compand=attacks=0:points=-80/-80|-12/-12|20/-12
3046 Hard noise gate at -35 dB:
3048 compand=attacks=0:points=-80/-115|-35.1/-80|-35/-35|20/20
3054 compand=attacks=0:points=-80/-80|-12.4/-12.4|-6/-8|0/-6.8|20/-2.8
3058 @section compensationdelay
3060 Compensation Delay Line is a metric based delay to compensate differing
3061 positions of microphones or speakers.
3063 For example, you have recorded guitar with two microphones placed in
3064 different locations. Because the front of sound wave has fixed speed in
3065 normal conditions, the phasing of microphones can vary and depends on
3066 their location and interposition. The best sound mix can be achieved when
3067 these microphones are in phase (synchronized). Note that a distance of
3068 ~30 cm between microphones makes one microphone capture the signal in
3069 antiphase to the other microphone. That makes the final mix sound moody.
3070 This filter helps to solve phasing problems by adding different delays
3071 to each microphone track and make them synchronized.
3073 The best result can be reached when you take one track as base and
3074 synchronize other tracks one by one with it.
3075 Remember that synchronization/delay tolerance depends on sample rate, too.
3076 Higher sample rates will give more tolerance.
3078 The filter accepts the following parameters:
3082 Set millimeters distance. This is compensation distance for fine tuning.
3086 Set cm distance. This is compensation distance for tightening distance setup.
3090 Set meters distance. This is compensation distance for hard distance setup.
3094 Set dry amount. Amount of unprocessed (dry) signal.
3098 Set wet amount. Amount of processed (wet) signal.
3102 Set temperature in degrees Celsius. This is the temperature of the environment.
3107 Apply headphone crossfeed filter.
3109 Crossfeed is the process of blending the left and right channels of stereo
3111 It is mainly used to reduce extreme stereo separation of low frequencies.
3113 The intent is to produce more speaker like sound to the listener.
3115 The filter accepts the following options:
3119 Set strength of crossfeed. Default is 0.2. Allowed range is from 0 to 1.
3120 This sets gain of low shelf filter for side part of stereo image.
3121 Default is -6dB. Max allowed is -30db when strength is set to 1.
3124 Set soundstage wideness. Default is 0.5. Allowed range is from 0 to 1.
3125 This sets cut off frequency of low shelf filter. Default is cut off near
3126 1550 Hz. With range set to 1 cut off frequency is set to 2100 Hz.
3129 Set input gain. Default is 0.9.
3132 Set output gain. Default is 1.
3135 @section crystalizer
3136 Simple algorithm to expand audio dynamic range.
3138 The filter accepts the following options:
3142 Sets the intensity of effect (default: 2.0). Must be in range between 0.0
3143 (unchanged sound) to 10.0 (maximum effect).
3146 Enable clipping. By default is enabled.
3150 Apply a DC shift to the audio.
3152 This can be useful to remove a DC offset (caused perhaps by a hardware problem
3153 in the recording chain) from the audio. The effect of a DC offset is reduced
3154 headroom and hence volume. The @ref{astats} filter can be used to determine if
3155 a signal has a DC offset.
3159 Set the DC shift, allowed range is [-1, 1]. It indicates the amount to shift
3163 Optional. It should have a value much less than 1 (e.g. 0.05 or 0.02) and is
3164 used to prevent clipping.
3169 Apply de-essing to the audio samples.
3173 Set intensity for triggering de-essing. Allowed range is from 0 to 1.
3177 Set amount of ducking on treble part of sound. Allowed range is from 0 to 1.
3181 How much of original frequency content to keep when de-essing. Allowed range is from 0 to 1.
3185 Set the output mode.
3187 It accepts the following values:
3190 Pass input unchanged.
3193 Pass ess filtered out.
3198 Default value is @var{o}.
3204 Measure audio dynamic range.
3206 DR values of 14 and higher is found in very dynamic material. DR of 8 to 13
3207 is found in transition material. And anything less that 8 have very poor dynamics
3208 and is very compressed.
3210 The filter accepts the following options:
3214 Set window length in seconds used to split audio into segments of equal length.
3215 Default is 3 seconds.
3219 Dynamic Audio Normalizer.
3221 This filter applies a certain amount of gain to the input audio in order
3222 to bring its peak magnitude to a target level (e.g. 0 dBFS). However, in
3223 contrast to more "simple" normalization algorithms, the Dynamic Audio
3224 Normalizer *dynamically* re-adjusts the gain factor to the input audio.
3225 This allows for applying extra gain to the "quiet" sections of the audio
3226 while avoiding distortions or clipping the "loud" sections. In other words:
3227 The Dynamic Audio Normalizer will "even out" the volume of quiet and loud
3228 sections, in the sense that the volume of each section is brought to the
3229 same target level. Note, however, that the Dynamic Audio Normalizer achieves
3230 this goal *without* applying "dynamic range compressing". It will retain 100%
3231 of the dynamic range *within* each section of the audio file.
3235 Set the frame length in milliseconds. In range from 10 to 8000 milliseconds.
3236 Default is 500 milliseconds.
3237 The Dynamic Audio Normalizer processes the input audio in small chunks,
3238 referred to as frames. This is required, because a peak magnitude has no
3239 meaning for just a single sample value. Instead, we need to determine the
3240 peak magnitude for a contiguous sequence of sample values. While a "standard"
3241 normalizer would simply use the peak magnitude of the complete file, the
3242 Dynamic Audio Normalizer determines the peak magnitude individually for each
3243 frame. The length of a frame is specified in milliseconds. By default, the
3244 Dynamic Audio Normalizer uses a frame length of 500 milliseconds, which has
3245 been found to give good results with most files.
3246 Note that the exact frame length, in number of samples, will be determined
3247 automatically, based on the sampling rate of the individual input audio file.
3250 Set the Gaussian filter window size. In range from 3 to 301, must be odd
3251 number. Default is 31.
3252 Probably the most important parameter of the Dynamic Audio Normalizer is the
3253 @code{window size} of the Gaussian smoothing filter. The filter's window size
3254 is specified in frames, centered around the current frame. For the sake of
3255 simplicity, this must be an odd number. Consequently, the default value of 31
3256 takes into account the current frame, as well as the 15 preceding frames and
3257 the 15 subsequent frames. Using a larger window results in a stronger
3258 smoothing effect and thus in less gain variation, i.e. slower gain
3259 adaptation. Conversely, using a smaller window results in a weaker smoothing
3260 effect and thus in more gain variation, i.e. faster gain adaptation.
3261 In other words, the more you increase this value, the more the Dynamic Audio
3262 Normalizer will behave like a "traditional" normalization filter. On the
3263 contrary, the more you decrease this value, the more the Dynamic Audio
3264 Normalizer will behave like a dynamic range compressor.
3267 Set the target peak value. This specifies the highest permissible magnitude
3268 level for the normalized audio input. This filter will try to approach the
3269 target peak magnitude as closely as possible, but at the same time it also
3270 makes sure that the normalized signal will never exceed the peak magnitude.
3271 A frame's maximum local gain factor is imposed directly by the target peak
3272 magnitude. The default value is 0.95 and thus leaves a headroom of 5%*.
3273 It is not recommended to go above this value.
3276 Set the maximum gain factor. In range from 1.0 to 100.0. Default is 10.0.
3277 The Dynamic Audio Normalizer determines the maximum possible (local) gain
3278 factor for each input frame, i.e. the maximum gain factor that does not
3279 result in clipping or distortion. The maximum gain factor is determined by
3280 the frame's highest magnitude sample. However, the Dynamic Audio Normalizer
3281 additionally bounds the frame's maximum gain factor by a predetermined
3282 (global) maximum gain factor. This is done in order to avoid excessive gain
3283 factors in "silent" or almost silent frames. By default, the maximum gain
3284 factor is 10.0, For most inputs the default value should be sufficient and
3285 it usually is not recommended to increase this value. Though, for input
3286 with an extremely low overall volume level, it may be necessary to allow even
3287 higher gain factors. Note, however, that the Dynamic Audio Normalizer does
3288 not simply apply a "hard" threshold (i.e. cut off values above the threshold).
3289 Instead, a "sigmoid" threshold function will be applied. This way, the
3290 gain factors will smoothly approach the threshold value, but never exceed that
3294 Set the target RMS. In range from 0.0 to 1.0. Default is 0.0 - disabled.
3295 By default, the Dynamic Audio Normalizer performs "peak" normalization.
3296 This means that the maximum local gain factor for each frame is defined
3297 (only) by the frame's highest magnitude sample. This way, the samples can
3298 be amplified as much as possible without exceeding the maximum signal
3299 level, i.e. without clipping. Optionally, however, the Dynamic Audio
3300 Normalizer can also take into account the frame's root mean square,
3301 abbreviated RMS. In electrical engineering, the RMS is commonly used to
3302 determine the power of a time-varying signal. It is therefore considered
3303 that the RMS is a better approximation of the "perceived loudness" than
3304 just looking at the signal's peak magnitude. Consequently, by adjusting all
3305 frames to a constant RMS value, a uniform "perceived loudness" can be
3306 established. If a target RMS value has been specified, a frame's local gain
3307 factor is defined as the factor that would result in exactly that RMS value.
3308 Note, however, that the maximum local gain factor is still restricted by the
3309 frame's highest magnitude sample, in order to prevent clipping.
3312 Enable channels coupling. By default is enabled.
3313 By default, the Dynamic Audio Normalizer will amplify all channels by the same
3314 amount. This means the same gain factor will be applied to all channels, i.e.
3315 the maximum possible gain factor is determined by the "loudest" channel.
3316 However, in some recordings, it may happen that the volume of the different
3317 channels is uneven, e.g. one channel may be "quieter" than the other one(s).
3318 In this case, this option can be used to disable the channel coupling. This way,
3319 the gain factor will be determined independently for each channel, depending
3320 only on the individual channel's highest magnitude sample. This allows for
3321 harmonizing the volume of the different channels.
3324 Enable DC bias correction. By default is disabled.
3325 An audio signal (in the time domain) is a sequence of sample values.
3326 In the Dynamic Audio Normalizer these sample values are represented in the
3327 -1.0 to 1.0 range, regardless of the original input format. Normally, the
3328 audio signal, or "waveform", should be centered around the zero point.
3329 That means if we calculate the mean value of all samples in a file, or in a
3330 single frame, then the result should be 0.0 or at least very close to that
3331 value. If, however, there is a significant deviation of the mean value from
3332 0.0, in either positive or negative direction, this is referred to as a
3333 DC bias or DC offset. Since a DC bias is clearly undesirable, the Dynamic
3334 Audio Normalizer provides optional DC bias correction.
3335 With DC bias correction enabled, the Dynamic Audio Normalizer will determine
3336 the mean value, or "DC correction" offset, of each input frame and subtract
3337 that value from all of the frame's sample values which ensures those samples
3338 are centered around 0.0 again. Also, in order to avoid "gaps" at the frame
3339 boundaries, the DC correction offset values will be interpolated smoothly
3340 between neighbouring frames.
3342 @item altboundary, b
3343 Enable alternative boundary mode. By default is disabled.
3344 The Dynamic Audio Normalizer takes into account a certain neighbourhood
3345 around each frame. This includes the preceding frames as well as the
3346 subsequent frames. However, for the "boundary" frames, located at the very
3347 beginning and at the very end of the audio file, not all neighbouring
3348 frames are available. In particular, for the first few frames in the audio
3349 file, the preceding frames are not known. And, similarly, for the last few
3350 frames in the audio file, the subsequent frames are not known. Thus, the
3351 question arises which gain factors should be assumed for the missing frames
3352 in the "boundary" region. The Dynamic Audio Normalizer implements two modes
3353 to deal with this situation. The default boundary mode assumes a gain factor
3354 of exactly 1.0 for the missing frames, resulting in a smooth "fade in" and
3355 "fade out" at the beginning and at the end of the input, respectively.
3358 Set the compress factor. In range from 0.0 to 30.0. Default is 0.0.
3359 By default, the Dynamic Audio Normalizer does not apply "traditional"
3360 compression. This means that signal peaks will not be pruned and thus the
3361 full dynamic range will be retained within each local neighbourhood. However,
3362 in some cases it may be desirable to combine the Dynamic Audio Normalizer's
3363 normalization algorithm with a more "traditional" compression.
3364 For this purpose, the Dynamic Audio Normalizer provides an optional compression
3365 (thresholding) function. If (and only if) the compression feature is enabled,
3366 all input frames will be processed by a soft knee thresholding function prior
3367 to the actual normalization process. Put simply, the thresholding function is
3368 going to prune all samples whose magnitude exceeds a certain threshold value.
3369 However, the Dynamic Audio Normalizer does not simply apply a fixed threshold
3370 value. Instead, the threshold value will be adjusted for each individual
3372 In general, smaller parameters result in stronger compression, and vice versa.
3373 Values below 3.0 are not recommended, because audible distortion may appear.
3378 Make audio easier to listen to on headphones.
3380 This filter adds `cues' to 44.1kHz stereo (i.e. audio CD format) audio
3381 so that when listened to on headphones the stereo image is moved from
3382 inside your head (standard for headphones) to outside and in front of
3383 the listener (standard for speakers).
3389 Apply a two-pole peaking equalisation (EQ) filter. With this
3390 filter, the signal-level at and around a selected frequency can
3391 be increased or decreased, whilst (unlike bandpass and bandreject
3392 filters) that at all other frequencies is unchanged.
3394 In order to produce complex equalisation curves, this filter can
3395 be given several times, each with a different central frequency.
3397 The filter accepts the following options:
3401 Set the filter's central frequency in Hz.
3404 Set method to specify band-width of filter.
3419 Specify the band-width of a filter in width_type units.
3422 Set the required gain or attenuation in dB.
3423 Beware of clipping when using a positive gain.
3426 How much to use filtered signal in output. Default is 1.
3427 Range is between 0 and 1.
3430 Specify which channels to filter, by default all available are filtered.
3433 @subsection Examples
3436 Attenuate 10 dB at 1000 Hz, with a bandwidth of 200 Hz:
3438 equalizer=f=1000:t=h:width=200:g=-10
3442 Apply 2 dB gain at 1000 Hz with Q 1 and attenuate 5 dB at 100 Hz with Q 2:
3444 equalizer=f=1000:t=q:w=1:g=2,equalizer=f=100:t=q:w=2:g=-5
3448 @subsection Commands
3450 This filter supports the following commands:
3453 Change equalizer frequency.
3454 Syntax for the command is : "@var{frequency}"
3457 Change equalizer width_type.
3458 Syntax for the command is : "@var{width_type}"
3461 Change equalizer width.
3462 Syntax for the command is : "@var{width}"
3465 Change equalizer gain.
3466 Syntax for the command is : "@var{gain}"
3469 Change equalizer mix.
3470 Syntax for the command is : "@var{mix}"
3473 @section extrastereo
3475 Linearly increases the difference between left and right channels which
3476 adds some sort of "live" effect to playback.
3478 The filter accepts the following options:
3482 Sets the difference coefficient (default: 2.5). 0.0 means mono sound
3483 (average of both channels), with 1.0 sound will be unchanged, with
3484 -1.0 left and right channels will be swapped.
3487 Enable clipping. By default is enabled.
3490 @section firequalizer
3491 Apply FIR Equalization using arbitrary frequency response.
3493 The filter accepts the following option:
3497 Set gain curve equation (in dB). The expression can contain variables:
3500 the evaluated frequency
3504 channel number, set to 0 when multichannels evaluation is disabled
3506 channel id, see libavutil/channel_layout.h, set to the first channel id when
3507 multichannels evaluation is disabled
3511 channel_layout, see libavutil/channel_layout.h
3516 @item gain_interpolate(f)
3517 interpolate gain on frequency f based on gain_entry
3518 @item cubic_interpolate(f)
3519 same as gain_interpolate, but smoother
3521 This option is also available as command. Default is @code{gain_interpolate(f)}.
3524 Set gain entry for gain_interpolate function. The expression can
3528 store gain entry at frequency f with value g
3530 This option is also available as command.
3533 Set filter delay in seconds. Higher value means more accurate.
3534 Default is @code{0.01}.
3537 Set filter accuracy in Hz. Lower value means more accurate.
3538 Default is @code{5}.
3541 Set window function. Acceptable values are:
3544 rectangular window, useful when gain curve is already smooth
3546 hann window (default)
3552 3-terms continuous 1st derivative nuttall window
3554 minimum 3-terms discontinuous nuttall window
3556 4-terms continuous 1st derivative nuttall window
3558 minimum 4-terms discontinuous nuttall (blackman-nuttall) window
3560 blackman-harris window
3566 If enabled, use fixed number of audio samples. This improves speed when
3567 filtering with large delay. Default is disabled.
3570 Enable multichannels evaluation on gain. Default is disabled.
3573 Enable zero phase mode by subtracting timestamp to compensate delay.
3574 Default is disabled.
3577 Set scale used by gain. Acceptable values are:
3580 linear frequency, linear gain
3582 linear frequency, logarithmic (in dB) gain (default)
3584 logarithmic (in octave scale where 20 Hz is 0) frequency, linear gain
3586 logarithmic frequency, logarithmic gain
3590 Set file for dumping, suitable for gnuplot.
3593 Set scale for dumpfile. Acceptable values are same with scale option.
3597 Enable 2-channel convolution using complex FFT. This improves speed significantly.
3598 Default is disabled.
3601 Enable minimum phase impulse response. Default is disabled.
3604 @subsection Examples
3609 firequalizer=gain='if(lt(f,1000), 0, -INF)'
3612 lowpass at 1000 Hz with gain_entry:
3614 firequalizer=gain_entry='entry(1000,0); entry(1001, -INF)'
3617 custom equalization:
3619 firequalizer=gain_entry='entry(100,0); entry(400, -4); entry(1000, -6); entry(2000, 0)'
3622 higher delay with zero phase to compensate delay:
3624 firequalizer=delay=0.1:fixed=on:zero_phase=on
3627 lowpass on left channel, highpass on right channel:
3629 firequalizer=gain='if(eq(chid,1), gain_interpolate(f), if(eq(chid,2), gain_interpolate(1e6+f), 0))'
3630 :gain_entry='entry(1000, 0); entry(1001,-INF); entry(1e6+1000,0)':multi=on
3635 Apply a flanging effect to the audio.
3637 The filter accepts the following options:
3641 Set base delay in milliseconds. Range from 0 to 30. Default value is 0.
3644 Set added sweep delay in milliseconds. Range from 0 to 10. Default value is 2.
3647 Set percentage regeneration (delayed signal feedback). Range from -95 to 95.
3651 Set percentage of delayed signal mixed with original. Range from 0 to 100.
3652 Default value is 71.
3655 Set sweeps per second (Hz). Range from 0.1 to 10. Default value is 0.5.
3658 Set swept wave shape, can be @var{triangular} or @var{sinusoidal}.
3659 Default value is @var{sinusoidal}.
3662 Set swept wave percentage-shift for multi channel. Range from 0 to 100.
3663 Default value is 25.
3666 Set delay-line interpolation, @var{linear} or @var{quadratic}.
3667 Default is @var{linear}.
3671 Apply Haas effect to audio.
3673 Note that this makes most sense to apply on mono signals.
3674 With this filter applied to mono signals it give some directionality and
3675 stretches its stereo image.
3677 The filter accepts the following options:
3681 Set input level. By default is @var{1}, or 0dB
3684 Set output level. By default is @var{1}, or 0dB.
3687 Set gain applied to side part of signal. By default is @var{1}.
3690 Set kind of middle source. Can be one of the following:
3700 Pick middle part signal of stereo image.
3703 Pick side part signal of stereo image.
3707 Change middle phase. By default is disabled.
3710 Set left channel delay. By default is @var{2.05} milliseconds.
3713 Set left channel balance. By default is @var{-1}.
3716 Set left channel gain. By default is @var{1}.
3719 Change left phase. By default is disabled.
3722 Set right channel delay. By defaults is @var{2.12} milliseconds.
3725 Set right channel balance. By default is @var{1}.
3728 Set right channel gain. By default is @var{1}.
3731 Change right phase. By default is enabled.
3736 Decodes High Definition Compatible Digital (HDCD) data. A 16-bit PCM stream with
3737 embedded HDCD codes is expanded into a 20-bit PCM stream.
3739 The filter supports the Peak Extend and Low-level Gain Adjustment features
3740 of HDCD, and detects the Transient Filter flag.
3743 ffmpeg -i HDCD16.flac -af hdcd OUT24.flac
3746 When using the filter with wav, note the default encoding for wav is 16-bit,
3747 so the resulting 20-bit stream will be truncated back to 16-bit. Use something
3748 like @command{-acodec pcm_s24le} after the filter to get 24-bit PCM output.
3750 ffmpeg -i HDCD16.wav -af hdcd OUT16.wav
3751 ffmpeg -i HDCD16.wav -af hdcd -c:a pcm_s24le OUT24.wav
3754 The filter accepts the following options:
3757 @item disable_autoconvert
3758 Disable any automatic format conversion or resampling in the filter graph.
3760 @item process_stereo
3761 Process the stereo channels together. If target_gain does not match between
3762 channels, consider it invalid and use the last valid target_gain.
3765 Set the code detect timer period in ms.
3768 Always extend peaks above -3dBFS even if PE isn't signaled.
3771 Replace audio with a solid tone and adjust the amplitude to signal some
3772 specific aspect of the decoding process. The output file can be loaded in
3773 an audio editor alongside the original to aid analysis.
3775 @code{analyze_mode=pe:force_pe=true} can be used to see all samples above the PE level.
3782 Gain adjustment level at each sample
3784 Samples where peak extend occurs
3786 Samples where the code detect timer is active
3788 Samples where the target gain does not match between channels
3794 Apply head-related transfer functions (HRTFs) to create virtual
3795 loudspeakers around the user for binaural listening via headphones.
3796 The HRIRs are provided via additional streams, for each channel
3797 one stereo input stream is needed.
3799 The filter accepts the following options:
3803 Set mapping of input streams for convolution.
3804 The argument is a '|'-separated list of channel names in order as they
3805 are given as additional stream inputs for filter.
3806 This also specify number of input streams. Number of input streams
3807 must be not less than number of channels in first stream plus one.
3810 Set gain applied to audio. Value is in dB. Default is 0.
3813 Set processing type. Can be @var{time} or @var{freq}. @var{time} is
3814 processing audio in time domain which is slow.
3815 @var{freq} is processing audio in frequency domain which is fast.
3816 Default is @var{freq}.
3819 Set custom gain for LFE channels. Value is in dB. Default is 0.
3822 Set size of frame in number of samples which will be processed at once.
3823 Default value is @var{1024}. Allowed range is from 1024 to 96000.
3826 Set format of hrir stream.
3827 Default value is @var{stereo}. Alternative value is @var{multich}.
3828 If value is set to @var{stereo}, number of additional streams should
3829 be greater or equal to number of input channels in first input stream.
3830 Also each additional stream should have stereo number of channels.
3831 If value is set to @var{multich}, number of additional streams should
3832 be exactly one. Also number of input channels of additional stream
3833 should be equal or greater than twice number of channels of first input
3837 @subsection Examples
3841 Full example using wav files as coefficients with amovie filters for 7.1 downmix,
3842 each amovie filter use stereo file with IR coefficients as input.
3843 The files give coefficients for each position of virtual loudspeaker:
3846 -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"
3851 Full example using wav files as coefficients with amovie filters for 7.1 downmix,
3852 but now in @var{multich} @var{hrir} format.
3854 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"
3861 Apply a high-pass filter with 3dB point frequency.
3862 The filter can be either single-pole, or double-pole (the default).
3863 The filter roll off at 6dB per pole per octave (20dB per pole per decade).
3865 The filter accepts the following options:
3869 Set frequency in Hz. Default is 3000.
3872 Set number of poles. Default is 2.
3875 Set method to specify band-width of filter.
3890 Specify the band-width of a filter in width_type units.
3891 Applies only to double-pole filter.
3892 The default is 0.707q and gives a Butterworth response.
3895 How much to use filtered signal in output. Default is 1.
3896 Range is between 0 and 1.
3899 Specify which channels to filter, by default all available are filtered.
3902 @subsection Commands
3904 This filter supports the following commands:
3907 Change highpass frequency.
3908 Syntax for the command is : "@var{frequency}"
3911 Change highpass width_type.
3912 Syntax for the command is : "@var{width_type}"
3915 Change highpass width.
3916 Syntax for the command is : "@var{width}"
3919 Change highpass mix.
3920 Syntax for the command is : "@var{mix}"
3925 Join multiple input streams into one multi-channel stream.
3927 It accepts the following parameters:
3931 The number of input streams. It defaults to 2.
3933 @item channel_layout
3934 The desired output channel layout. It defaults to stereo.
3937 Map channels from inputs to output. The argument is a '|'-separated list of
3938 mappings, each in the @code{@var{input_idx}.@var{in_channel}-@var{out_channel}}
3939 form. @var{input_idx} is the 0-based index of the input stream. @var{in_channel}
3940 can be either the name of the input channel (e.g. FL for front left) or its
3941 index in the specified input stream. @var{out_channel} is the name of the output
3945 The filter will attempt to guess the mappings when they are not specified
3946 explicitly. It does so by first trying to find an unused matching input channel
3947 and if that fails it picks the first unused input channel.
3949 Join 3 inputs (with properly set channel layouts):
3951 ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT
3954 Build a 5.1 output from 6 single-channel streams:
3956 ffmpeg -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex
3957 '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'
3963 Load a LADSPA (Linux Audio Developer's Simple Plugin API) plugin.
3965 To enable compilation of this filter you need to configure FFmpeg with
3966 @code{--enable-ladspa}.
3970 Specifies the name of LADSPA plugin library to load. If the environment
3971 variable @env{LADSPA_PATH} is defined, the LADSPA plugin is searched in
3972 each one of the directories specified by the colon separated list in
3973 @env{LADSPA_PATH}, otherwise in the standard LADSPA paths, which are in
3974 this order: @file{HOME/.ladspa/lib/}, @file{/usr/local/lib/ladspa/},
3975 @file{/usr/lib/ladspa/}.
3978 Specifies the plugin within the library. Some libraries contain only
3979 one plugin, but others contain many of them. If this is not set filter
3980 will list all available plugins within the specified library.
3983 Set the '|' separated list of controls which are zero or more floating point
3984 values that determine the behavior of the loaded plugin (for example delay,
3986 Controls need to be defined using the following syntax:
3987 c0=@var{value0}|c1=@var{value1}|c2=@var{value2}|..., where
3988 @var{valuei} is the value set on the @var{i}-th control.
3989 Alternatively they can be also defined using the following syntax:
3990 @var{value0}|@var{value1}|@var{value2}|..., where
3991 @var{valuei} is the value set on the @var{i}-th control.
3992 If @option{controls} is set to @code{help}, all available controls and
3993 their valid ranges are printed.
3995 @item sample_rate, s
3996 Specify the sample rate, default to 44100. Only used if plugin have
4000 Set the number of samples per channel per each output frame, default
4001 is 1024. Only used if plugin have zero inputs.
4004 Set the minimum duration of the sourced audio. See
4005 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
4006 for the accepted syntax.
4007 Note that the resulting duration may be greater than the specified duration,
4008 as the generated audio is always cut at the end of a complete frame.
4009 If not specified, or the expressed duration is negative, the audio is
4010 supposed to be generated forever.
4011 Only used if plugin have zero inputs.
4015 @subsection Examples
4019 List all available plugins within amp (LADSPA example plugin) library:
4025 List all available controls and their valid ranges for @code{vcf_notch}
4026 plugin from @code{VCF} library:
4028 ladspa=f=vcf:p=vcf_notch:c=help
4032 Simulate low quality audio equipment using @code{Computer Music Toolkit} (CMT)
4035 ladspa=file=cmt:plugin=lofi:controls=c0=22|c1=12|c2=12
4039 Add reverberation to the audio using TAP-plugins
4040 (Tom's Audio Processing plugins):
4042 ladspa=file=tap_reverb:tap_reverb
4046 Generate white noise, with 0.2 amplitude:
4048 ladspa=file=cmt:noise_source_white:c=c0=.2
4052 Generate 20 bpm clicks using plugin @code{C* Click - Metronome} from the
4053 @code{C* Audio Plugin Suite} (CAPS) library:
4055 ladspa=file=caps:Click:c=c1=20'
4059 Apply @code{C* Eq10X2 - Stereo 10-band equaliser} effect:
4061 ladspa=caps:Eq10X2:c=c0=-48|c9=-24|c3=12|c4=2
4065 Increase volume by 20dB using fast lookahead limiter from Steve Harris
4066 @code{SWH Plugins} collection:
4068 ladspa=fast_lookahead_limiter_1913:fastLookaheadLimiter:20|0|2
4072 Attenuate low frequencies using Multiband EQ from Steve Harris
4073 @code{SWH Plugins} collection:
4075 ladspa=mbeq_1197:mbeq:-24|-24|-24|0|0|0|0|0|0|0|0|0|0|0|0
4079 Reduce stereo image using @code{Narrower} from the @code{C* Audio Plugin Suite}
4082 ladspa=caps:Narrower
4086 Another white noise, now using @code{C* Audio Plugin Suite} (CAPS) library:
4088 ladspa=caps:White:.2
4092 Some fractal noise, using @code{C* Audio Plugin Suite} (CAPS) library:
4094 ladspa=caps:Fractal:c=c1=1
4098 Dynamic volume normalization using @code{VLevel} plugin:
4100 ladspa=vlevel-ladspa:vlevel_mono
4104 @subsection Commands
4106 This filter supports the following commands:
4109 Modify the @var{N}-th control value.
4111 If the specified value is not valid, it is ignored and prior one is kept.
4116 EBU R128 loudness normalization. Includes both dynamic and linear normalization modes.
4117 Support for both single pass (livestreams, files) and double pass (files) modes.
4118 This algorithm can target IL, LRA, and maximum true peak. To accurately detect true peaks,
4119 the audio stream will be upsampled to 192 kHz unless the normalization mode is linear.
4120 Use the @code{-ar} option or @code{aresample} filter to explicitly set an output sample rate.
4122 The filter accepts the following options:
4126 Set integrated loudness target.
4127 Range is -70.0 - -5.0. Default value is -24.0.
4130 Set loudness range target.
4131 Range is 1.0 - 20.0. Default value is 7.0.
4134 Set maximum true peak.
4135 Range is -9.0 - +0.0. Default value is -2.0.
4137 @item measured_I, measured_i
4138 Measured IL of input file.
4139 Range is -99.0 - +0.0.
4141 @item measured_LRA, measured_lra
4142 Measured LRA of input file.
4143 Range is 0.0 - 99.0.
4145 @item measured_TP, measured_tp
4146 Measured true peak of input file.
4147 Range is -99.0 - +99.0.
4149 @item measured_thresh
4150 Measured threshold of input file.
4151 Range is -99.0 - +0.0.
4154 Set offset gain. Gain is applied before the true-peak limiter.
4155 Range is -99.0 - +99.0. Default is +0.0.
4158 Normalize linearly if possible.
4159 measured_I, measured_LRA, measured_TP, and measured_thresh must also
4160 to be specified in order to use this mode.
4161 Options are true or false. Default is true.
4164 Treat mono input files as "dual-mono". If a mono file is intended for playback
4165 on a stereo system, its EBU R128 measurement will be perceptually incorrect.
4166 If set to @code{true}, this option will compensate for this effect.
4167 Multi-channel input files are not affected by this option.
4168 Options are true or false. Default is false.
4171 Set print format for stats. Options are summary, json, or none.
4172 Default value is none.
4177 Apply a low-pass filter with 3dB point frequency.
4178 The filter can be either single-pole or double-pole (the default).
4179 The filter roll off at 6dB per pole per octave (20dB per pole per decade).
4181 The filter accepts the following options:
4185 Set frequency in Hz. Default is 500.
4188 Set number of poles. Default is 2.
4191 Set method to specify band-width of filter.
4206 Specify the band-width of a filter in width_type units.
4207 Applies only to double-pole filter.
4208 The default is 0.707q and gives a Butterworth response.
4211 How much to use filtered signal in output. Default is 1.
4212 Range is between 0 and 1.
4215 Specify which channels to filter, by default all available are filtered.
4218 @subsection Examples
4221 Lowpass only LFE channel, it LFE is not present it does nothing:
4227 @subsection Commands
4229 This filter supports the following commands:
4232 Change lowpass frequency.
4233 Syntax for the command is : "@var{frequency}"
4236 Change lowpass width_type.
4237 Syntax for the command is : "@var{width_type}"
4240 Change lowpass width.
4241 Syntax for the command is : "@var{width}"
4245 Syntax for the command is : "@var{mix}"
4250 Load a LV2 (LADSPA Version 2) plugin.
4252 To enable compilation of this filter you need to configure FFmpeg with
4253 @code{--enable-lv2}.
4257 Specifies the plugin URI. You may need to escape ':'.
4260 Set the '|' separated list of controls which are zero or more floating point
4261 values that determine the behavior of the loaded plugin (for example delay,
4263 If @option{controls} is set to @code{help}, all available controls and
4264 their valid ranges are printed.
4266 @item sample_rate, s
4267 Specify the sample rate, default to 44100. Only used if plugin have
4271 Set the number of samples per channel per each output frame, default
4272 is 1024. Only used if plugin have zero inputs.
4275 Set the minimum duration of the sourced audio. See
4276 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
4277 for the accepted syntax.
4278 Note that the resulting duration may be greater than the specified duration,
4279 as the generated audio is always cut at the end of a complete frame.
4280 If not specified, or the expressed duration is negative, the audio is
4281 supposed to be generated forever.
4282 Only used if plugin have zero inputs.
4285 @subsection Examples
4289 Apply bass enhancer plugin from Calf:
4291 lv2=p=http\\\\://calf.sourceforge.net/plugins/BassEnhancer:c=amount=2
4295 Apply vinyl plugin from Calf:
4297 lv2=p=http\\\\://calf.sourceforge.net/plugins/Vinyl:c=drone=0.2|aging=0.5
4301 Apply bit crusher plugin from ArtyFX:
4303 lv2=p=http\\\\://www.openavproductions.com/artyfx#bitta:c=crush=0.3
4308 Multiband Compress or expand the audio's dynamic range.
4310 The input audio is divided into bands using 4th order Linkwitz-Riley IIRs.
4311 This is akin to the crossover of a loudspeaker, and results in flat frequency
4312 response when absent compander action.
4314 It accepts the following parameters:
4318 This option syntax is:
4319 attack,decay,[attack,decay..] soft-knee points crossover_frequency [delay [initial_volume [gain]]] | attack,decay ...
4320 For explanation of each item refer to compand filter documentation.
4326 Mix channels with specific gain levels. The filter accepts the output
4327 channel layout followed by a set of channels definitions.
4329 This filter is also designed to efficiently remap the channels of an audio
4332 The filter accepts parameters of the form:
4333 "@var{l}|@var{outdef}|@var{outdef}|..."
4337 output channel layout or number of channels
4340 output channel specification, of the form:
4341 "@var{out_name}=[@var{gain}*]@var{in_name}[(+-)[@var{gain}*]@var{in_name}...]"
4344 output channel to define, either a channel name (FL, FR, etc.) or a channel
4345 number (c0, c1, etc.)
4348 multiplicative coefficient for the channel, 1 leaving the volume unchanged
4351 input channel to use, see out_name for details; it is not possible to mix
4352 named and numbered input channels
4355 If the `=' in a channel specification is replaced by `<', then the gains for
4356 that specification will be renormalized so that the total is 1, thus
4357 avoiding clipping noise.
4359 @subsection Mixing examples
4361 For example, if you want to down-mix from stereo to mono, but with a bigger
4362 factor for the left channel:
4364 pan=1c|c0=0.9*c0+0.1*c1
4367 A customized down-mix to stereo that works automatically for 3-, 4-, 5- and
4368 7-channels surround:
4370 pan=stereo| FL < FL + 0.5*FC + 0.6*BL + 0.6*SL | FR < FR + 0.5*FC + 0.6*BR + 0.6*SR
4373 Note that @command{ffmpeg} integrates a default down-mix (and up-mix) system
4374 that should be preferred (see "-ac" option) unless you have very specific
4377 @subsection Remapping examples
4379 The channel remapping will be effective if, and only if:
4382 @item gain coefficients are zeroes or ones,
4383 @item only one input per channel output,
4386 If all these conditions are satisfied, the filter will notify the user ("Pure
4387 channel mapping detected"), and use an optimized and lossless method to do the
4390 For example, if you have a 5.1 source and want a stereo audio stream by
4391 dropping the extra channels:
4393 pan="stereo| c0=FL | c1=FR"
4396 Given the same source, you can also switch front left and front right channels
4397 and keep the input channel layout:
4399 pan="5.1| c0=c1 | c1=c0 | c2=c2 | c3=c3 | c4=c4 | c5=c5"
4402 If the input is a stereo audio stream, you can mute the front left channel (and
4403 still keep the stereo channel layout) with:
4408 Still with a stereo audio stream input, you can copy the right channel in both
4409 front left and right:
4411 pan="stereo| c0=FR | c1=FR"
4416 ReplayGain scanner filter. This filter takes an audio stream as an input and
4417 outputs it unchanged.
4418 At end of filtering it displays @code{track_gain} and @code{track_peak}.
4422 Convert the audio sample format, sample rate and channel layout. It is
4423 not meant to be used directly.
4426 Apply time-stretching and pitch-shifting with librubberband.
4428 To enable compilation of this filter, you need to configure FFmpeg with
4429 @code{--enable-librubberband}.
4431 The filter accepts the following options:
4435 Set tempo scale factor.
4438 Set pitch scale factor.
4441 Set transients detector.
4442 Possible values are:
4451 Possible values are:
4460 Possible values are:
4467 Set processing window size.
4468 Possible values are:
4477 Possible values are:
4484 Enable formant preservation when shift pitching.
4485 Possible values are:
4493 Possible values are:
4502 Possible values are:
4509 @subsection Commands
4511 This filter supports the following commands:
4514 Change filter tempo scale factor.
4515 Syntax for the command is : "@var{tempo}"
4518 Change filter pitch scale factor.
4519 Syntax for the command is : "@var{pitch}"
4522 @section sidechaincompress
4524 This filter acts like normal compressor but has the ability to compress
4525 detected signal using second input signal.
4526 It needs two input streams and returns one output stream.
4527 First input stream will be processed depending on second stream signal.
4528 The filtered signal then can be filtered with other filters in later stages of
4529 processing. See @ref{pan} and @ref{amerge} filter.
4531 The filter accepts the following options:
4535 Set input gain. Default is 1. Range is between 0.015625 and 64.
4538 Set mode of compressor operation. Can be @code{upward} or @code{downward}.
4539 Default is @code{downward}.
4542 If a signal of second stream raises above this level it will affect the gain
4543 reduction of first stream.
4544 By default is 0.125. Range is between 0.00097563 and 1.
4547 Set a ratio about which the signal is reduced. 1:2 means that if the level
4548 raised 4dB above the threshold, it will be only 2dB above after the reduction.
4549 Default is 2. Range is between 1 and 20.
4552 Amount of milliseconds the signal has to rise above the threshold before gain
4553 reduction starts. Default is 20. Range is between 0.01 and 2000.
4556 Amount of milliseconds the signal has to fall below the threshold before
4557 reduction is decreased again. Default is 250. Range is between 0.01 and 9000.
4560 Set the amount by how much signal will be amplified after processing.
4561 Default is 1. Range is from 1 to 64.
4564 Curve the sharp knee around the threshold to enter gain reduction more softly.
4565 Default is 2.82843. Range is between 1 and 8.
4568 Choose if the @code{average} level between all channels of side-chain stream
4569 or the louder(@code{maximum}) channel of side-chain stream affects the
4570 reduction. Default is @code{average}.
4573 Should the exact signal be taken in case of @code{peak} or an RMS one in case
4574 of @code{rms}. Default is @code{rms} which is mainly smoother.
4577 Set sidechain gain. Default is 1. Range is between 0.015625 and 64.
4580 How much to use compressed signal in output. Default is 1.
4581 Range is between 0 and 1.
4584 @subsection Examples
4588 Full ffmpeg example taking 2 audio inputs, 1st input to be compressed
4589 depending on the signal of 2nd input and later compressed signal to be
4590 merged with 2nd input:
4592 ffmpeg -i main.flac -i sidechain.flac -filter_complex "[1:a]asplit=2[sc][mix];[0:a][sc]sidechaincompress[compr];[compr][mix]amerge"
4596 @section sidechaingate
4598 A sidechain gate acts like a normal (wideband) gate but has the ability to
4599 filter the detected signal before sending it to the gain reduction stage.
4600 Normally a gate uses the full range signal to detect a level above the
4602 For example: If you cut all lower frequencies from your sidechain signal
4603 the gate will decrease the volume of your track only if not enough highs
4604 appear. With this technique you are able to reduce the resonation of a
4605 natural drum or remove "rumbling" of muted strokes from a heavily distorted
4607 It needs two input streams and returns one output stream.
4608 First input stream will be processed depending on second stream signal.
4610 The filter accepts the following options:
4614 Set input level before filtering.
4615 Default is 1. Allowed range is from 0.015625 to 64.
4618 Set the mode of operation. Can be @code{upward} or @code{downward}.
4619 Default is @code{downward}. If set to @code{upward} mode, higher parts of signal
4620 will be amplified, expanding dynamic range in upward direction.
4621 Otherwise, in case of @code{downward} lower parts of signal will be reduced.
4624 Set the level of gain reduction when the signal is below the threshold.
4625 Default is 0.06125. Allowed range is from 0 to 1.
4626 Setting this to 0 disables reduction and then filter behaves like expander.
4629 If a signal rises above this level the gain reduction is released.
4630 Default is 0.125. Allowed range is from 0 to 1.
4633 Set a ratio about which the signal is reduced.
4634 Default is 2. Allowed range is from 1 to 9000.
4637 Amount of milliseconds the signal has to rise above the threshold before gain
4639 Default is 20 milliseconds. Allowed range is from 0.01 to 9000.
4642 Amount of milliseconds the signal has to fall below the threshold before the
4643 reduction is increased again. Default is 250 milliseconds.
4644 Allowed range is from 0.01 to 9000.
4647 Set amount of amplification of signal after processing.
4648 Default is 1. Allowed range is from 1 to 64.
4651 Curve the sharp knee around the threshold to enter gain reduction more softly.
4652 Default is 2.828427125. Allowed range is from 1 to 8.
4655 Choose if exact signal should be taken for detection or an RMS like one.
4656 Default is rms. Can be peak or rms.
4659 Choose if the average level between all channels or the louder channel affects
4661 Default is average. Can be average or maximum.
4664 Set sidechain gain. Default is 1. Range is from 0.015625 to 64.
4667 @section silencedetect
4669 Detect silence in an audio stream.
4671 This filter logs a message when it detects that the input audio volume is less
4672 or equal to a noise tolerance value for a duration greater or equal to the
4673 minimum detected noise duration.
4675 The printed times and duration are expressed in seconds.
4677 The filter accepts the following options:
4681 Set noise tolerance. Can be specified in dB (in case "dB" is appended to the
4682 specified value) or amplitude ratio. Default is -60dB, or 0.001.
4685 Set silence duration until notification (default is 2 seconds).
4688 Process each channel separately, instead of combined. By default is disabled.
4691 @subsection Examples
4695 Detect 5 seconds of silence with -50dB noise tolerance:
4697 silencedetect=n=-50dB:d=5
4701 Complete example with @command{ffmpeg} to detect silence with 0.0001 noise
4702 tolerance in @file{silence.mp3}:
4704 ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null -
4708 @section silenceremove
4710 Remove silence from the beginning, middle or end of the audio.
4712 The filter accepts the following options:
4716 This value is used to indicate if audio should be trimmed at beginning of
4717 the audio. A value of zero indicates no silence should be trimmed from the
4718 beginning. When specifying a non-zero value, it trims audio up until it
4719 finds non-silence. Normally, when trimming silence from beginning of audio
4720 the @var{start_periods} will be @code{1} but it can be increased to higher
4721 values to trim all audio up to specific count of non-silence periods.
4722 Default value is @code{0}.
4724 @item start_duration
4725 Specify the amount of time that non-silence must be detected before it stops
4726 trimming audio. By increasing the duration, bursts of noises can be treated
4727 as silence and trimmed off. Default value is @code{0}.
4729 @item start_threshold
4730 This indicates what sample value should be treated as silence. For digital
4731 audio, a value of @code{0} may be fine but for audio recorded from analog,
4732 you may wish to increase the value to account for background noise.
4733 Can be specified in dB (in case "dB" is appended to the specified value)
4734 or amplitude ratio. Default value is @code{0}.
4737 Specify max duration of silence at beginning that will be kept after
4738 trimming. Default is 0, which is equal to trimming all samples detected
4742 Specify mode of detection of silence end in start of multi-channel audio.
4743 Can be @var{any} or @var{all}. Default is @var{any}.
4744 With @var{any}, any sample that is detected as non-silence will cause
4745 stopped trimming of silence.
4746 With @var{all}, only if all channels are detected as non-silence will cause
4747 stopped trimming of silence.
4750 Set the count for trimming silence from the end of audio.
4751 To remove silence from the middle of a file, specify a @var{stop_periods}
4752 that is negative. This value is then treated as a positive value and is
4753 used to indicate the effect should restart processing as specified by
4754 @var{start_periods}, making it suitable for removing periods of silence
4755 in the middle of the audio.
4756 Default value is @code{0}.
4759 Specify a duration of silence that must exist before audio is not copied any
4760 more. By specifying a higher duration, silence that is wanted can be left in
4762 Default value is @code{0}.
4764 @item stop_threshold
4765 This is the same as @option{start_threshold} but for trimming silence from
4767 Can be specified in dB (in case "dB" is appended to the specified value)
4768 or amplitude ratio. Default value is @code{0}.
4771 Specify max duration of silence at end that will be kept after
4772 trimming. Default is 0, which is equal to trimming all samples detected
4776 Specify mode of detection of silence start in end of multi-channel audio.
4777 Can be @var{any} or @var{all}. Default is @var{any}.
4778 With @var{any}, any sample that is detected as non-silence will cause
4779 stopped trimming of silence.
4780 With @var{all}, only if all channels are detected as non-silence will cause
4781 stopped trimming of silence.
4784 Set how is silence detected. Can be @code{rms} or @code{peak}. Second is faster
4785 and works better with digital silence which is exactly 0.
4786 Default value is @code{rms}.
4789 Set duration in number of seconds used to calculate size of window in number
4790 of samples for detecting silence.
4791 Default value is @code{0.02}. Allowed range is from @code{0} to @code{10}.
4794 @subsection Examples
4798 The following example shows how this filter can be used to start a recording
4799 that does not contain the delay at the start which usually occurs between
4800 pressing the record button and the start of the performance:
4802 silenceremove=start_periods=1:start_duration=5:start_threshold=0.02
4806 Trim all silence encountered from beginning to end where there is more than 1
4807 second of silence in audio:
4809 silenceremove=stop_periods=-1:stop_duration=1:stop_threshold=-90dB
4813 Trim all digital silence samples, using peak detection, from beginning to end
4814 where there is more than 0 samples of digital silence in audio and digital
4815 silence is detected in all channels at same positions in stream:
4817 silenceremove=window=0:detection=peak:stop_mode=all:start_mode=all:stop_periods=-1:stop_threshold=0
4823 SOFAlizer uses head-related transfer functions (HRTFs) to create virtual
4824 loudspeakers around the user for binaural listening via headphones (audio
4825 formats up to 9 channels supported).
4826 The HRTFs are stored in SOFA files (see @url{http://www.sofacoustics.org/} for a database).
4827 SOFAlizer is developed at the Acoustics Research Institute (ARI) of the
4828 Austrian Academy of Sciences.
4830 To enable compilation of this filter you need to configure FFmpeg with
4831 @code{--enable-libmysofa}.
4833 The filter accepts the following options:
4837 Set the SOFA file used for rendering.
4840 Set gain applied to audio. Value is in dB. Default is 0.
4843 Set rotation of virtual loudspeakers in deg. Default is 0.
4846 Set elevation of virtual speakers in deg. Default is 0.
4849 Set distance in meters between loudspeakers and the listener with near-field
4850 HRTFs. Default is 1.
4853 Set processing type. Can be @var{time} or @var{freq}. @var{time} is
4854 processing audio in time domain which is slow.
4855 @var{freq} is processing audio in frequency domain which is fast.
4856 Default is @var{freq}.
4859 Set custom positions of virtual loudspeakers. Syntax for this option is:
4860 <CH> <AZIM> <ELEV>[|<CH> <AZIM> <ELEV>|...].
4861 Each virtual loudspeaker is described with short channel name following with
4862 azimuth and elevation in degrees.
4863 Each virtual loudspeaker description is separated by '|'.
4864 For example to override front left and front right channel positions use:
4865 'speakers=FL 45 15|FR 345 15'.
4866 Descriptions with unrecognised channel names are ignored.
4869 Set custom gain for LFE channels. Value is in dB. Default is 0.
4872 Set custom frame size in number of samples. Default is 1024.
4873 Allowed range is from 1024 to 96000. Only used if option @samp{type}
4874 is set to @var{freq}.
4877 Should all IRs be normalized upon importing SOFA file.
4878 By default is enabled.
4881 Should nearest IRs be interpolated with neighbor IRs if exact position
4882 does not match. By default is disabled.
4885 Minphase all IRs upon loading of SOFA file. By default is disabled.
4888 Set neighbor search angle step. Only used if option @var{interpolate} is enabled.
4891 Set neighbor search radius step. Only used if option @var{interpolate} is enabled.
4894 @subsection Examples
4898 Using ClubFritz6 sofa file:
4900 sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=1
4904 Using ClubFritz12 sofa file and bigger radius with small rotation:
4906 sofalizer=sofa=/path/to/ClubFritz12.sofa:type=freq:radius=2:rotation=5
4910 Similar as above but with custom speaker positions for front left, front right, back left and back right
4911 and also with custom gain:
4913 "sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=2:speakers=FL 45|FR 315|BL 135|BR 225:gain=28"
4917 @section stereotools
4919 This filter has some handy utilities to manage stereo signals, for converting
4920 M/S stereo recordings to L/R signal while having control over the parameters
4921 or spreading the stereo image of master track.
4923 The filter accepts the following options:
4927 Set input level before filtering for both channels. Defaults is 1.
4928 Allowed range is from 0.015625 to 64.
4931 Set output level after filtering for both channels. Defaults is 1.
4932 Allowed range is from 0.015625 to 64.
4935 Set input balance between both channels. Default is 0.
4936 Allowed range is from -1 to 1.
4939 Set output balance between both channels. Default is 0.
4940 Allowed range is from -1 to 1.
4943 Enable softclipping. Results in analog distortion instead of harsh digital 0dB
4944 clipping. Disabled by default.
4947 Mute the left channel. Disabled by default.
4950 Mute the right channel. Disabled by default.
4953 Change the phase of the left channel. Disabled by default.
4956 Change the phase of the right channel. Disabled by default.
4959 Set stereo mode. Available values are:
4963 Left/Right to Left/Right, this is default.
4966 Left/Right to Mid/Side.
4969 Mid/Side to Left/Right.
4972 Left/Right to Left/Left.
4975 Left/Right to Right/Right.
4978 Left/Right to Left + Right.
4981 Left/Right to Right/Left.
4984 Mid/Side to Left/Left.
4987 Mid/Side to Right/Right.
4991 Set level of side signal. Default is 1.
4992 Allowed range is from 0.015625 to 64.
4995 Set balance of side signal. Default is 0.
4996 Allowed range is from -1 to 1.
4999 Set level of the middle signal. Default is 1.
5000 Allowed range is from 0.015625 to 64.
5003 Set middle signal pan. Default is 0. Allowed range is from -1 to 1.
5006 Set stereo base between mono and inversed channels. Default is 0.
5007 Allowed range is from -1 to 1.
5010 Set delay in milliseconds how much to delay left from right channel and
5011 vice versa. Default is 0. Allowed range is from -20 to 20.
5014 Set S/C level. Default is 1. Allowed range is from 1 to 100.
5017 Set the stereo phase in degrees. Default is 0. Allowed range is from 0 to 360.
5019 @item bmode_in, bmode_out
5020 Set balance mode for balance_in/balance_out option.
5022 Can be one of the following:
5026 Classic balance mode. Attenuate one channel at time.
5027 Gain is raised up to 1.
5030 Similar as classic mode above but gain is raised up to 2.
5033 Equal power distribution, from -6dB to +6dB range.
5037 @subsection Examples
5041 Apply karaoke like effect:
5043 stereotools=mlev=0.015625
5047 Convert M/S signal to L/R:
5049 "stereotools=mode=ms>lr"
5053 @section stereowiden
5055 This filter enhance the stereo effect by suppressing signal common to both
5056 channels and by delaying the signal of left into right and vice versa,
5057 thereby widening the stereo effect.
5059 The filter accepts the following options:
5063 Time in milliseconds of the delay of left signal into right and vice versa.
5064 Default is 20 milliseconds.
5067 Amount of gain in delayed signal into right and vice versa. Gives a delay
5068 effect of left signal in right output and vice versa which gives widening
5069 effect. Default is 0.3.
5072 Cross feed of left into right with inverted phase. This helps in suppressing
5073 the mono. If the value is 1 it will cancel all the signal common to both
5074 channels. Default is 0.3.
5077 Set level of input signal of original channel. Default is 0.8.
5080 @section superequalizer
5081 Apply 18 band equalizer.
5083 The filter accepts the following options:
5090 Set 131Hz band gain.
5092 Set 185Hz band gain.
5094 Set 262Hz band gain.
5096 Set 370Hz band gain.
5098 Set 523Hz band gain.
5100 Set 740Hz band gain.
5102 Set 1047Hz band gain.
5104 Set 1480Hz band gain.
5106 Set 2093Hz band gain.
5108 Set 2960Hz band gain.
5110 Set 4186Hz band gain.
5112 Set 5920Hz band gain.
5114 Set 8372Hz band gain.
5116 Set 11840Hz band gain.
5118 Set 16744Hz band gain.
5120 Set 20000Hz band gain.
5124 Apply audio surround upmix filter.
5126 This filter allows to produce multichannel output from audio stream.
5128 The filter accepts the following options:
5132 Set output channel layout. By default, this is @var{5.1}.
5134 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
5135 for the required syntax.
5138 Set input channel layout. By default, this is @var{stereo}.
5140 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
5141 for the required syntax.
5144 Set input volume level. By default, this is @var{1}.
5147 Set output volume level. By default, this is @var{1}.
5150 Enable LFE channel output if output channel layout has it. By default, this is enabled.
5153 Set LFE low cut off frequency. By default, this is @var{128} Hz.
5156 Set LFE high cut off frequency. By default, this is @var{256} Hz.
5159 Set LFE mode, can be @var{add} or @var{sub}. Default is @var{add}.
5160 In @var{add} mode, LFE channel is created from input audio and added to output.
5161 In @var{sub} mode, LFE channel is created from input audio and added to output but
5162 also all non-LFE output channels are subtracted with output LFE channel.
5165 Set angle of stereo surround transform, Allowed range is from @var{0} to @var{360}.
5166 Default is @var{90}.
5169 Set front center input volume. By default, this is @var{1}.
5172 Set front center output volume. By default, this is @var{1}.
5175 Set front left input volume. By default, this is @var{1}.
5178 Set front left output volume. By default, this is @var{1}.
5181 Set front right input volume. By default, this is @var{1}.
5184 Set front right output volume. By default, this is @var{1}.
5187 Set side left input volume. By default, this is @var{1}.
5190 Set side left output volume. By default, this is @var{1}.
5193 Set side right input volume. By default, this is @var{1}.
5196 Set side right output volume. By default, this is @var{1}.
5199 Set back left input volume. By default, this is @var{1}.
5202 Set back left output volume. By default, this is @var{1}.
5205 Set back right input volume. By default, this is @var{1}.
5208 Set back right output volume. By default, this is @var{1}.
5211 Set back center input volume. By default, this is @var{1}.
5214 Set back center output volume. By default, this is @var{1}.
5217 Set LFE input volume. By default, this is @var{1}.
5220 Set LFE output volume. By default, this is @var{1}.
5223 Set spread usage of stereo image across X axis for all channels.
5226 Set spread usage of stereo image across Y axis for all channels.
5228 @item fcx, flx, frx, blx, brx, slx, srx, bcx
5229 Set spread usage of stereo image across X axis for each channel.
5231 @item fcy, fly, fry, bly, bry, sly, sry, bcy
5232 Set spread usage of stereo image across Y axis for each channel.
5235 Set window size. Allowed range is from @var{1024} to @var{65536}. Default size is @var{4096}.
5238 Set window function.
5240 It accepts the following values:
5263 Default is @code{hann}.
5266 Set window overlap. If set to 1, the recommended overlap for selected
5267 window function will be picked. Default is @code{0.5}.
5270 @section treble, highshelf
5272 Boost or cut treble (upper) frequencies of the audio using a two-pole
5273 shelving filter with a response similar to that of a standard
5274 hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
5276 The filter accepts the following options:
5280 Give the gain at whichever is the lower of ~22 kHz and the
5281 Nyquist frequency. Its useful range is about -20 (for a large cut)
5282 to +20 (for a large boost). Beware of clipping when using a positive gain.
5285 Set the filter's central frequency and so can be used
5286 to extend or reduce the frequency range to be boosted or cut.
5287 The default value is @code{3000} Hz.
5290 Set method to specify band-width of filter.
5305 Determine how steep is the filter's shelf transition.
5308 How much to use filtered signal in output. Default is 1.
5309 Range is between 0 and 1.
5312 Specify which channels to filter, by default all available are filtered.
5315 @subsection Commands
5317 This filter supports the following commands:
5320 Change treble frequency.
5321 Syntax for the command is : "@var{frequency}"
5324 Change treble width_type.
5325 Syntax for the command is : "@var{width_type}"
5328 Change treble width.
5329 Syntax for the command is : "@var{width}"
5333 Syntax for the command is : "@var{gain}"
5337 Syntax for the command is : "@var{mix}"
5342 Sinusoidal amplitude modulation.
5344 The filter accepts the following options:
5348 Modulation frequency in Hertz. Modulation frequencies in the subharmonic range
5349 (20 Hz or lower) will result in a tremolo effect.
5350 This filter may also be used as a ring modulator by specifying
5351 a modulation frequency higher than 20 Hz.
5352 Range is 0.1 - 20000.0. Default value is 5.0 Hz.
5355 Depth of modulation as a percentage. Range is 0.0 - 1.0.
5356 Default value is 0.5.
5361 Sinusoidal phase modulation.
5363 The filter accepts the following options:
5367 Modulation frequency in Hertz.
5368 Range is 0.1 - 20000.0. Default value is 5.0 Hz.
5371 Depth of modulation as a percentage. Range is 0.0 - 1.0.
5372 Default value is 0.5.
5377 Adjust the input audio volume.
5379 It accepts the following parameters:
5383 Set audio volume expression.
5385 Output values are clipped to the maximum value.
5387 The output audio volume is given by the relation:
5389 @var{output_volume} = @var{volume} * @var{input_volume}
5392 The default value for @var{volume} is "1.0".
5395 This parameter represents the mathematical precision.
5397 It determines which input sample formats will be allowed, which affects the
5398 precision of the volume scaling.
5402 8-bit fixed-point; this limits input sample format to U8, S16, and S32.
5404 32-bit floating-point; this limits input sample format to FLT. (default)
5406 64-bit floating-point; this limits input sample format to DBL.
5410 Choose the behaviour on encountering ReplayGain side data in input frames.
5414 Remove ReplayGain side data, ignoring its contents (the default).
5417 Ignore ReplayGain side data, but leave it in the frame.
5420 Prefer the track gain, if present.
5423 Prefer the album gain, if present.
5426 @item replaygain_preamp
5427 Pre-amplification gain in dB to apply to the selected replaygain gain.
5429 Default value for @var{replaygain_preamp} is 0.0.
5432 Set when the volume expression is evaluated.
5434 It accepts the following values:
5437 only evaluate expression once during the filter initialization, or
5438 when the @samp{volume} command is sent
5441 evaluate expression for each incoming frame
5444 Default value is @samp{once}.
5447 The volume expression can contain the following parameters.
5451 frame number (starting at zero)
5454 @item nb_consumed_samples
5455 number of samples consumed by the filter
5457 number of samples in the current frame
5459 original frame position in the file
5465 PTS at start of stream
5467 time at start of stream
5473 last set volume value
5476 Note that when @option{eval} is set to @samp{once} only the
5477 @var{sample_rate} and @var{tb} variables are available, all other
5478 variables will evaluate to NAN.
5480 @subsection Commands
5482 This filter supports the following commands:
5485 Modify the volume expression.
5486 The command accepts the same syntax of the corresponding option.
5488 If the specified expression is not valid, it is kept at its current
5490 @item replaygain_noclip
5491 Prevent clipping by limiting the gain applied.
5493 Default value for @var{replaygain_noclip} is 1.
5497 @subsection Examples
5501 Halve the input audio volume:
5505 volume=volume=-6.0206dB
5508 In all the above example the named key for @option{volume} can be
5509 omitted, for example like in:
5515 Increase input audio power by 6 decibels using fixed-point precision:
5517 volume=volume=6dB:precision=fixed
5521 Fade volume after time 10 with an annihilation period of 5 seconds:
5523 volume='if(lt(t,10),1,max(1-(t-10)/5,0))':eval=frame
5527 @section volumedetect
5529 Detect the volume of the input video.
5531 The filter has no parameters. The input is not modified. Statistics about
5532 the volume will be printed in the log when the input stream end is reached.
5534 In particular it will show the mean volume (root mean square), maximum
5535 volume (on a per-sample basis), and the beginning of a histogram of the
5536 registered volume values (from the maximum value to a cumulated 1/1000 of
5539 All volumes are in decibels relative to the maximum PCM value.
5541 @subsection Examples
5543 Here is an excerpt of the output:
5545 [Parsed_volumedetect_0 @ 0xa23120] mean_volume: -27 dB
5546 [Parsed_volumedetect_0 @ 0xa23120] max_volume: -4 dB
5547 [Parsed_volumedetect_0 @ 0xa23120] histogram_4db: 6
5548 [Parsed_volumedetect_0 @ 0xa23120] histogram_5db: 62
5549 [Parsed_volumedetect_0 @ 0xa23120] histogram_6db: 286
5550 [Parsed_volumedetect_0 @ 0xa23120] histogram_7db: 1042
5551 [Parsed_volumedetect_0 @ 0xa23120] histogram_8db: 2551
5552 [Parsed_volumedetect_0 @ 0xa23120] histogram_9db: 4609
5553 [Parsed_volumedetect_0 @ 0xa23120] histogram_10db: 8409
5559 The mean square energy is approximately -27 dB, or 10^-2.7.
5561 The largest sample is at -4 dB, or more precisely between -4 dB and -5 dB.
5563 There are 6 samples at -4 dB, 62 at -5 dB, 286 at -6 dB, etc.
5566 In other words, raising the volume by +4 dB does not cause any clipping,
5567 raising it by +5 dB causes clipping for 6 samples, etc.
5569 @c man end AUDIO FILTERS
5571 @chapter Audio Sources
5572 @c man begin AUDIO SOURCES
5574 Below is a description of the currently available audio sources.
5578 Buffer audio frames, and make them available to the filter chain.
5580 This source is mainly intended for a programmatic use, in particular
5581 through the interface defined in @file{libavfilter/asrc_abuffer.h}.
5583 It accepts the following parameters:
5587 The timebase which will be used for timestamps of submitted frames. It must be
5588 either a floating-point number or in @var{numerator}/@var{denominator} form.
5591 The sample rate of the incoming audio buffers.
5594 The sample format of the incoming audio buffers.
5595 Either a sample format name or its corresponding integer representation from
5596 the enum AVSampleFormat in @file{libavutil/samplefmt.h}
5598 @item channel_layout
5599 The channel layout of the incoming audio buffers.
5600 Either a channel layout name from channel_layout_map in
5601 @file{libavutil/channel_layout.c} or its corresponding integer representation
5602 from the AV_CH_LAYOUT_* macros in @file{libavutil/channel_layout.h}
5605 The number of channels of the incoming audio buffers.
5606 If both @var{channels} and @var{channel_layout} are specified, then they
5611 @subsection Examples
5614 abuffer=sample_rate=44100:sample_fmt=s16p:channel_layout=stereo
5617 will instruct the source to accept planar 16bit signed stereo at 44100Hz.
5618 Since the sample format with name "s16p" corresponds to the number
5619 6 and the "stereo" channel layout corresponds to the value 0x3, this is
5622 abuffer=sample_rate=44100:sample_fmt=6:channel_layout=0x3
5627 Generate an audio signal specified by an expression.
5629 This source accepts in input one or more expressions (one for each
5630 channel), which are evaluated and used to generate a corresponding
5633 This source accepts the following options:
5637 Set the '|'-separated expressions list for each separate channel. In case the
5638 @option{channel_layout} option is not specified, the selected channel layout
5639 depends on the number of provided expressions. Otherwise the last
5640 specified expression is applied to the remaining output channels.
5642 @item channel_layout, c
5643 Set the channel layout. The number of channels in the specified layout
5644 must be equal to the number of specified expressions.
5647 Set the minimum duration of the sourced audio. See
5648 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
5649 for the accepted syntax.
5650 Note that the resulting duration may be greater than the specified
5651 duration, as the generated audio is always cut at the end of a
5654 If not specified, or the expressed duration is negative, the audio is
5655 supposed to be generated forever.
5658 Set the number of samples per channel per each output frame,
5661 @item sample_rate, s
5662 Specify the sample rate, default to 44100.
5665 Each expression in @var{exprs} can contain the following constants:
5669 number of the evaluated sample, starting from 0
5672 time of the evaluated sample expressed in seconds, starting from 0
5679 @subsection Examples
5689 Generate a sin signal with frequency of 440 Hz, set sample rate to
5692 aevalsrc="sin(440*2*PI*t):s=8000"
5696 Generate a two channels signal, specify the channel layout (Front
5697 Center + Back Center) explicitly:
5699 aevalsrc="sin(420*2*PI*t)|cos(430*2*PI*t):c=FC|BC"
5703 Generate white noise:
5705 aevalsrc="-2+random(0)"
5709 Generate an amplitude modulated signal:
5711 aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)"
5715 Generate 2.5 Hz binaural beats on a 360 Hz carrier:
5717 aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) | 0.1*sin(2*PI*(360+2.5/2)*t)"
5724 The null audio source, return unprocessed audio frames. It is mainly useful
5725 as a template and to be employed in analysis / debugging tools, or as
5726 the source for filters which ignore the input data (for example the sox
5729 This source accepts the following options:
5733 @item channel_layout, cl
5735 Specifies the channel layout, and can be either an integer or a string
5736 representing a channel layout. The default value of @var{channel_layout}
5739 Check the channel_layout_map definition in
5740 @file{libavutil/channel_layout.c} for the mapping between strings and
5741 channel layout values.
5743 @item sample_rate, r
5744 Specifies the sample rate, and defaults to 44100.
5747 Set the number of samples per requested frames.
5751 @subsection Examples
5755 Set the sample rate to 48000 Hz and the channel layout to AV_CH_LAYOUT_MONO.
5757 anullsrc=r=48000:cl=4
5761 Do the same operation with a more obvious syntax:
5763 anullsrc=r=48000:cl=mono
5767 All the parameters need to be explicitly defined.
5771 Synthesize a voice utterance using the libflite library.
5773 To enable compilation of this filter you need to configure FFmpeg with
5774 @code{--enable-libflite}.
5776 Note that versions of the flite library prior to 2.0 are not thread-safe.
5778 The filter accepts the following options:
5783 If set to 1, list the names of the available voices and exit
5784 immediately. Default value is 0.
5787 Set the maximum number of samples per frame. Default value is 512.
5790 Set the filename containing the text to speak.
5793 Set the text to speak.
5796 Set the voice to use for the speech synthesis. Default value is
5797 @code{kal}. See also the @var{list_voices} option.
5800 @subsection Examples
5804 Read from file @file{speech.txt}, and synthesize the text using the
5805 standard flite voice:
5807 flite=textfile=speech.txt
5811 Read the specified text selecting the @code{slt} voice:
5813 flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
5817 Input text to ffmpeg:
5819 ffmpeg -f lavfi -i flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
5823 Make @file{ffplay} speak the specified text, using @code{flite} and
5824 the @code{lavfi} device:
5826 ffplay -f lavfi flite=text='No more be grieved for which that thou hast done.'
5830 For more information about libflite, check:
5831 @url{http://www.festvox.org/flite/}
5835 Generate a noise audio signal.
5837 The filter accepts the following options:
5840 @item sample_rate, r
5841 Specify the sample rate. Default value is 48000 Hz.
5844 Specify the amplitude (0.0 - 1.0) of the generated audio stream. Default value
5848 Specify the duration of the generated audio stream. Not specifying this option
5849 results in noise with an infinite length.
5851 @item color, colour, c
5852 Specify the color of noise. Available noise colors are white, pink, brown,
5853 blue and violet. Default color is white.
5856 Specify a value used to seed the PRNG.
5859 Set the number of samples per each output frame, default is 1024.
5862 @subsection Examples
5867 Generate 60 seconds of pink noise, with a 44.1 kHz sampling rate and an amplitude of 0.5:
5869 anoisesrc=d=60:c=pink:r=44100:a=0.5
5875 Generate odd-tap Hilbert transform FIR coefficients.
5877 The resulting stream can be used with @ref{afir} filter for phase-shifting
5878 the signal by 90 degrees.
5880 This is used in many matrix coding schemes and for analytic signal generation.
5881 The process is often written as a multiplication by i (or j), the imaginary unit.
5883 The filter accepts the following options:
5887 @item sample_rate, s
5888 Set sample rate, default is 44100.
5891 Set length of FIR filter, default is 22051.
5894 Set number of samples per each frame.
5897 Set window function to be used when generating FIR coefficients.
5902 Generate a sinc kaiser-windowed low-pass, high-pass, band-pass, or band-reject FIR coefficients.
5904 The resulting stream can be used with @ref{afir} filter for filtering the audio signal.
5906 The filter accepts the following options:
5909 @item sample_rate, r
5910 Set sample rate, default is 44100.
5913 Set number of samples per each frame. Default is 1024.
5916 Set high-pass frequency. Default is 0.
5919 Set low-pass frequency. Default is 0.
5920 If high-pass frequency is lower than low-pass frequency and low-pass frequency
5921 is higher than 0 then filter will create band-pass filter coefficients,
5922 otherwise band-reject filter coefficients.
5925 Set filter phase response. Default is 50. Allowed range is from 0 to 100.
5928 Set Kaiser window beta.
5931 Set stop-band attenuation. Default is 120dB, allowed range is from 40 to 180 dB.
5934 Enable rounding, by default is disabled.
5937 Set number of taps for high-pass filter.
5940 Set number of taps for low-pass filter.
5945 Generate an audio signal made of a sine wave with amplitude 1/8.
5947 The audio signal is bit-exact.
5949 The filter accepts the following options:
5954 Set the carrier frequency. Default is 440 Hz.
5956 @item beep_factor, b
5957 Enable a periodic beep every second with frequency @var{beep_factor} times
5958 the carrier frequency. Default is 0, meaning the beep is disabled.
5960 @item sample_rate, r
5961 Specify the sample rate, default is 44100.
5964 Specify the duration of the generated audio stream.
5966 @item samples_per_frame
5967 Set the number of samples per output frame.
5969 The expression can contain the following constants:
5973 The (sequential) number of the output audio frame, starting from 0.
5976 The PTS (Presentation TimeStamp) of the output audio frame,
5977 expressed in @var{TB} units.
5980 The PTS of the output audio frame, expressed in seconds.
5983 The timebase of the output audio frames.
5986 Default is @code{1024}.
5989 @subsection Examples
5994 Generate a simple 440 Hz sine wave:
6000 Generate a 220 Hz sine wave with a 880 Hz beep each second, for 5 seconds:
6004 sine=frequency=220:beep_factor=4:duration=5
6008 Generate a 1 kHz sine wave following @code{1602,1601,1602,1601,1602} NTSC
6011 sine=1000:samples_per_frame='st(0,mod(n,5)); 1602-not(not(eq(ld(0),1)+eq(ld(0),3)))'
6015 @c man end AUDIO SOURCES
6017 @chapter Audio Sinks
6018 @c man begin AUDIO SINKS
6020 Below is a description of the currently available audio sinks.
6022 @section abuffersink
6024 Buffer audio frames, and make them available to the end of filter chain.
6026 This sink is mainly intended for programmatic use, in particular
6027 through the interface defined in @file{libavfilter/buffersink.h}
6028 or the options system.
6030 It accepts a pointer to an AVABufferSinkContext structure, which
6031 defines the incoming buffers' formats, to be passed as the opaque
6032 parameter to @code{avfilter_init_filter} for initialization.
6035 Null audio sink; do absolutely nothing with the input audio. It is
6036 mainly useful as a template and for use in analysis / debugging
6039 @c man end AUDIO SINKS
6041 @chapter Video Filters
6042 @c man begin VIDEO FILTERS
6044 When you configure your FFmpeg build, you can disable any of the
6045 existing filters using @code{--disable-filters}.
6046 The configure output will show the video filters included in your
6049 Below is a description of the currently available video filters.
6053 Mark a region of interest in a video frame.
6055 The frame data is passed through unchanged, but metadata is attached
6056 to the frame indicating regions of interest which can affect the
6057 behaviour of later encoding. Multiple regions can be marked by
6058 applying the filter multiple times.
6062 Region distance in pixels from the left edge of the frame.
6064 Region distance in pixels from the top edge of the frame.
6066 Region width in pixels.
6068 Region height in pixels.
6070 The parameters @var{x}, @var{y}, @var{w} and @var{h} are expressions,
6071 and may contain the following variables:
6074 Width of the input frame.
6076 Height of the input frame.
6080 Quantisation offset to apply within the region.
6082 This must be a real value in the range -1 to +1. A value of zero
6083 indicates no quality change. A negative value asks for better quality
6084 (less quantisation), while a positive value asks for worse quality
6085 (greater quantisation).
6087 The range is calibrated so that the extreme values indicate the
6088 largest possible offset - if the rest of the frame is encoded with the
6089 worst possible quality, an offset of -1 indicates that this region
6090 should be encoded with the best possible quality anyway. Intermediate
6091 values are then interpolated in some codec-dependent way.
6093 For example, in 10-bit H.264 the quantisation parameter varies between
6094 -12 and 51. A typical qoffset value of -1/10 therefore indicates that
6095 this region should be encoded with a QP around one-tenth of the full
6096 range better than the rest of the frame. So, if most of the frame
6097 were to be encoded with a QP of around 30, this region would get a QP
6098 of around 24 (an offset of approximately -1/10 * (51 - -12) = -6.3).
6099 An extreme value of -1 would indicate that this region should be
6100 encoded with the best possible quality regardless of the treatment of
6101 the rest of the frame - that is, should be encoded at a QP of -12.
6103 If set to true, remove any existing regions of interest marked on the
6104 frame before adding the new one.
6107 @subsection Examples
6111 Mark the centre quarter of the frame as interesting.
6113 addroi=iw/4:ih/4:iw/2:ih/2:-1/10
6116 Mark the 100-pixel-wide region on the left edge of the frame as very
6117 uninteresting (to be encoded at much lower quality than the rest of
6120 addroi=0:0:100:ih:+1/5
6124 @section alphaextract
6126 Extract the alpha component from the input as a grayscale video. This
6127 is especially useful with the @var{alphamerge} filter.
6131 Add or replace the alpha component of the primary input with the
6132 grayscale value of a second input. This is intended for use with
6133 @var{alphaextract} to allow the transmission or storage of frame
6134 sequences that have alpha in a format that doesn't support an alpha
6137 For example, to reconstruct full frames from a normal YUV-encoded video
6138 and a separate video created with @var{alphaextract}, you might use:
6140 movie=in_alpha.mkv [alpha]; [in][alpha] alphamerge [out]
6143 Since this filter is designed for reconstruction, it operates on frame
6144 sequences without considering timestamps, and terminates when either
6145 input reaches end of stream. This will cause problems if your encoding
6146 pipeline drops frames. If you're trying to apply an image as an
6147 overlay to a video stream, consider the @var{overlay} filter instead.
6151 Amplify differences between current pixel and pixels of adjacent frames in
6152 same pixel location.
6154 This filter accepts the following options:
6158 Set frame radius. Default is 2. Allowed range is from 1 to 63.
6159 For example radius of 3 will instruct filter to calculate average of 7 frames.
6162 Set factor to amplify difference. Default is 2. Allowed range is from 0 to 65535.
6165 Set threshold for difference amplification. Any difference greater or equal to
6166 this value will not alter source pixel. Default is 10.
6167 Allowed range is from 0 to 65535.
6170 Set tolerance for difference amplification. Any difference lower to
6171 this value will not alter source pixel. Default is 0.
6172 Allowed range is from 0 to 65535.
6175 Set lower limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535.
6176 This option controls maximum possible value that will decrease source pixel value.
6179 Set high limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535.
6180 This option controls maximum possible value that will increase source pixel value.
6183 Set which planes to filter. Default is all. Allowed range is from 0 to 15.
6186 @subsection Commands
6188 This filter supports the following @ref{commands} that corresponds to option of same name:
6200 Same as the @ref{subtitles} filter, except that it doesn't require libavcodec
6201 and libavformat to work. On the other hand, it is limited to ASS (Advanced
6202 Substation Alpha) subtitles files.
6204 This filter accepts the following option in addition to the common options from
6205 the @ref{subtitles} filter:
6209 Set the shaping engine
6211 Available values are:
6214 The default libass shaping engine, which is the best available.
6216 Fast, font-agnostic shaper that can do only substitutions
6218 Slower shaper using OpenType for substitutions and positioning
6221 The default is @code{auto}.
6225 Apply an Adaptive Temporal Averaging Denoiser to the video input.
6227 The filter accepts the following options:
6231 Set threshold A for 1st plane. Default is 0.02.
6232 Valid range is 0 to 0.3.
6235 Set threshold B for 1st plane. Default is 0.04.
6236 Valid range is 0 to 5.
6239 Set threshold A for 2nd plane. Default is 0.02.
6240 Valid range is 0 to 0.3.
6243 Set threshold B for 2nd plane. Default is 0.04.
6244 Valid range is 0 to 5.
6247 Set threshold A for 3rd plane. Default is 0.02.
6248 Valid range is 0 to 0.3.
6251 Set threshold B for 3rd plane. Default is 0.04.
6252 Valid range is 0 to 5.
6254 Threshold A is designed to react on abrupt changes in the input signal and
6255 threshold B is designed to react on continuous changes in the input signal.
6258 Set number of frames filter will use for averaging. Default is 9. Must be odd
6259 number in range [5, 129].
6262 Set what planes of frame filter will use for averaging. Default is all.
6267 Apply average blur filter.
6269 The filter accepts the following options:
6273 Set horizontal radius size.
6276 Set which planes to filter. By default all planes are filtered.
6279 Set vertical radius size, if zero it will be same as @code{sizeX}.
6280 Default is @code{0}.
6283 @subsection Commands
6284 This filter supports same commands as options.
6285 The command accepts the same syntax of the corresponding option.
6287 If the specified expression is not valid, it is kept at its current
6292 Compute the bounding box for the non-black pixels in the input frame
6295 This filter computes the bounding box containing all the pixels with a
6296 luminance value greater than the minimum allowed value.
6297 The parameters describing the bounding box are printed on the filter
6300 The filter accepts the following option:
6304 Set the minimal luminance value. Default is @code{16}.
6307 @section bitplanenoise
6309 Show and measure bit plane noise.
6311 The filter accepts the following options:
6315 Set which plane to analyze. Default is @code{1}.
6318 Filter out noisy pixels from @code{bitplane} set above.
6319 Default is disabled.
6322 @section blackdetect
6324 Detect video intervals that are (almost) completely black. Can be
6325 useful to detect chapter transitions, commercials, or invalid
6326 recordings. Output lines contains the time for the start, end and
6327 duration of the detected black interval expressed in seconds.
6329 In order to display the output lines, you need to set the loglevel at
6330 least to the AV_LOG_INFO value.
6332 The filter accepts the following options:
6335 @item black_min_duration, d
6336 Set the minimum detected black duration expressed in seconds. It must
6337 be a non-negative floating point number.
6339 Default value is 2.0.
6341 @item picture_black_ratio_th, pic_th
6342 Set the threshold for considering a picture "black".
6343 Express the minimum value for the ratio:
6345 @var{nb_black_pixels} / @var{nb_pixels}
6348 for which a picture is considered black.
6349 Default value is 0.98.
6351 @item pixel_black_th, pix_th
6352 Set the threshold for considering a pixel "black".
6354 The threshold expresses the maximum pixel luminance value for which a
6355 pixel is considered "black". The provided value is scaled according to
6356 the following equation:
6358 @var{absolute_threshold} = @var{luminance_minimum_value} + @var{pixel_black_th} * @var{luminance_range_size}
6361 @var{luminance_range_size} and @var{luminance_minimum_value} depend on
6362 the input video format, the range is [0-255] for YUV full-range
6363 formats and [16-235] for YUV non full-range formats.
6365 Default value is 0.10.
6368 The following example sets the maximum pixel threshold to the minimum
6369 value, and detects only black intervals of 2 or more seconds:
6371 blackdetect=d=2:pix_th=0.00
6376 Detect frames that are (almost) completely black. Can be useful to
6377 detect chapter transitions or commercials. Output lines consist of
6378 the frame number of the detected frame, the percentage of blackness,
6379 the position in the file if known or -1 and the timestamp in seconds.
6381 In order to display the output lines, you need to set the loglevel at
6382 least to the AV_LOG_INFO value.
6384 This filter exports frame metadata @code{lavfi.blackframe.pblack}.
6385 The value represents the percentage of pixels in the picture that
6386 are below the threshold value.
6388 It accepts the following parameters:
6393 The percentage of the pixels that have to be below the threshold; it defaults to
6396 @item threshold, thresh
6397 The threshold below which a pixel value is considered black; it defaults to
6402 @section blend, tblend
6404 Blend two video frames into each other.
6406 The @code{blend} filter takes two input streams and outputs one
6407 stream, the first input is the "top" layer and second input is
6408 "bottom" layer. By default, the output terminates when the longest input terminates.
6410 The @code{tblend} (time blend) filter takes two consecutive frames
6411 from one single stream, and outputs the result obtained by blending
6412 the new frame on top of the old frame.
6414 A description of the accepted options follows.
6422 Set blend mode for specific pixel component or all pixel components in case
6423 of @var{all_mode}. Default value is @code{normal}.
6425 Available values for component modes are:
6467 Set blend opacity for specific pixel component or all pixel components in case
6468 of @var{all_opacity}. Only used in combination with pixel component blend modes.
6475 Set blend expression for specific pixel component or all pixel components in case
6476 of @var{all_expr}. Note that related mode options will be ignored if those are set.
6478 The expressions can use the following variables:
6482 The sequential number of the filtered frame, starting from @code{0}.
6486 the coordinates of the current sample
6490 the width and height of currently filtered plane
6494 Width and height scale for the plane being filtered. It is the
6495 ratio between the dimensions of the current plane to the luma plane,
6496 e.g. for a @code{yuv420p} frame, the values are @code{1,1} for
6497 the luma plane and @code{0.5,0.5} for the chroma planes.
6500 Time of the current frame, expressed in seconds.
6503 Value of pixel component at current location for first video frame (top layer).
6506 Value of pixel component at current location for second video frame (bottom layer).
6510 The @code{blend} filter also supports the @ref{framesync} options.
6512 @subsection Examples
6516 Apply transition from bottom layer to top layer in first 10 seconds:
6518 blend=all_expr='A*(if(gte(T,10),1,T/10))+B*(1-(if(gte(T,10),1,T/10)))'
6522 Apply linear horizontal transition from top layer to bottom layer:
6524 blend=all_expr='A*(X/W)+B*(1-X/W)'
6528 Apply 1x1 checkerboard effect:
6530 blend=all_expr='if(eq(mod(X,2),mod(Y,2)),A,B)'
6534 Apply uncover left effect:
6536 blend=all_expr='if(gte(N*SW+X,W),A,B)'
6540 Apply uncover down effect:
6542 blend=all_expr='if(gte(Y-N*SH,0),A,B)'
6546 Apply uncover up-left effect:
6548 blend=all_expr='if(gte(T*SH*40+Y,H)*gte((T*40*SW+X)*W/H,W),A,B)'
6552 Split diagonally video and shows top and bottom layer on each side:
6554 blend=all_expr='if(gt(X,Y*(W/H)),A,B)'
6558 Display differences between the current and the previous frame:
6560 tblend=all_mode=grainextract
6566 Denoise frames using Block-Matching 3D algorithm.
6568 The filter accepts the following options.
6572 Set denoising strength. Default value is 1.
6573 Allowed range is from 0 to 999.9.
6574 The denoising algorithm is very sensitive to sigma, so adjust it
6575 according to the source.
6578 Set local patch size. This sets dimensions in 2D.
6581 Set sliding step for processing blocks. Default value is 4.
6582 Allowed range is from 1 to 64.
6583 Smaller values allows processing more reference blocks and is slower.
6586 Set maximal number of similar blocks for 3rd dimension. Default value is 1.
6587 When set to 1, no block matching is done. Larger values allows more blocks
6589 Allowed range is from 1 to 256.
6592 Set radius for search block matching. Default is 9.
6593 Allowed range is from 1 to INT32_MAX.
6596 Set step between two search locations for block matching. Default is 1.
6597 Allowed range is from 1 to 64. Smaller is slower.
6600 Set threshold of mean square error for block matching. Valid range is 0 to
6604 Set thresholding parameter for hard thresholding in 3D transformed domain.
6605 Larger values results in stronger hard-thresholding filtering in frequency
6609 Set filtering estimation mode. Can be @code{basic} or @code{final}.
6610 Default is @code{basic}.
6613 If enabled, filter will use 2nd stream for block matching.
6614 Default is disabled for @code{basic} value of @var{estim} option,
6615 and always enabled if value of @var{estim} is @code{final}.
6618 Set planes to filter. Default is all available except alpha.
6621 @subsection Examples
6625 Basic filtering with bm3d:
6627 bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic
6631 Same as above, but filtering only luma:
6633 bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic:planes=1
6637 Same as above, but with both estimation modes:
6639 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
6643 Same as above, but prefilter with @ref{nlmeans} filter instead:
6645 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
6651 Apply a boxblur algorithm to the input video.
6653 It accepts the following parameters:
6657 @item luma_radius, lr
6658 @item luma_power, lp
6659 @item chroma_radius, cr
6660 @item chroma_power, cp
6661 @item alpha_radius, ar
6662 @item alpha_power, ap
6666 A description of the accepted options follows.
6669 @item luma_radius, lr
6670 @item chroma_radius, cr
6671 @item alpha_radius, ar
6672 Set an expression for the box radius in pixels used for blurring the
6673 corresponding input plane.
6675 The radius value must be a non-negative number, and must not be
6676 greater than the value of the expression @code{min(w,h)/2} for the
6677 luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma
6680 Default value for @option{luma_radius} is "2". If not specified,
6681 @option{chroma_radius} and @option{alpha_radius} default to the
6682 corresponding value set for @option{luma_radius}.
6684 The expressions can contain the following constants:
6688 The input width and height in pixels.
6692 The input chroma image width and height in pixels.
6696 The horizontal and vertical chroma subsample values. For example, for the
6697 pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1.
6700 @item luma_power, lp
6701 @item chroma_power, cp
6702 @item alpha_power, ap
6703 Specify how many times the boxblur filter is applied to the
6704 corresponding plane.
6706 Default value for @option{luma_power} is 2. If not specified,
6707 @option{chroma_power} and @option{alpha_power} default to the
6708 corresponding value set for @option{luma_power}.
6710 A value of 0 will disable the effect.
6713 @subsection Examples
6717 Apply a boxblur filter with the luma, chroma, and alpha radii
6720 boxblur=luma_radius=2:luma_power=1
6725 Set the luma radius to 2, and alpha and chroma radius to 0:
6727 boxblur=2:1:cr=0:ar=0
6731 Set the luma and chroma radii to a fraction of the video dimension:
6733 boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1
6739 Deinterlace the input video ("bwdif" stands for "Bob Weaver
6740 Deinterlacing Filter").
6742 Motion adaptive deinterlacing based on yadif with the use of w3fdif and cubic
6743 interpolation algorithms.
6744 It accepts the following parameters:
6748 The interlacing mode to adopt. It accepts one of the following values:
6752 Output one frame for each frame.
6754 Output one frame for each field.
6757 The default value is @code{send_field}.
6760 The picture field parity assumed for the input interlaced video. It accepts one
6761 of the following values:
6765 Assume the top field is first.
6767 Assume the bottom field is first.
6769 Enable automatic detection of field parity.
6772 The default value is @code{auto}.
6773 If the interlacing is unknown or the decoder does not export this information,
6774 top field first will be assumed.
6777 Specify which frames to deinterlace. Accepts one of the following
6782 Deinterlace all frames.
6784 Only deinterlace frames marked as interlaced.
6787 The default value is @code{all}.
6791 Remove all color information for all colors except for certain one.
6793 The filter accepts the following options:
6797 The color which will not be replaced with neutral chroma.
6800 Similarity percentage with the above color.
6801 0.01 matches only the exact key color, while 1.0 matches everything.
6805 0.0 makes pixels either fully gray, or not gray at all.
6806 Higher values result in more preserved color.
6809 Signals that the color passed is already in YUV instead of RGB.
6811 Literal colors like "green" or "red" don't make sense with this enabled anymore.
6812 This can be used to pass exact YUV values as hexadecimal numbers.
6816 YUV colorspace color/chroma keying.
6818 The filter accepts the following options:
6822 The color which will be replaced with transparency.
6825 Similarity percentage with the key color.
6827 0.01 matches only the exact key color, while 1.0 matches everything.
6832 0.0 makes pixels either fully transparent, or not transparent at all.
6834 Higher values result in semi-transparent pixels, with a higher transparency
6835 the more similar the pixels color is to the key color.
6838 Signals that the color passed is already in YUV instead of RGB.
6840 Literal colors like "green" or "red" don't make sense with this enabled anymore.
6841 This can be used to pass exact YUV values as hexadecimal numbers.
6844 @subsection Examples
6848 Make every green pixel in the input image transparent:
6850 ffmpeg -i input.png -vf chromakey=green out.png
6854 Overlay a greenscreen-video on top of a static black background.
6856 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
6860 @section chromashift
6861 Shift chroma pixels horizontally and/or vertically.
6863 The filter accepts the following options:
6866 Set amount to shift chroma-blue horizontally.
6868 Set amount to shift chroma-blue vertically.
6870 Set amount to shift chroma-red horizontally.
6872 Set amount to shift chroma-red vertically.
6874 Set edge mode, can be @var{smear}, default, or @var{warp}.
6879 Display CIE color diagram with pixels overlaid onto it.
6881 The filter accepts the following options:
6896 @item uhdtv, rec2020
6910 Set what gamuts to draw.
6912 See @code{system} option for available values.
6915 Set ciescope size, by default set to 512.
6918 Set intensity used to map input pixel values to CIE diagram.
6921 Set contrast used to draw tongue colors that are out of active color system gamut.
6924 Correct gamma displayed on scope, by default enabled.
6927 Show white point on CIE diagram, by default disabled.
6930 Set input gamma. Used only with XYZ input color space.
6935 Visualize information exported by some codecs.
6937 Some codecs can export information through frames using side-data or other
6938 means. For example, some MPEG based codecs export motion vectors through the
6939 @var{export_mvs} flag in the codec @option{flags2} option.
6941 The filter accepts the following option:
6945 Set motion vectors to visualize.
6947 Available flags for @var{mv} are:
6951 forward predicted MVs of P-frames
6953 forward predicted MVs of B-frames
6955 backward predicted MVs of B-frames
6959 Display quantization parameters using the chroma planes.
6962 Set motion vectors type to visualize. Includes MVs from all frames unless specified by @var{frame_type} option.
6964 Available flags for @var{mv_type} are:
6968 forward predicted MVs
6970 backward predicted MVs
6973 @item frame_type, ft
6974 Set frame type to visualize motion vectors of.
6976 Available flags for @var{frame_type} are:
6980 intra-coded frames (I-frames)
6982 predicted frames (P-frames)
6984 bi-directionally predicted frames (B-frames)
6988 @subsection Examples
6992 Visualize forward predicted MVs of all frames using @command{ffplay}:
6994 ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv_type=fp
6998 Visualize multi-directionals MVs of P and B-Frames using @command{ffplay}:
7000 ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv=pf+bf+bb
7004 @section colorbalance
7005 Modify intensity of primary colors (red, green and blue) of input frames.
7007 The filter allows an input frame to be adjusted in the shadows, midtones or highlights
7008 regions for the red-cyan, green-magenta or blue-yellow balance.
7010 A positive adjustment value shifts the balance towards the primary color, a negative
7011 value towards the complementary color.
7013 The filter accepts the following options:
7019 Adjust red, green and blue shadows (darkest pixels).
7024 Adjust red, green and blue midtones (medium pixels).
7029 Adjust red, green and blue highlights (brightest pixels).
7031 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
7034 @subsection Examples
7038 Add red color cast to shadows:
7044 @section colorchannelmixer
7046 Adjust video input frames by re-mixing color channels.
7048 This filter modifies a color channel by adding the values associated to
7049 the other channels of the same pixels. For example if the value to
7050 modify is red, the output value will be:
7052 @var{red}=@var{red}*@var{rr} + @var{blue}*@var{rb} + @var{green}*@var{rg} + @var{alpha}*@var{ra}
7055 The filter accepts the following options:
7062 Adjust contribution of input red, green, blue and alpha channels for output red channel.
7063 Default is @code{1} for @var{rr}, and @code{0} for @var{rg}, @var{rb} and @var{ra}.
7069 Adjust contribution of input red, green, blue and alpha channels for output green channel.
7070 Default is @code{1} for @var{gg}, and @code{0} for @var{gr}, @var{gb} and @var{ga}.
7076 Adjust contribution of input red, green, blue and alpha channels for output blue channel.
7077 Default is @code{1} for @var{bb}, and @code{0} for @var{br}, @var{bg} and @var{ba}.
7083 Adjust contribution of input red, green, blue and alpha channels for output alpha channel.
7084 Default is @code{1} for @var{aa}, and @code{0} for @var{ar}, @var{ag} and @var{ab}.
7086 Allowed ranges for options are @code{[-2.0, 2.0]}.
7089 @subsection Examples
7093 Convert source to grayscale:
7095 colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3
7098 Simulate sepia tones:
7100 colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131
7104 @subsection Commands
7106 This filter supports the all above options as @ref{commands}.
7109 RGB colorspace color keying.
7111 The filter accepts the following options:
7115 The color which will be replaced with transparency.
7118 Similarity percentage with the key color.
7120 0.01 matches only the exact key color, while 1.0 matches everything.
7125 0.0 makes pixels either fully transparent, or not transparent at all.
7127 Higher values result in semi-transparent pixels, with a higher transparency
7128 the more similar the pixels color is to the key color.
7131 @subsection Examples
7135 Make every green pixel in the input image transparent:
7137 ffmpeg -i input.png -vf colorkey=green out.png
7141 Overlay a greenscreen-video on top of a static background image.
7143 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
7148 Remove all color information for all RGB colors except for certain one.
7150 The filter accepts the following options:
7154 The color which will not be replaced with neutral gray.
7157 Similarity percentage with the above color.
7158 0.01 matches only the exact key color, while 1.0 matches everything.
7161 Blend percentage. 0.0 makes pixels fully gray.
7162 Higher values result in more preserved color.
7165 @section colorlevels
7167 Adjust video input frames using levels.
7169 The filter accepts the following options:
7176 Adjust red, green, blue and alpha input black point.
7177 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
7183 Adjust red, green, blue and alpha input white point.
7184 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{1}.
7186 Input levels are used to lighten highlights (bright tones), darken shadows
7187 (dark tones), change the balance of bright and dark tones.
7193 Adjust red, green, blue and alpha output black point.
7194 Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{0}.
7200 Adjust red, green, blue and alpha output white point.
7201 Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{1}.
7203 Output levels allows manual selection of a constrained output level range.
7206 @subsection Examples
7210 Make video output darker:
7212 colorlevels=rimin=0.058:gimin=0.058:bimin=0.058
7218 colorlevels=rimin=0.039:gimin=0.039:bimin=0.039:rimax=0.96:gimax=0.96:bimax=0.96
7222 Make video output lighter:
7224 colorlevels=rimax=0.902:gimax=0.902:bimax=0.902
7228 Increase brightness:
7230 colorlevels=romin=0.5:gomin=0.5:bomin=0.5
7234 @section colormatrix
7236 Convert color matrix.
7238 The filter accepts the following options:
7243 Specify the source and destination color matrix. Both values must be
7246 The accepted values are:
7274 For example to convert from BT.601 to SMPTE-240M, use the command:
7276 colormatrix=bt601:smpte240m
7281 Convert colorspace, transfer characteristics or color primaries.
7282 Input video needs to have an even size.
7284 The filter accepts the following options:
7289 Specify all color properties at once.
7291 The accepted values are:
7321 Specify output colorspace.
7323 The accepted values are:
7332 BT.470BG or BT.601-6 625
7335 SMPTE-170M or BT.601-6 525
7344 BT.2020 with non-constant luminance
7350 Specify output transfer characteristics.
7352 The accepted values are:
7364 Constant gamma of 2.2
7367 Constant gamma of 2.8
7370 SMPTE-170M, BT.601-6 625 or BT.601-6 525
7388 BT.2020 for 10-bits content
7391 BT.2020 for 12-bits content
7397 Specify output color primaries.
7399 The accepted values are:
7408 BT.470BG or BT.601-6 625
7411 SMPTE-170M or BT.601-6 525
7435 Specify output color range.
7437 The accepted values are:
7440 TV (restricted) range
7443 MPEG (restricted) range
7454 Specify output color format.
7456 The accepted values are:
7459 YUV 4:2:0 planar 8-bits
7462 YUV 4:2:0 planar 10-bits
7465 YUV 4:2:0 planar 12-bits
7468 YUV 4:2:2 planar 8-bits
7471 YUV 4:2:2 planar 10-bits
7474 YUV 4:2:2 planar 12-bits
7477 YUV 4:4:4 planar 8-bits
7480 YUV 4:4:4 planar 10-bits
7483 YUV 4:4:4 planar 12-bits
7488 Do a fast conversion, which skips gamma/primary correction. This will take
7489 significantly less CPU, but will be mathematically incorrect. To get output
7490 compatible with that produced by the colormatrix filter, use fast=1.
7493 Specify dithering mode.
7495 The accepted values are:
7501 Floyd-Steinberg dithering
7505 Whitepoint adaptation mode.
7507 The accepted values are:
7510 Bradford whitepoint adaptation
7513 von Kries whitepoint adaptation
7516 identity whitepoint adaptation (i.e. no whitepoint adaptation)
7520 Override all input properties at once. Same accepted values as @ref{all}.
7523 Override input colorspace. Same accepted values as @ref{space}.
7526 Override input color primaries. Same accepted values as @ref{primaries}.
7529 Override input transfer characteristics. Same accepted values as @ref{trc}.
7532 Override input color range. Same accepted values as @ref{range}.
7536 The filter converts the transfer characteristics, color space and color
7537 primaries to the specified user values. The output value, if not specified,
7538 is set to a default value based on the "all" property. If that property is
7539 also not specified, the filter will log an error. The output color range and
7540 format default to the same value as the input color range and format. The
7541 input transfer characteristics, color space, color primaries and color range
7542 should be set on the input data. If any of these are missing, the filter will
7543 log an error and no conversion will take place.
7545 For example to convert the input to SMPTE-240M, use the command:
7547 colorspace=smpte240m
7550 @section convolution
7552 Apply convolution of 3x3, 5x5, 7x7 or horizontal/vertical up to 49 elements.
7554 The filter accepts the following options:
7561 Set matrix for each plane.
7562 Matrix is sequence of 9, 25 or 49 signed integers in @var{square} mode,
7563 and from 1 to 49 odd number of signed integers in @var{row} mode.
7569 Set multiplier for calculated value for each plane.
7570 If unset or 0, it will be sum of all matrix elements.
7576 Set bias for each plane. This value is added to the result of the multiplication.
7577 Useful for making the overall image brighter or darker. Default is 0.0.
7583 Set matrix mode for each plane. Can be @var{square}, @var{row} or @var{column}.
7584 Default is @var{square}.
7587 @subsection Examples
7593 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"
7599 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"
7605 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"
7611 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"
7615 Apply laplacian edge detector which includes diagonals:
7617 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"
7623 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"
7629 Apply 2D convolution of video stream in frequency domain using second stream
7632 The filter accepts the following options:
7636 Set which planes to process.
7639 Set which impulse video frames will be processed, can be @var{first}
7640 or @var{all}. Default is @var{all}.
7643 The @code{convolve} filter also supports the @ref{framesync} options.
7647 Copy the input video source unchanged to the output. This is mainly useful for
7652 Video filtering on GPU using Apple's CoreImage API on OSX.
7654 Hardware acceleration is based on an OpenGL context. Usually, this means it is
7655 processed by video hardware. However, software-based OpenGL implementations
7656 exist which means there is no guarantee for hardware processing. It depends on
7659 There are many filters and image generators provided by Apple that come with a
7660 large variety of options. The filter has to be referenced by its name along
7663 The coreimage filter accepts the following options:
7666 List all available filters and generators along with all their respective
7667 options as well as possible minimum and maximum values along with the default
7674 Specify all filters by their respective name and options.
7675 Use @var{list_filters} to determine all valid filter names and options.
7676 Numerical options are specified by a float value and are automatically clamped
7677 to their respective value range. Vector and color options have to be specified
7678 by a list of space separated float values. Character escaping has to be done.
7679 A special option name @code{default} is available to use default options for a
7682 It is required to specify either @code{default} or at least one of the filter options.
7683 All omitted options are used with their default values.
7684 The syntax of the filter string is as follows:
7686 filter=<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...][#<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...]][#...]
7690 Specify a rectangle where the output of the filter chain is copied into the
7691 input image. It is given by a list of space separated float values:
7693 output_rect=x\ y\ width\ height
7695 If not given, the output rectangle equals the dimensions of the input image.
7696 The output rectangle is automatically cropped at the borders of the input
7697 image. Negative values are valid for each component.
7699 output_rect=25\ 25\ 100\ 100
7703 Several filters can be chained for successive processing without GPU-HOST
7704 transfers allowing for fast processing of complex filter chains.
7705 Currently, only filters with zero (generators) or exactly one (filters) input
7706 image and one output image are supported. Also, transition filters are not yet
7709 Some filters generate output images with additional padding depending on the
7710 respective filter kernel. The padding is automatically removed to ensure the
7711 filter output has the same size as the input image.
7713 For image generators, the size of the output image is determined by the
7714 previous output image of the filter chain or the input image of the whole
7715 filterchain, respectively. The generators do not use the pixel information of
7716 this image to generate their output. However, the generated output is
7717 blended onto this image, resulting in partial or complete coverage of the
7720 The @ref{coreimagesrc} video source can be used for generating input images
7721 which are directly fed into the filter chain. By using it, providing input
7722 images by another video source or an input video is not required.
7724 @subsection Examples
7729 List all filters available:
7731 coreimage=list_filters=true
7735 Use the CIBoxBlur filter with default options to blur an image:
7737 coreimage=filter=CIBoxBlur@@default
7741 Use a filter chain with CISepiaTone at default values and CIVignetteEffect with
7742 its center at 100x100 and a radius of 50 pixels:
7744 coreimage=filter=CIBoxBlur@@default#CIVignetteEffect@@inputCenter=100\ 100@@inputRadius=50
7748 Use nullsrc and CIQRCodeGenerator to create a QR code for the FFmpeg homepage,
7749 given as complete and escaped command-line for Apple's standard bash shell:
7751 ffmpeg -f lavfi -i nullsrc=s=100x100,coreimage=filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png
7757 Cover a rectangular object
7759 It accepts the following options:
7763 Filepath of the optional cover image, needs to be in yuv420.
7768 It accepts the following values:
7771 cover it by the supplied image
7773 cover it by interpolating the surrounding pixels
7776 Default value is @var{blur}.
7779 @subsection Examples
7783 Cover a rectangular object by the supplied image of a given video using @command{ffmpeg}:
7785 ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
7791 Crop the input video to given dimensions.
7793 It accepts the following parameters:
7797 The width of the output video. It defaults to @code{iw}.
7798 This expression is evaluated only once during the filter
7799 configuration, or when the @samp{w} or @samp{out_w} command is sent.
7802 The height of the output video. It defaults to @code{ih}.
7803 This expression is evaluated only once during the filter
7804 configuration, or when the @samp{h} or @samp{out_h} command is sent.
7807 The horizontal position, in the input video, of the left edge of the output
7808 video. It defaults to @code{(in_w-out_w)/2}.
7809 This expression is evaluated per-frame.
7812 The vertical position, in the input video, of the top edge of the output video.
7813 It defaults to @code{(in_h-out_h)/2}.
7814 This expression is evaluated per-frame.
7817 If set to 1 will force the output display aspect ratio
7818 to be the same of the input, by changing the output sample aspect
7819 ratio. It defaults to 0.
7822 Enable exact cropping. If enabled, subsampled videos will be cropped at exact
7823 width/height/x/y as specified and will not be rounded to nearest smaller value.
7827 The @var{out_w}, @var{out_h}, @var{x}, @var{y} parameters are
7828 expressions containing the following constants:
7833 The computed values for @var{x} and @var{y}. They are evaluated for
7838 The input width and height.
7842 These are the same as @var{in_w} and @var{in_h}.
7846 The output (cropped) width and height.
7850 These are the same as @var{out_w} and @var{out_h}.
7853 same as @var{iw} / @var{ih}
7856 input sample aspect ratio
7859 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
7863 horizontal and vertical chroma subsample values. For example for the
7864 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
7867 The number of the input frame, starting from 0.
7870 the position in the file of the input frame, NAN if unknown
7873 The timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
7877 The expression for @var{out_w} may depend on the value of @var{out_h},
7878 and the expression for @var{out_h} may depend on @var{out_w}, but they
7879 cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are
7880 evaluated after @var{out_w} and @var{out_h}.
7882 The @var{x} and @var{y} parameters specify the expressions for the
7883 position of the top-left corner of the output (non-cropped) area. They
7884 are evaluated for each frame. If the evaluated value is not valid, it
7885 is approximated to the nearest valid value.
7887 The expression for @var{x} may depend on @var{y}, and the expression
7888 for @var{y} may depend on @var{x}.
7890 @subsection Examples
7894 Crop area with size 100x100 at position (12,34).
7899 Using named options, the example above becomes:
7901 crop=w=100:h=100:x=12:y=34
7905 Crop the central input area with size 100x100:
7911 Crop the central input area with size 2/3 of the input video:
7913 crop=2/3*in_w:2/3*in_h
7917 Crop the input video central square:
7924 Delimit the rectangle with the top-left corner placed at position
7925 100:100 and the right-bottom corner corresponding to the right-bottom
7926 corner of the input image.
7928 crop=in_w-100:in_h-100:100:100
7932 Crop 10 pixels from the left and right borders, and 20 pixels from
7933 the top and bottom borders
7935 crop=in_w-2*10:in_h-2*20
7939 Keep only the bottom right quarter of the input image:
7941 crop=in_w/2:in_h/2:in_w/2:in_h/2
7945 Crop height for getting Greek harmony:
7947 crop=in_w:1/PHI*in_w
7951 Apply trembling effect:
7953 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)
7957 Apply erratic camera effect depending on timestamp:
7959 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)"
7963 Set x depending on the value of y:
7965 crop=in_w/2:in_h/2:y:10+10*sin(n/10)
7969 @subsection Commands
7971 This filter supports the following commands:
7977 Set width/height of the output video and the horizontal/vertical position
7979 The command accepts the same syntax of the corresponding option.
7981 If the specified expression is not valid, it is kept at its current
7987 Auto-detect the crop size.
7989 It calculates the necessary cropping parameters and prints the
7990 recommended parameters via the logging system. The detected dimensions
7991 correspond to the non-black area of the input video.
7993 It accepts the following parameters:
7998 Set higher black value threshold, which can be optionally specified
7999 from nothing (0) to everything (255 for 8-bit based formats). An intensity
8000 value greater to the set value is considered non-black. It defaults to 24.
8001 You can also specify a value between 0.0 and 1.0 which will be scaled depending
8002 on the bitdepth of the pixel format.
8005 The value which the width/height should be divisible by. It defaults to
8006 16. The offset is automatically adjusted to center the video. Use 2 to
8007 get only even dimensions (needed for 4:2:2 video). 16 is best when
8008 encoding to most video codecs.
8010 @item reset_count, reset
8011 Set the counter that determines after how many frames cropdetect will
8012 reset the previously detected largest video area and start over to
8013 detect the current optimal crop area. Default value is 0.
8015 This can be useful when channel logos distort the video area. 0
8016 indicates 'never reset', and returns the largest area encountered during
8023 Delay video filtering until a given wallclock timestamp. The filter first
8024 passes on @option{preroll} amount of frames, then it buffers at most
8025 @option{buffer} amount of frames and waits for the cue. After reaching the cue
8026 it forwards the buffered frames and also any subsequent frames coming in its
8029 The filter can be used synchronize the output of multiple ffmpeg processes for
8030 realtime output devices like decklink. By putting the delay in the filtering
8031 chain and pre-buffering frames the process can pass on data to output almost
8032 immediately after the target wallclock timestamp is reached.
8034 Perfect frame accuracy cannot be guaranteed, but the result is good enough for
8040 The cue timestamp expressed in a UNIX timestamp in microseconds. Default is 0.
8043 The duration of content to pass on as preroll expressed in seconds. Default is 0.
8046 The maximum duration of content to buffer before waiting for the cue expressed
8047 in seconds. Default is 0.
8054 Apply color adjustments using curves.
8056 This filter is similar to the Adobe Photoshop and GIMP curves tools. Each
8057 component (red, green and blue) has its values defined by @var{N} key points
8058 tied from each other using a smooth curve. The x-axis represents the pixel
8059 values from the input frame, and the y-axis the new pixel values to be set for
8062 By default, a component curve is defined by the two points @var{(0;0)} and
8063 @var{(1;1)}. This creates a straight line where each original pixel value is
8064 "adjusted" to its own value, which means no change to the image.
8066 The filter allows you to redefine these two points and add some more. A new
8067 curve (using a natural cubic spline interpolation) will be define to pass
8068 smoothly through all these new coordinates. The new defined points needs to be
8069 strictly increasing over the x-axis, and their @var{x} and @var{y} values must
8070 be in the @var{[0;1]} interval. If the computed curves happened to go outside
8071 the vector spaces, the values will be clipped accordingly.
8073 The filter accepts the following options:
8077 Select one of the available color presets. This option can be used in addition
8078 to the @option{r}, @option{g}, @option{b} parameters; in this case, the later
8079 options takes priority on the preset values.
8080 Available presets are:
8083 @item color_negative
8086 @item increase_contrast
8088 @item linear_contrast
8089 @item medium_contrast
8091 @item strong_contrast
8094 Default is @code{none}.
8096 Set the master key points. These points will define a second pass mapping. It
8097 is sometimes called a "luminance" or "value" mapping. It can be used with
8098 @option{r}, @option{g}, @option{b} or @option{all} since it acts like a
8099 post-processing LUT.
8101 Set the key points for the red component.
8103 Set the key points for the green component.
8105 Set the key points for the blue component.
8107 Set the key points for all components (not including master).
8108 Can be used in addition to the other key points component
8109 options. In this case, the unset component(s) will fallback on this
8110 @option{all} setting.
8112 Specify a Photoshop curves file (@code{.acv}) to import the settings from.
8114 Save Gnuplot script of the curves in specified file.
8117 To avoid some filtergraph syntax conflicts, each key points list need to be
8118 defined using the following syntax: @code{x0/y0 x1/y1 x2/y2 ...}.
8120 @subsection Examples
8124 Increase slightly the middle level of blue:
8126 curves=blue='0/0 0.5/0.58 1/1'
8132 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'
8134 Here we obtain the following coordinates for each components:
8137 @code{(0;0.11) (0.42;0.51) (1;0.95)}
8139 @code{(0;0) (0.50;0.48) (1;1)}
8141 @code{(0;0.22) (0.49;0.44) (1;0.80)}
8145 The previous example can also be achieved with the associated built-in preset:
8147 curves=preset=vintage
8157 Use a Photoshop preset and redefine the points of the green component:
8159 curves=psfile='MyCurvesPresets/purple.acv':green='0/0 0.45/0.53 1/1'
8163 Check out the curves of the @code{cross_process} profile using @command{ffmpeg}
8164 and @command{gnuplot}:
8166 ffmpeg -f lavfi -i color -vf curves=cross_process:plot=/tmp/curves.plt -frames:v 1 -f null -
8167 gnuplot -p /tmp/curves.plt
8173 Video data analysis filter.
8175 This filter shows hexadecimal pixel values of part of video.
8177 The filter accepts the following options:
8181 Set output video size.
8184 Set x offset from where to pick pixels.
8187 Set y offset from where to pick pixels.
8190 Set scope mode, can be one of the following:
8193 Draw hexadecimal pixel values with white color on black background.
8196 Draw hexadecimal pixel values with input video pixel color on black
8200 Draw hexadecimal pixel values on color background picked from input video,
8201 the text color is picked in such way so its always visible.
8205 Draw rows and columns numbers on left and top of video.
8208 Set background opacity.
8213 Denoise frames using 2D DCT (frequency domain filtering).
8215 This filter is not designed for real time.
8217 The filter accepts the following options:
8221 Set the noise sigma constant.
8223 This @var{sigma} defines a hard threshold of @code{3 * sigma}; every DCT
8224 coefficient (absolute value) below this threshold with be dropped.
8226 If you need a more advanced filtering, see @option{expr}.
8228 Default is @code{0}.
8231 Set number overlapping pixels for each block. Since the filter can be slow, you
8232 may want to reduce this value, at the cost of a less effective filter and the
8233 risk of various artefacts.
8235 If the overlapping value doesn't permit processing the whole input width or
8236 height, a warning will be displayed and according borders won't be denoised.
8238 Default value is @var{blocksize}-1, which is the best possible setting.
8241 Set the coefficient factor expression.
8243 For each coefficient of a DCT block, this expression will be evaluated as a
8244 multiplier value for the coefficient.
8246 If this is option is set, the @option{sigma} option will be ignored.
8248 The absolute value of the coefficient can be accessed through the @var{c}
8252 Set the @var{blocksize} using the number of bits. @code{1<<@var{n}} defines the
8253 @var{blocksize}, which is the width and height of the processed blocks.
8255 The default value is @var{3} (8x8) and can be raised to @var{4} for a
8256 @var{blocksize} of 16x16. Note that changing this setting has huge consequences
8257 on the speed processing. Also, a larger block size does not necessarily means a
8261 @subsection Examples
8263 Apply a denoise with a @option{sigma} of @code{4.5}:
8268 The same operation can be achieved using the expression system:
8270 dctdnoiz=e='gte(c, 4.5*3)'
8273 Violent denoise using a block size of @code{16x16}:
8280 Remove banding artifacts from input video.
8281 It works by replacing banded pixels with average value of referenced pixels.
8283 The filter accepts the following options:
8290 Set banding detection threshold for each plane. Default is 0.02.
8291 Valid range is 0.00003 to 0.5.
8292 If difference between current pixel and reference pixel is less than threshold,
8293 it will be considered as banded.
8296 Banding detection range in pixels. Default is 16. If positive, random number
8297 in range 0 to set value will be used. If negative, exact absolute value
8299 The range defines square of four pixels around current pixel.
8302 Set direction in radians from which four pixel will be compared. If positive,
8303 random direction from 0 to set direction will be picked. If negative, exact of
8304 absolute value will be picked. For example direction 0, -PI or -2*PI radians
8305 will pick only pixels on same row and -PI/2 will pick only pixels on same
8309 If enabled, current pixel is compared with average value of all four
8310 surrounding pixels. The default is enabled. If disabled current pixel is
8311 compared with all four surrounding pixels. The pixel is considered banded
8312 if only all four differences with surrounding pixels are less than threshold.
8315 If enabled, current pixel is changed if and only if all pixel components are banded,
8316 e.g. banding detection threshold is triggered for all color components.
8317 The default is disabled.
8322 Remove blocking artifacts from input video.
8324 The filter accepts the following options:
8328 Set filter type, can be @var{weak} or @var{strong}. Default is @var{strong}.
8329 This controls what kind of deblocking is applied.
8332 Set size of block, allowed range is from 4 to 512. Default is @var{8}.
8338 Set blocking detection thresholds. Allowed range is 0 to 1.
8339 Defaults are: @var{0.098} for @var{alpha} and @var{0.05} for the rest.
8340 Using higher threshold gives more deblocking strength.
8341 Setting @var{alpha} controls threshold detection at exact edge of block.
8342 Remaining options controls threshold detection near the edge. Each one for
8343 below/above or left/right. Setting any of those to @var{0} disables
8347 Set planes to filter. Default is to filter all available planes.
8350 @subsection Examples
8354 Deblock using weak filter and block size of 4 pixels.
8356 deblock=filter=weak:block=4
8360 Deblock using strong filter, block size of 4 pixels and custom thresholds for
8361 deblocking more edges.
8363 deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05
8367 Similar as above, but filter only first plane.
8369 deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=1
8373 Similar as above, but filter only second and third plane.
8375 deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=6
8382 Drop duplicated frames at regular intervals.
8384 The filter accepts the following options:
8388 Set the number of frames from which one will be dropped. Setting this to
8389 @var{N} means one frame in every batch of @var{N} frames will be dropped.
8390 Default is @code{5}.
8393 Set the threshold for duplicate detection. If the difference metric for a frame
8394 is less than or equal to this value, then it is declared as duplicate. Default
8398 Set scene change threshold. Default is @code{15}.
8402 Set the size of the x and y-axis blocks used during metric calculations.
8403 Larger blocks give better noise suppression, but also give worse detection of
8404 small movements. Must be a power of two. Default is @code{32}.
8407 Mark main input as a pre-processed input and activate clean source input
8408 stream. This allows the input to be pre-processed with various filters to help
8409 the metrics calculation while keeping the frame selection lossless. When set to
8410 @code{1}, the first stream is for the pre-processed input, and the second
8411 stream is the clean source from where the kept frames are chosen. Default is
8415 Set whether or not chroma is considered in the metric calculations. Default is
8421 Apply 2D deconvolution of video stream in frequency domain using second stream
8424 The filter accepts the following options:
8428 Set which planes to process.
8431 Set which impulse video frames will be processed, can be @var{first}
8432 or @var{all}. Default is @var{all}.
8435 Set noise when doing divisions. Default is @var{0.0000001}. Useful when width
8436 and height are not same and not power of 2 or if stream prior to convolving
8440 The @code{deconvolve} filter also supports the @ref{framesync} options.
8444 Reduce cross-luminance (dot-crawl) and cross-color (rainbows) from video.
8446 It accepts the following options:
8450 Set mode of operation. Can be combination of @var{dotcrawl} for cross-luminance reduction and/or
8451 @var{rainbows} for cross-color reduction.
8454 Set spatial luma threshold. Lower values increases reduction of cross-luminance.
8457 Set tolerance for temporal luma. Higher values increases reduction of cross-luminance.
8460 Set tolerance for chroma temporal variation. Higher values increases reduction of cross-color.
8463 Set temporal chroma threshold. Lower values increases reduction of cross-color.
8468 Apply deflate effect to the video.
8470 This filter replaces the pixel by the local(3x3) average by taking into account
8471 only values lower than the pixel.
8473 It accepts the following options:
8480 Limit the maximum change for each plane, default is 65535.
8481 If 0, plane will remain unchanged.
8486 Remove temporal frame luminance variations.
8488 It accepts the following options:
8492 Set moving-average filter size in frames. Default is 5. Allowed range is 2 - 129.
8495 Set averaging mode to smooth temporal luminance variations.
8497 Available values are:
8522 Do not actually modify frame. Useful when one only wants metadata.
8527 Remove judder produced by partially interlaced telecined content.
8529 Judder can be introduced, for instance, by @ref{pullup} filter. If the original
8530 source was partially telecined content then the output of @code{pullup,dejudder}
8531 will have a variable frame rate. May change the recorded frame rate of the
8532 container. Aside from that change, this filter will not affect constant frame
8535 The option available in this filter is:
8539 Specify the length of the window over which the judder repeats.
8541 Accepts any integer greater than 1. Useful values are:
8545 If the original was telecined from 24 to 30 fps (Film to NTSC).
8548 If the original was telecined from 25 to 30 fps (PAL to NTSC).
8551 If a mixture of the two.
8554 The default is @samp{4}.
8559 Suppress a TV station logo by a simple interpolation of the surrounding
8560 pixels. Just set a rectangle covering the logo and watch it disappear
8561 (and sometimes something even uglier appear - your mileage may vary).
8563 It accepts the following parameters:
8568 Specify the top left corner coordinates of the logo. They must be
8573 Specify the width and height of the logo to clear. They must be
8577 Specify the thickness of the fuzzy edge of the rectangle (added to
8578 @var{w} and @var{h}). The default value is 1. This option is
8579 deprecated, setting higher values should no longer be necessary and
8583 When set to 1, a green rectangle is drawn on the screen to simplify
8584 finding the right @var{x}, @var{y}, @var{w}, and @var{h} parameters.
8585 The default value is 0.
8587 The rectangle is drawn on the outermost pixels which will be (partly)
8588 replaced with interpolated values. The values of the next pixels
8589 immediately outside this rectangle in each direction will be used to
8590 compute the interpolated pixel values inside the rectangle.
8594 @subsection Examples
8598 Set a rectangle covering the area with top left corner coordinates 0,0
8599 and size 100x77, and a band of size 10:
8601 delogo=x=0:y=0:w=100:h=77:band=10
8608 Remove the rain in the input image/video by applying the derain methods based on
8609 convolutional neural networks. Supported models:
8613 Recurrent Squeeze-and-Excitation Context Aggregation Net (RESCAN).
8614 See @url{http://openaccess.thecvf.com/content_ECCV_2018/papers/Xia_Li_Recurrent_Squeeze-and-Excitation_Context_ECCV_2018_paper.pdf}.
8617 Training as well as model generation scripts are provided in
8618 the repository at @url{https://github.com/XueweiMeng/derain_filter.git}.
8620 Native model files (.model) can be generated from TensorFlow model
8621 files (.pb) by using tools/python/convert.py
8623 The filter accepts the following options:
8627 Specify which filter to use. This option accepts the following values:
8631 Derain filter. To conduct derain filter, you need to use a derain model.
8634 Dehaze filter. To conduct dehaze filter, you need to use a dehaze model.
8636 Default value is @samp{derain}.
8639 Specify which DNN backend to use for model loading and execution. This option accepts
8640 the following values:
8644 Native implementation of DNN loading and execution.
8647 TensorFlow backend. To enable this backend you
8648 need to install the TensorFlow for C library (see
8649 @url{https://www.tensorflow.org/install/install_c}) and configure FFmpeg with
8650 @code{--enable-libtensorflow}
8652 Default value is @samp{native}.
8655 Set path to model file specifying network architecture and its parameters.
8656 Note that different backends use different file formats. TensorFlow and native
8657 backend can load files for only its format.
8662 Attempt to fix small changes in horizontal and/or vertical shift. This
8663 filter helps remove camera shake from hand-holding a camera, bumping a
8664 tripod, moving on a vehicle, etc.
8666 The filter accepts the following options:
8674 Specify a rectangular area where to limit the search for motion
8676 If desired the search for motion vectors can be limited to a
8677 rectangular area of the frame defined by its top left corner, width
8678 and height. These parameters have the same meaning as the drawbox
8679 filter which can be used to visualise the position of the bounding
8682 This is useful when simultaneous movement of subjects within the frame
8683 might be confused for camera motion by the motion vector search.
8685 If any or all of @var{x}, @var{y}, @var{w} and @var{h} are set to -1
8686 then the full frame is used. This allows later options to be set
8687 without specifying the bounding box for the motion vector search.
8689 Default - search the whole frame.
8693 Specify the maximum extent of movement in x and y directions in the
8694 range 0-64 pixels. Default 16.
8697 Specify how to generate pixels to fill blanks at the edge of the
8698 frame. Available values are:
8701 Fill zeroes at blank locations
8703 Original image at blank locations
8705 Extruded edge value at blank locations
8707 Mirrored edge at blank locations
8709 Default value is @samp{mirror}.
8712 Specify the blocksize to use for motion search. Range 4-128 pixels,
8716 Specify the contrast threshold for blocks. Only blocks with more than
8717 the specified contrast (difference between darkest and lightest
8718 pixels) will be considered. Range 1-255, default 125.
8721 Specify the search strategy. Available values are:
8724 Set exhaustive search
8726 Set less exhaustive search.
8728 Default value is @samp{exhaustive}.
8731 If set then a detailed log of the motion search is written to the
8738 Remove unwanted contamination of foreground colors, caused by reflected color of
8739 greenscreen or bluescreen.
8741 This filter accepts the following options:
8745 Set what type of despill to use.
8748 Set how spillmap will be generated.
8751 Set how much to get rid of still remaining spill.
8754 Controls amount of red in spill area.
8757 Controls amount of green in spill area.
8758 Should be -1 for greenscreen.
8761 Controls amount of blue in spill area.
8762 Should be -1 for bluescreen.
8765 Controls brightness of spill area, preserving colors.
8768 Modify alpha from generated spillmap.
8773 Apply an exact inverse of the telecine operation. It requires a predefined
8774 pattern specified using the pattern option which must be the same as that passed
8775 to the telecine filter.
8777 This filter accepts the following options:
8786 The default value is @code{top}.
8790 A string of numbers representing the pulldown pattern you wish to apply.
8791 The default value is @code{23}.
8794 A number representing position of the first frame with respect to the telecine
8795 pattern. This is to be used if the stream is cut. The default value is @code{0}.
8800 Apply dilation effect to the video.
8802 This filter replaces the pixel by the local(3x3) maximum.
8804 It accepts the following options:
8811 Limit the maximum change for each plane, default is 65535.
8812 If 0, plane will remain unchanged.
8815 Flag which specifies the pixel to refer to. Default is 255 i.e. all eight
8818 Flags to local 3x3 coordinates maps like this:
8827 Displace pixels as indicated by second and third input stream.
8829 It takes three input streams and outputs one stream, the first input is the
8830 source, and second and third input are displacement maps.
8832 The second input specifies how much to displace pixels along the
8833 x-axis, while the third input specifies how much to displace pixels
8835 If one of displacement map streams terminates, last frame from that
8836 displacement map will be used.
8838 Note that once generated, displacements maps can be reused over and over again.
8840 A description of the accepted options follows.
8844 Set displace behavior for pixels that are out of range.
8846 Available values are:
8849 Missing pixels are replaced by black pixels.
8852 Adjacent pixels will spread out to replace missing pixels.
8855 Out of range pixels are wrapped so they point to pixels of other side.
8858 Out of range pixels will be replaced with mirrored pixels.
8860 Default is @samp{smear}.
8864 @subsection Examples
8868 Add ripple effect to rgb input of video size hd720:
8870 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
8874 Add wave effect to rgb input of video size hd720:
8876 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
8882 Draw a colored box on the input image.
8884 It accepts the following parameters:
8889 The expressions which specify the top left corner coordinates of the box. It defaults to 0.
8893 The expressions which specify the width and height of the box; if 0 they are interpreted as
8894 the input width and height. It defaults to 0.
8897 Specify the color of the box to write. For the general syntax of this option,
8898 check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. If the special
8899 value @code{invert} is used, the box edge color is the same as the
8900 video with inverted luma.
8903 The expression which sets the thickness of the box edge.
8904 A value of @code{fill} will create a filled box. Default value is @code{3}.
8906 See below for the list of accepted constants.
8909 Applicable if the input has alpha. With value @code{1}, the pixels of the painted box
8910 will overwrite the video's color and alpha pixels.
8911 Default is @code{0}, which composites the box onto the input, leaving the video's alpha intact.
8914 The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
8915 following constants:
8919 The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
8923 horizontal and vertical chroma subsample values. For example for the
8924 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
8928 The input width and height.
8931 The input sample aspect ratio.
8935 The x and y offset coordinates where the box is drawn.
8939 The width and height of the drawn box.
8942 The thickness of the drawn box.
8944 These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
8945 each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
8949 @subsection Examples
8953 Draw a black box around the edge of the input image:
8959 Draw a box with color red and an opacity of 50%:
8961 drawbox=10:20:200:60:red@@0.5
8964 The previous example can be specified as:
8966 drawbox=x=10:y=20:w=200:h=60:color=red@@0.5
8970 Fill the box with pink color:
8972 drawbox=x=10:y=10:w=100:h=100:color=pink@@0.5:t=fill
8976 Draw a 2-pixel red 2.40:1 mask:
8978 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
8982 @subsection Commands
8983 This filter supports same commands as options.
8984 The command accepts the same syntax of the corresponding option.
8986 If the specified expression is not valid, it is kept at its current
8991 Draw a grid on the input image.
8993 It accepts the following parameters:
8998 The expressions which specify the coordinates of some point of grid intersection (meant to configure offset). Both default to 0.
9002 The expressions which specify the width and height of the grid cell, if 0 they are interpreted as the
9003 input width and height, respectively, minus @code{thickness}, so image gets
9004 framed. Default to 0.
9007 Specify the color of the grid. For the general syntax of this option,
9008 check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. If the special
9009 value @code{invert} is used, the grid color is the same as the
9010 video with inverted luma.
9013 The expression which sets the thickness of the grid line. Default value is @code{1}.
9015 See below for the list of accepted constants.
9018 Applicable if the input has alpha. With @code{1} the pixels of the painted grid
9019 will overwrite the video's color and alpha pixels.
9020 Default is @code{0}, which composites the grid onto the input, leaving the video's alpha intact.
9023 The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
9024 following constants:
9028 The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
9032 horizontal and vertical chroma subsample values. For example for the
9033 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
9037 The input grid cell width and height.
9040 The input sample aspect ratio.
9044 The x and y coordinates of some point of grid intersection (meant to configure offset).
9048 The width and height of the drawn cell.
9051 The thickness of the drawn cell.
9053 These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
9054 each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
9058 @subsection Examples
9062 Draw a grid with cell 100x100 pixels, thickness 2 pixels, with color red and an opacity of 50%:
9064 drawgrid=width=100:height=100:thickness=2:color=red@@0.5
9068 Draw a white 3x3 grid with an opacity of 50%:
9070 drawgrid=w=iw/3:h=ih/3:t=2:c=white@@0.5
9074 @subsection Commands
9075 This filter supports same commands as options.
9076 The command accepts the same syntax of the corresponding option.
9078 If the specified expression is not valid, it is kept at its current
9084 Draw a text string or text from a specified file on top of a video, using the
9085 libfreetype library.
9087 To enable compilation of this filter, you need to configure FFmpeg with
9088 @code{--enable-libfreetype}.
9089 To enable default font fallback and the @var{font} option you need to
9090 configure FFmpeg with @code{--enable-libfontconfig}.
9091 To enable the @var{text_shaping} option, you need to configure FFmpeg with
9092 @code{--enable-libfribidi}.
9096 It accepts the following parameters:
9101 Used to draw a box around text using the background color.
9102 The value must be either 1 (enable) or 0 (disable).
9103 The default value of @var{box} is 0.
9106 Set the width of the border to be drawn around the box using @var{boxcolor}.
9107 The default value of @var{boxborderw} is 0.
9110 The color to be used for drawing box around text. For the syntax of this
9111 option, check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
9113 The default value of @var{boxcolor} is "white".
9116 Set the line spacing in pixels of the border to be drawn around the box using @var{box}.
9117 The default value of @var{line_spacing} is 0.
9120 Set the width of the border to be drawn around the text using @var{bordercolor}.
9121 The default value of @var{borderw} is 0.
9124 Set the color to be used for drawing border around text. For the syntax of this
9125 option, check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
9127 The default value of @var{bordercolor} is "black".
9130 Select how the @var{text} is expanded. Can be either @code{none},
9131 @code{strftime} (deprecated) or
9132 @code{normal} (default). See the @ref{drawtext_expansion, Text expansion} section
9136 Set a start time for the count. Value is in microseconds. Only applied
9137 in the deprecated strftime expansion mode. To emulate in normal expansion
9138 mode use the @code{pts} function, supplying the start time (in seconds)
9139 as the second argument.
9142 If true, check and fix text coords to avoid clipping.
9145 The color to be used for drawing fonts. For the syntax of this option, check
9146 the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
9148 The default value of @var{fontcolor} is "black".
9150 @item fontcolor_expr
9151 String which is expanded the same way as @var{text} to obtain dynamic
9152 @var{fontcolor} value. By default this option has empty value and is not
9153 processed. When this option is set, it overrides @var{fontcolor} option.
9156 The font family to be used for drawing text. By default Sans.
9159 The font file to be used for drawing text. The path must be included.
9160 This parameter is mandatory if the fontconfig support is disabled.
9163 Draw the text applying alpha blending. The value can
9164 be a number between 0.0 and 1.0.
9165 The expression accepts the same variables @var{x, y} as well.
9166 The default value is 1.
9167 Please see @var{fontcolor_expr}.
9170 The font size to be used for drawing text.
9171 The default value of @var{fontsize} is 16.
9174 If set to 1, attempt to shape the text (for example, reverse the order of
9175 right-to-left text and join Arabic characters) before drawing it.
9176 Otherwise, just draw the text exactly as given.
9177 By default 1 (if supported).
9180 The flags to be used for loading the fonts.
9182 The flags map the corresponding flags supported by libfreetype, and are
9183 a combination of the following values:
9190 @item vertical_layout
9191 @item force_autohint
9194 @item ignore_global_advance_width
9196 @item ignore_transform
9202 Default value is "default".
9204 For more information consult the documentation for the FT_LOAD_*
9208 The color to be used for drawing a shadow behind the drawn text. For the
9209 syntax of this option, check the @ref{color syntax,,"Color" section in the
9210 ffmpeg-utils manual,ffmpeg-utils}.
9212 The default value of @var{shadowcolor} is "black".
9216 The x and y offsets for the text shadow position with respect to the
9217 position of the text. They can be either positive or negative
9218 values. The default value for both is "0".
9221 The starting frame number for the n/frame_num variable. The default value
9225 The size in number of spaces to use for rendering the tab.
9229 Set the initial timecode representation in "hh:mm:ss[:;.]ff"
9230 format. It can be used with or without text parameter. @var{timecode_rate}
9231 option must be specified.
9233 @item timecode_rate, rate, r
9234 Set the timecode frame rate (timecode only). Value will be rounded to nearest
9235 integer. Minimum value is "1".
9236 Drop-frame timecode is supported for frame rates 30 & 60.
9239 If set to 1, the output of the timecode option will wrap around at 24 hours.
9240 Default is 0 (disabled).
9243 The text string to be drawn. The text must be a sequence of UTF-8
9245 This parameter is mandatory if no file is specified with the parameter
9249 A text file containing text to be drawn. The text must be a sequence
9250 of UTF-8 encoded characters.
9252 This parameter is mandatory if no text string is specified with the
9253 parameter @var{text}.
9255 If both @var{text} and @var{textfile} are specified, an error is thrown.
9258 If set to 1, the @var{textfile} will be reloaded before each frame.
9259 Be sure to update it atomically, or it may be read partially, or even fail.
9263 The expressions which specify the offsets where text will be drawn
9264 within the video frame. They are relative to the top/left border of the
9267 The default value of @var{x} and @var{y} is "0".
9269 See below for the list of accepted constants and functions.
9272 The parameters for @var{x} and @var{y} are expressions containing the
9273 following constants and functions:
9277 input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
9281 horizontal and vertical chroma subsample values. For example for the
9282 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
9285 the height of each text line
9293 @item max_glyph_a, ascent
9294 the maximum distance from the baseline to the highest/upper grid
9295 coordinate used to place a glyph outline point, for all the rendered
9297 It is a positive value, due to the grid's orientation with the Y axis
9300 @item max_glyph_d, descent
9301 the maximum distance from the baseline to the lowest grid coordinate
9302 used to place a glyph outline point, for all the rendered glyphs.
9303 This is a negative value, due to the grid's orientation, with the Y axis
9307 maximum glyph height, that is the maximum height for all the glyphs
9308 contained in the rendered text, it is equivalent to @var{ascent} -
9312 maximum glyph width, that is the maximum width for all the glyphs
9313 contained in the rendered text
9316 the number of input frame, starting from 0
9318 @item rand(min, max)
9319 return a random number included between @var{min} and @var{max}
9322 The input sample aspect ratio.
9325 timestamp expressed in seconds, NAN if the input timestamp is unknown
9328 the height of the rendered text
9331 the width of the rendered text
9335 the x and y offset coordinates where the text is drawn.
9337 These parameters allow the @var{x} and @var{y} expressions to refer
9338 to each other, so you can for example specify @code{y=x/dar}.
9341 A one character description of the current frame's picture type.
9344 The current packet's position in the input file or stream
9345 (in bytes, from the start of the input). A value of -1 indicates
9346 this info is not available.
9349 The current packet's duration, in seconds.
9352 The current packet's size (in bytes).
9355 @anchor{drawtext_expansion}
9356 @subsection Text expansion
9358 If @option{expansion} is set to @code{strftime},
9359 the filter recognizes strftime() sequences in the provided text and
9360 expands them accordingly. Check the documentation of strftime(). This
9361 feature is deprecated.
9363 If @option{expansion} is set to @code{none}, the text is printed verbatim.
9365 If @option{expansion} is set to @code{normal} (which is the default),
9366 the following expansion mechanism is used.
9368 The backslash character @samp{\}, followed by any character, always expands to
9369 the second character.
9371 Sequences of the form @code{%@{...@}} are expanded. The text between the
9372 braces is a function name, possibly followed by arguments separated by ':'.
9373 If the arguments contain special characters or delimiters (':' or '@}'),
9374 they should be escaped.
9376 Note that they probably must also be escaped as the value for the
9377 @option{text} option in the filter argument string and as the filter
9378 argument in the filtergraph description, and possibly also for the shell,
9379 that makes up to four levels of escaping; using a text file avoids these
9382 The following functions are available:
9387 The expression evaluation result.
9389 It must take one argument specifying the expression to be evaluated,
9390 which accepts the same constants and functions as the @var{x} and
9391 @var{y} values. Note that not all constants should be used, for
9392 example the text size is not known when evaluating the expression, so
9393 the constants @var{text_w} and @var{text_h} will have an undefined
9396 @item expr_int_format, eif
9397 Evaluate the expression's value and output as formatted integer.
9399 The first argument is the expression to be evaluated, just as for the @var{expr} function.
9400 The second argument specifies the output format. Allowed values are @samp{x},
9401 @samp{X}, @samp{d} and @samp{u}. They are treated exactly as in the
9402 @code{printf} function.
9403 The third parameter is optional and sets the number of positions taken by the output.
9404 It can be used to add padding with zeros from the left.
9407 The time at which the filter is running, expressed in UTC.
9408 It can accept an argument: a strftime() format string.
9411 The time at which the filter is running, expressed in the local time zone.
9412 It can accept an argument: a strftime() format string.
9415 Frame metadata. Takes one or two arguments.
9417 The first argument is mandatory and specifies the metadata key.
9419 The second argument is optional and specifies a default value, used when the
9420 metadata key is not found or empty.
9422 Available metadata can be identified by inspecting entries
9423 starting with TAG included within each frame section
9424 printed by running @code{ffprobe -show_frames}.
9426 String metadata generated in filters leading to
9427 the drawtext filter are also available.
9430 The frame number, starting from 0.
9433 A one character description of the current picture type.
9436 The timestamp of the current frame.
9437 It can take up to three arguments.
9439 The first argument is the format of the timestamp; it defaults to @code{flt}
9440 for seconds as a decimal number with microsecond accuracy; @code{hms} stands
9441 for a formatted @var{[-]HH:MM:SS.mmm} timestamp with millisecond accuracy.
9442 @code{gmtime} stands for the timestamp of the frame formatted as UTC time;
9443 @code{localtime} stands for the timestamp of the frame formatted as
9444 local time zone time.
9446 The second argument is an offset added to the timestamp.
9448 If the format is set to @code{hms}, a third argument @code{24HH} may be
9449 supplied to present the hour part of the formatted timestamp in 24h format
9452 If the format is set to @code{localtime} or @code{gmtime},
9453 a third argument may be supplied: a strftime() format string.
9454 By default, @var{YYYY-MM-DD HH:MM:SS} format will be used.
9457 @subsection Commands
9459 This filter supports altering parameters via commands:
9462 Alter existing filter parameters.
9464 Syntax for the argument is the same as for filter invocation, e.g.
9467 fontsize=56:fontcolor=green:text='Hello World'
9470 Full filter invocation with sendcmd would look like this:
9473 sendcmd=c='56.0 drawtext reinit fontsize=56\:fontcolor=green\:text=Hello\\ World'
9477 If the entire argument can't be parsed or applied as valid values then the filter will
9478 continue with its existing parameters.
9480 @subsection Examples
9484 Draw "Test Text" with font FreeSerif, using the default values for the
9485 optional parameters.
9488 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"
9492 Draw 'Test Text' with font FreeSerif of size 24 at position x=100
9493 and y=50 (counting from the top-left corner of the screen), text is
9494 yellow with a red box around it. Both the text and the box have an
9498 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
9499 x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2"
9502 Note that the double quotes are not necessary if spaces are not used
9503 within the parameter list.
9506 Show the text at the center of the video frame:
9508 drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h)/2"
9512 Show the text at a random position, switching to a new position every 30 seconds:
9514 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)"
9518 Show a text line sliding from right to left in the last row of the video
9519 frame. The file @file{LONG_LINE} is assumed to contain a single line
9522 drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t"
9526 Show the content of file @file{CREDITS} off the bottom of the frame and scroll up.
9528 drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t"
9532 Draw a single green letter "g", at the center of the input video.
9533 The glyph baseline is placed at half screen height.
9535 drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent"
9539 Show text for 1 second every 3 seconds:
9541 drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:enable=lt(mod(t\,3)\,1):text='blink'"
9545 Use fontconfig to set the font. Note that the colons need to be escaped.
9547 drawtext='fontfile=Linux Libertine O-40\:style=Semibold:text=FFmpeg'
9551 Print the date of a real-time encoding (see strftime(3)):
9553 drawtext='fontfile=FreeSans.ttf:text=%@{localtime\:%a %b %d %Y@}'
9557 Show text fading in and out (appearing/disappearing):
9560 DS=1.0 # display start
9561 DE=10.0 # display end
9562 FID=1.5 # fade in duration
9563 FOD=5 # fade out duration
9564 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 @}"
9568 Horizontally align multiple separate texts. Note that @option{max_glyph_a}
9569 and the @option{fontsize} value are included in the @option{y} offset.
9571 drawtext=fontfile=FreeSans.ttf:text=DOG:fontsize=24:x=10:y=20+24-max_glyph_a,
9572 drawtext=fontfile=FreeSans.ttf:text=cow:fontsize=24:x=80:y=20+24-max_glyph_a
9577 For more information about libfreetype, check:
9578 @url{http://www.freetype.org/}.
9580 For more information about fontconfig, check:
9581 @url{http://freedesktop.org/software/fontconfig/fontconfig-user.html}.
9583 For more information about libfribidi, check:
9584 @url{http://fribidi.org/}.
9588 Detect and draw edges. The filter uses the Canny Edge Detection algorithm.
9590 The filter accepts the following options:
9595 Set low and high threshold values used by the Canny thresholding
9598 The high threshold selects the "strong" edge pixels, which are then
9599 connected through 8-connectivity with the "weak" edge pixels selected
9600 by the low threshold.
9602 @var{low} and @var{high} threshold values must be chosen in the range
9603 [0,1], and @var{low} should be lesser or equal to @var{high}.
9605 Default value for @var{low} is @code{20/255}, and default value for @var{high}
9609 Define the drawing mode.
9613 Draw white/gray wires on black background.
9616 Mix the colors to create a paint/cartoon effect.
9619 Apply Canny edge detector on all selected planes.
9621 Default value is @var{wires}.
9624 Select planes for filtering. By default all available planes are filtered.
9627 @subsection Examples
9631 Standard edge detection with custom values for the hysteresis thresholding:
9633 edgedetect=low=0.1:high=0.4
9637 Painting effect without thresholding:
9639 edgedetect=mode=colormix:high=0
9645 Apply a posterize effect using the ELBG (Enhanced LBG) algorithm.
9647 For each input image, the filter will compute the optimal mapping from
9648 the input to the output given the codebook length, that is the number
9649 of distinct output colors.
9651 This filter accepts the following options.
9654 @item codebook_length, l
9655 Set codebook length. The value must be a positive integer, and
9656 represents the number of distinct output colors. Default value is 256.
9659 Set the maximum number of iterations to apply for computing the optimal
9660 mapping. The higher the value the better the result and the higher the
9661 computation time. Default value is 1.
9664 Set a random seed, must be an integer included between 0 and
9665 UINT32_MAX. If not specified, or if explicitly set to -1, the filter
9666 will try to use a good random seed on a best effort basis.
9669 Set pal8 output pixel format. This option does not work with codebook
9670 length greater than 256.
9675 Measure graylevel entropy in histogram of color channels of video frames.
9677 It accepts the following parameters:
9681 Can be either @var{normal} or @var{diff}. Default is @var{normal}.
9683 @var{diff} mode measures entropy of histogram delta values, absolute differences
9684 between neighbour histogram values.
9688 Set brightness, contrast, saturation and approximate gamma adjustment.
9690 The filter accepts the following options:
9694 Set the contrast expression. The value must be a float value in range
9695 @code{-1000.0} to @code{1000.0}. The default value is "1".
9698 Set the brightness expression. The value must be a float value in
9699 range @code{-1.0} to @code{1.0}. The default value is "0".
9702 Set the saturation expression. The value must be a float in
9703 range @code{0.0} to @code{3.0}. The default value is "1".
9706 Set the gamma expression. The value must be a float in range
9707 @code{0.1} to @code{10.0}. The default value is "1".
9710 Set the gamma expression for red. The value must be a float in
9711 range @code{0.1} to @code{10.0}. The default value is "1".
9714 Set the gamma expression for green. The value must be a float in range
9715 @code{0.1} to @code{10.0}. The default value is "1".
9718 Set the gamma expression for blue. The value must be a float in range
9719 @code{0.1} to @code{10.0}. The default value is "1".
9722 Set the gamma weight expression. It can be used to reduce the effect
9723 of a high gamma value on bright image areas, e.g. keep them from
9724 getting overamplified and just plain white. The value must be a float
9725 in range @code{0.0} to @code{1.0}. A value of @code{0.0} turns the
9726 gamma correction all the way down while @code{1.0} leaves it at its
9727 full strength. Default is "1".
9730 Set when the expressions for brightness, contrast, saturation and
9731 gamma expressions are evaluated.
9733 It accepts the following values:
9736 only evaluate expressions once during the filter initialization or
9737 when a command is processed
9740 evaluate expressions for each incoming frame
9743 Default value is @samp{init}.
9746 The expressions accept the following parameters:
9749 frame count of the input frame starting from 0
9752 byte position of the corresponding packet in the input file, NAN if
9756 frame rate of the input video, NAN if the input frame rate is unknown
9759 timestamp expressed in seconds, NAN if the input timestamp is unknown
9762 @subsection Commands
9763 The filter supports the following commands:
9767 Set the contrast expression.
9770 Set the brightness expression.
9773 Set the saturation expression.
9776 Set the gamma expression.
9779 Set the gamma_r expression.
9782 Set gamma_g expression.
9785 Set gamma_b expression.
9788 Set gamma_weight expression.
9790 The command accepts the same syntax of the corresponding option.
9792 If the specified expression is not valid, it is kept at its current
9799 Apply erosion effect to the video.
9801 This filter replaces the pixel by the local(3x3) minimum.
9803 It accepts the following options:
9810 Limit the maximum change for each plane, default is 65535.
9811 If 0, plane will remain unchanged.
9814 Flag which specifies the pixel to refer to. Default is 255 i.e. all eight
9817 Flags to local 3x3 coordinates maps like this:
9824 @section extractplanes
9826 Extract color channel components from input video stream into
9827 separate grayscale video streams.
9829 The filter accepts the following option:
9833 Set plane(s) to extract.
9835 Available values for planes are:
9846 Choosing planes not available in the input will result in an error.
9847 That means you cannot select @code{r}, @code{g}, @code{b} planes
9848 with @code{y}, @code{u}, @code{v} planes at same time.
9851 @subsection Examples
9855 Extract luma, u and v color channel component from input video frame
9856 into 3 grayscale outputs:
9858 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
9864 Apply a fade-in/out effect to the input video.
9866 It accepts the following parameters:
9870 The effect type can be either "in" for a fade-in, or "out" for a fade-out
9872 Default is @code{in}.
9874 @item start_frame, s
9875 Specify the number of the frame to start applying the fade
9876 effect at. Default is 0.
9879 The number of frames that the fade effect lasts. At the end of the
9880 fade-in effect, the output video will have the same intensity as the input video.
9881 At the end of the fade-out transition, the output video will be filled with the
9882 selected @option{color}.
9886 If set to 1, fade only alpha channel, if one exists on the input.
9889 @item start_time, st
9890 Specify the timestamp (in seconds) of the frame to start to apply the fade
9891 effect. If both start_frame and start_time are specified, the fade will start at
9892 whichever comes last. Default is 0.
9895 The number of seconds for which the fade effect has to last. At the end of the
9896 fade-in effect the output video will have the same intensity as the input video,
9897 at the end of the fade-out transition the output video will be filled with the
9898 selected @option{color}.
9899 If both duration and nb_frames are specified, duration is used. Default is 0
9900 (nb_frames is used by default).
9903 Specify the color of the fade. Default is "black".
9906 @subsection Examples
9910 Fade in the first 30 frames of video:
9915 The command above is equivalent to:
9921 Fade out the last 45 frames of a 200-frame video:
9924 fade=type=out:start_frame=155:nb_frames=45
9928 Fade in the first 25 frames and fade out the last 25 frames of a 1000-frame video:
9930 fade=in:0:25, fade=out:975:25
9934 Make the first 5 frames yellow, then fade in from frame 5-24:
9936 fade=in:5:20:color=yellow
9940 Fade in alpha over first 25 frames of video:
9942 fade=in:0:25:alpha=1
9946 Make the first 5.5 seconds black, then fade in for 0.5 seconds:
9948 fade=t=in:st=5.5:d=0.5
9954 Denoise frames using 3D FFT (frequency domain filtering).
9956 The filter accepts the following options:
9960 Set the noise sigma constant. This sets denoising strength.
9961 Default value is 1. Allowed range is from 0 to 30.
9962 Using very high sigma with low overlap may give blocking artifacts.
9965 Set amount of denoising. By default all detected noise is reduced.
9966 Default value is 1. Allowed range is from 0 to 1.
9969 Set size of block, Default is 4, can be 3, 4, 5 or 6.
9970 Actual size of block in pixels is 2 to power of @var{block}, so by default
9971 block size in pixels is 2^4 which is 16.
9974 Set block overlap. Default is 0.5. Allowed range is from 0.2 to 0.8.
9977 Set number of previous frames to use for denoising. By default is set to 0.
9980 Set number of next frames to to use for denoising. By default is set to 0.
9983 Set planes which will be filtered, by default are all available filtered
9988 Apply arbitrary expressions to samples in frequency domain
9992 Adjust the dc value (gain) of the luma plane of the image. The filter
9993 accepts an integer value in range @code{0} to @code{1000}. The default
9994 value is set to @code{0}.
9997 Adjust the dc value (gain) of the 1st chroma plane of the image. The
9998 filter accepts an integer value in range @code{0} to @code{1000}. The
9999 default value is set to @code{0}.
10002 Adjust the dc value (gain) of the 2nd chroma plane of the image. The
10003 filter accepts an integer value in range @code{0} to @code{1000}. The
10004 default value is set to @code{0}.
10007 Set the frequency domain weight expression for the luma plane.
10010 Set the frequency domain weight expression for the 1st chroma plane.
10013 Set the frequency domain weight expression for the 2nd chroma plane.
10016 Set when the expressions are evaluated.
10018 It accepts the following values:
10021 Only evaluate expressions once during the filter initialization.
10024 Evaluate expressions for each incoming frame.
10027 Default value is @samp{init}.
10029 The filter accepts the following variables:
10032 The coordinates of the current sample.
10036 The width and height of the image.
10039 The number of input frame, starting from 0.
10042 @subsection Examples
10048 fftfilt=dc_Y=128:weight_Y='squish(1-(Y+X)/100)'
10054 fftfilt=dc_Y=0:weight_Y='squish((Y+X)/100-1)'
10060 fftfilt=dc_Y=0:weight_Y='1+squish(1-(Y+X)/100)'
10066 fftfilt=dc_Y=0:weight_Y='exp(-4 * ((Y+X)/(W+H)))'
10073 Extract a single field from an interlaced image using stride
10074 arithmetic to avoid wasting CPU time. The output frames are marked as
10077 The filter accepts the following options:
10081 Specify whether to extract the top (if the value is @code{0} or
10082 @code{top}) or the bottom field (if the value is @code{1} or
10088 Create new frames by copying the top and bottom fields from surrounding frames
10089 supplied as numbers by the hint file.
10093 Set file containing hints: absolute/relative frame numbers.
10095 There must be one line for each frame in a clip. Each line must contain two
10096 numbers separated by the comma, optionally followed by @code{-} or @code{+}.
10097 Numbers supplied on each line of file can not be out of [N-1,N+1] where N
10098 is current frame number for @code{absolute} mode or out of [-1, 1] range
10099 for @code{relative} mode. First number tells from which frame to pick up top
10100 field and second number tells from which frame to pick up bottom field.
10102 If optionally followed by @code{+} output frame will be marked as interlaced,
10103 else if followed by @code{-} output frame will be marked as progressive, else
10104 it will be marked same as input frame.
10105 If line starts with @code{#} or @code{;} that line is skipped.
10108 Can be item @code{absolute} or @code{relative}. Default is @code{absolute}.
10111 Example of first several lines of @code{hint} file for @code{relative} mode:
10113 0,0 - # first frame
10114 1,0 - # second frame, use third's frame top field and second's frame bottom field
10115 1,0 - # third frame, use fourth's frame top field and third's frame bottom field
10130 @section fieldmatch
10132 Field matching filter for inverse telecine. It is meant to reconstruct the
10133 progressive frames from a telecined stream. The filter does not drop duplicated
10134 frames, so to achieve a complete inverse telecine @code{fieldmatch} needs to be
10135 followed by a decimation filter such as @ref{decimate} in the filtergraph.
10137 The separation of the field matching and the decimation is notably motivated by
10138 the possibility of inserting a de-interlacing filter fallback between the two.
10139 If the source has mixed telecined and real interlaced content,
10140 @code{fieldmatch} will not be able to match fields for the interlaced parts.
10141 But these remaining combed frames will be marked as interlaced, and thus can be
10142 de-interlaced by a later filter such as @ref{yadif} before decimation.
10144 In addition to the various configuration options, @code{fieldmatch} can take an
10145 optional second stream, activated through the @option{ppsrc} option. If
10146 enabled, the frames reconstruction will be based on the fields and frames from
10147 this second stream. This allows the first input to be pre-processed in order to
10148 help the various algorithms of the filter, while keeping the output lossless
10149 (assuming the fields are matched properly). Typically, a field-aware denoiser,
10150 or brightness/contrast adjustments can help.
10152 Note that this filter uses the same algorithms as TIVTC/TFM (AviSynth project)
10153 and VIVTC/VFM (VapourSynth project). The later is a light clone of TFM from
10154 which @code{fieldmatch} is based on. While the semantic and usage are very
10155 close, some behaviour and options names can differ.
10157 The @ref{decimate} filter currently only works for constant frame rate input.
10158 If your input has mixed telecined (30fps) and progressive content with a lower
10159 framerate like 24fps use the following filterchain to produce the necessary cfr
10160 stream: @code{dejudder,fps=30000/1001,fieldmatch,decimate}.
10162 The filter accepts the following options:
10166 Specify the assumed field order of the input stream. Available values are:
10170 Auto detect parity (use FFmpeg's internal parity value).
10172 Assume bottom field first.
10174 Assume top field first.
10177 Note that it is sometimes recommended not to trust the parity announced by the
10180 Default value is @var{auto}.
10183 Set the matching mode or strategy to use. @option{pc} mode is the safest in the
10184 sense that it won't risk creating jerkiness due to duplicate frames when
10185 possible, but if there are bad edits or blended fields it will end up
10186 outputting combed frames when a good match might actually exist. On the other
10187 hand, @option{pcn_ub} mode is the most risky in terms of creating jerkiness,
10188 but will almost always find a good frame if there is one. The other values are
10189 all somewhere in between @option{pc} and @option{pcn_ub} in terms of risking
10190 jerkiness and creating duplicate frames versus finding good matches in sections
10191 with bad edits, orphaned fields, blended fields, etc.
10193 More details about p/c/n/u/b are available in @ref{p/c/n/u/b meaning} section.
10195 Available values are:
10199 2-way matching (p/c)
10201 2-way matching, and trying 3rd match if still combed (p/c + n)
10203 2-way matching, and trying 3rd match (same order) if still combed (p/c + u)
10205 2-way matching, trying 3rd match if still combed, and trying 4th/5th matches if
10206 still combed (p/c + n + u/b)
10208 3-way matching (p/c/n)
10210 3-way matching, and trying 4th/5th matches if all 3 of the original matches are
10211 detected as combed (p/c/n + u/b)
10214 The parenthesis at the end indicate the matches that would be used for that
10215 mode assuming @option{order}=@var{tff} (and @option{field} on @var{auto} or
10218 In terms of speed @option{pc} mode is by far the fastest and @option{pcn_ub} is
10221 Default value is @var{pc_n}.
10224 Mark the main input stream as a pre-processed input, and enable the secondary
10225 input stream as the clean source to pick the fields from. See the filter
10226 introduction for more details. It is similar to the @option{clip2} feature from
10229 Default value is @code{0} (disabled).
10232 Set the field to match from. It is recommended to set this to the same value as
10233 @option{order} unless you experience matching failures with that setting. In
10234 certain circumstances changing the field that is used to match from can have a
10235 large impact on matching performance. Available values are:
10239 Automatic (same value as @option{order}).
10241 Match from the bottom field.
10243 Match from the top field.
10246 Default value is @var{auto}.
10249 Set whether or not chroma is included during the match comparisons. In most
10250 cases it is recommended to leave this enabled. You should set this to @code{0}
10251 only if your clip has bad chroma problems such as heavy rainbowing or other
10252 artifacts. Setting this to @code{0} could also be used to speed things up at
10253 the cost of some accuracy.
10255 Default value is @code{1}.
10259 These define an exclusion band which excludes the lines between @option{y0} and
10260 @option{y1} from being included in the field matching decision. An exclusion
10261 band can be used to ignore subtitles, a logo, or other things that may
10262 interfere with the matching. @option{y0} sets the starting scan line and
10263 @option{y1} sets the ending line; all lines in between @option{y0} and
10264 @option{y1} (including @option{y0} and @option{y1}) will be ignored. Setting
10265 @option{y0} and @option{y1} to the same value will disable the feature.
10266 @option{y0} and @option{y1} defaults to @code{0}.
10269 Set the scene change detection threshold as a percentage of maximum change on
10270 the luma plane. Good values are in the @code{[8.0, 14.0]} range. Scene change
10271 detection is only relevant in case @option{combmatch}=@var{sc}. The range for
10272 @option{scthresh} is @code{[0.0, 100.0]}.
10274 Default value is @code{12.0}.
10277 When @option{combatch} is not @var{none}, @code{fieldmatch} will take into
10278 account the combed scores of matches when deciding what match to use as the
10279 final match. Available values are:
10283 No final matching based on combed scores.
10285 Combed scores are only used when a scene change is detected.
10287 Use combed scores all the time.
10290 Default is @var{sc}.
10293 Force @code{fieldmatch} to calculate the combed metrics for certain matches and
10294 print them. This setting is known as @option{micout} in TFM/VFM vocabulary.
10295 Available values are:
10299 No forced calculation.
10301 Force p/c/n calculations.
10303 Force p/c/n/u/b calculations.
10306 Default value is @var{none}.
10309 This is the area combing threshold used for combed frame detection. This
10310 essentially controls how "strong" or "visible" combing must be to be detected.
10311 Larger values mean combing must be more visible and smaller values mean combing
10312 can be less visible or strong and still be detected. Valid settings are from
10313 @code{-1} (every pixel will be detected as combed) to @code{255} (no pixel will
10314 be detected as combed). This is basically a pixel difference value. A good
10315 range is @code{[8, 12]}.
10317 Default value is @code{9}.
10320 Sets whether or not chroma is considered in the combed frame decision. Only
10321 disable this if your source has chroma problems (rainbowing, etc.) that are
10322 causing problems for the combed frame detection with chroma enabled. Actually,
10323 using @option{chroma}=@var{0} is usually more reliable, except for the case
10324 where there is chroma only combing in the source.
10326 Default value is @code{0}.
10330 Respectively set the x-axis and y-axis size of the window used during combed
10331 frame detection. This has to do with the size of the area in which
10332 @option{combpel} pixels are required to be detected as combed for a frame to be
10333 declared combed. See the @option{combpel} parameter description for more info.
10334 Possible values are any number that is a power of 2 starting at 4 and going up
10337 Default value is @code{16}.
10340 The number of combed pixels inside any of the @option{blocky} by
10341 @option{blockx} size blocks on the frame for the frame to be detected as
10342 combed. While @option{cthresh} controls how "visible" the combing must be, this
10343 setting controls "how much" combing there must be in any localized area (a
10344 window defined by the @option{blockx} and @option{blocky} settings) on the
10345 frame. Minimum value is @code{0} and maximum is @code{blocky x blockx} (at
10346 which point no frames will ever be detected as combed). This setting is known
10347 as @option{MI} in TFM/VFM vocabulary.
10349 Default value is @code{80}.
10352 @anchor{p/c/n/u/b meaning}
10353 @subsection p/c/n/u/b meaning
10355 @subsubsection p/c/n
10357 We assume the following telecined stream:
10360 Top fields: 1 2 2 3 4
10361 Bottom fields: 1 2 3 4 4
10364 The numbers correspond to the progressive frame the fields relate to. Here, the
10365 first two frames are progressive, the 3rd and 4th are combed, and so on.
10367 When @code{fieldmatch} is configured to run a matching from bottom
10368 (@option{field}=@var{bottom}) this is how this input stream get transformed:
10373 B 1 2 3 4 4 <-- matching reference
10382 As a result of the field matching, we can see that some frames get duplicated.
10383 To perform a complete inverse telecine, you need to rely on a decimation filter
10384 after this operation. See for instance the @ref{decimate} filter.
10386 The same operation now matching from top fields (@option{field}=@var{top})
10391 T 1 2 2 3 4 <-- matching reference
10401 In these examples, we can see what @var{p}, @var{c} and @var{n} mean;
10402 basically, they refer to the frame and field of the opposite parity:
10405 @item @var{p} matches the field of the opposite parity in the previous frame
10406 @item @var{c} matches the field of the opposite parity in the current frame
10407 @item @var{n} matches the field of the opposite parity in the next frame
10412 The @var{u} and @var{b} matching are a bit special in the sense that they match
10413 from the opposite parity flag. In the following examples, we assume that we are
10414 currently matching the 2nd frame (Top:2, bottom:2). According to the match, a
10415 'x' is placed above and below each matched fields.
10417 With bottom matching (@option{field}=@var{bottom}):
10422 Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2
10423 Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3
10431 With top matching (@option{field}=@var{top}):
10436 Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2
10437 Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3
10445 @subsection Examples
10447 Simple IVTC of a top field first telecined stream:
10449 fieldmatch=order=tff:combmatch=none, decimate
10452 Advanced IVTC, with fallback on @ref{yadif} for still combed frames:
10454 fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate
10457 @section fieldorder
10459 Transform the field order of the input video.
10461 It accepts the following parameters:
10466 The output field order. Valid values are @var{tff} for top field first or @var{bff}
10467 for bottom field first.
10470 The default value is @samp{tff}.
10472 The transformation is done by shifting the picture content up or down
10473 by one line, and filling the remaining line with appropriate picture content.
10474 This method is consistent with most broadcast field order converters.
10476 If the input video is not flagged as being interlaced, or it is already
10477 flagged as being of the required output field order, then this filter does
10478 not alter the incoming video.
10480 It is very useful when converting to or from PAL DV material,
10481 which is bottom field first.
10485 ffmpeg -i in.vob -vf "fieldorder=bff" out.dv
10488 @section fifo, afifo
10490 Buffer input images and send them when they are requested.
10492 It is mainly useful when auto-inserted by the libavfilter
10495 It does not take parameters.
10497 @section fillborders
10499 Fill borders of the input video, without changing video stream dimensions.
10500 Sometimes video can have garbage at the four edges and you may not want to
10501 crop video input to keep size multiple of some number.
10503 This filter accepts the following options:
10507 Number of pixels to fill from left border.
10510 Number of pixels to fill from right border.
10513 Number of pixels to fill from top border.
10516 Number of pixels to fill from bottom border.
10521 It accepts the following values:
10524 fill pixels using outermost pixels
10527 fill pixels using mirroring
10530 fill pixels with constant value
10533 Default is @var{smear}.
10536 Set color for pixels in fixed mode. Default is @var{black}.
10541 Find a rectangular object
10543 It accepts the following options:
10547 Filepath of the object image, needs to be in gray8.
10550 Detection threshold, default is 0.5.
10553 Number of mipmaps, default is 3.
10555 @item xmin, ymin, xmax, ymax
10556 Specifies the rectangle in which to search.
10559 @subsection Examples
10563 Cover a rectangular object by the supplied image of a given video using @command{ffmpeg}:
10565 ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
10571 Flood area with values of same pixel components with another values.
10573 It accepts the following options:
10576 Set pixel x coordinate.
10579 Set pixel y coordinate.
10582 Set source #0 component value.
10585 Set source #1 component value.
10588 Set source #2 component value.
10591 Set source #3 component value.
10594 Set destination #0 component value.
10597 Set destination #1 component value.
10600 Set destination #2 component value.
10603 Set destination #3 component value.
10609 Convert the input video to one of the specified pixel formats.
10610 Libavfilter will try to pick one that is suitable as input to
10613 It accepts the following parameters:
10617 A '|'-separated list of pixel format names, such as
10618 "pix_fmts=yuv420p|monow|rgb24".
10622 @subsection Examples
10626 Convert the input video to the @var{yuv420p} format
10628 format=pix_fmts=yuv420p
10631 Convert the input video to any of the formats in the list
10633 format=pix_fmts=yuv420p|yuv444p|yuv410p
10640 Convert the video to specified constant frame rate by duplicating or dropping
10641 frames as necessary.
10643 It accepts the following parameters:
10647 The desired output frame rate. The default is @code{25}.
10650 Assume the first PTS should be the given value, in seconds. This allows for
10651 padding/trimming at the start of stream. By default, no assumption is made
10652 about the first frame's expected PTS, so no padding or trimming is done.
10653 For example, this could be set to 0 to pad the beginning with duplicates of
10654 the first frame if a video stream starts after the audio stream or to trim any
10655 frames with a negative PTS.
10658 Timestamp (PTS) rounding method.
10660 Possible values are:
10667 round towards -infinity
10669 round towards +infinity
10673 The default is @code{near}.
10676 Action performed when reading the last frame.
10678 Possible values are:
10681 Use same timestamp rounding method as used for other frames.
10683 Pass through last frame if input duration has not been reached yet.
10685 The default is @code{round}.
10689 Alternatively, the options can be specified as a flat string:
10690 @var{fps}[:@var{start_time}[:@var{round}]].
10692 See also the @ref{setpts} filter.
10694 @subsection Examples
10698 A typical usage in order to set the fps to 25:
10704 Sets the fps to 24, using abbreviation and rounding method to round to nearest:
10706 fps=fps=film:round=near
10712 Pack two different video streams into a stereoscopic video, setting proper
10713 metadata on supported codecs. The two views should have the same size and
10714 framerate and processing will stop when the shorter video ends. Please note
10715 that you may conveniently adjust view properties with the @ref{scale} and
10718 It accepts the following parameters:
10722 The desired packing format. Supported values are:
10727 The views are next to each other (default).
10730 The views are on top of each other.
10733 The views are packed by line.
10736 The views are packed by column.
10739 The views are temporally interleaved.
10748 # Convert left and right views into a frame-sequential video
10749 ffmpeg -i LEFT -i RIGHT -filter_complex framepack=frameseq OUTPUT
10751 # Convert views into a side-by-side video with the same output resolution as the input
10752 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
10757 Change the frame rate by interpolating new video output frames from the source
10760 This filter is not designed to function correctly with interlaced media. If
10761 you wish to change the frame rate of interlaced media then you are required
10762 to deinterlace before this filter and re-interlace after this filter.
10764 A description of the accepted options follows.
10768 Specify the output frames per second. This option can also be specified
10769 as a value alone. The default is @code{50}.
10772 Specify the start of a range where the output frame will be created as a
10773 linear interpolation of two frames. The range is [@code{0}-@code{255}],
10774 the default is @code{15}.
10777 Specify the end of a range where the output frame will be created as a
10778 linear interpolation of two frames. The range is [@code{0}-@code{255}],
10779 the default is @code{240}.
10782 Specify the level at which a scene change is detected as a value between
10783 0 and 100 to indicate a new scene; a low value reflects a low
10784 probability for the current frame to introduce a new scene, while a higher
10785 value means the current frame is more likely to be one.
10786 The default is @code{8.2}.
10789 Specify flags influencing the filter process.
10791 Available value for @var{flags} is:
10794 @item scene_change_detect, scd
10795 Enable scene change detection using the value of the option @var{scene}.
10796 This flag is enabled by default.
10802 Select one frame every N-th frame.
10804 This filter accepts the following option:
10807 Select frame after every @code{step} frames.
10808 Allowed values are positive integers higher than 0. Default value is @code{1}.
10811 @section freezedetect
10813 Detect frozen video.
10815 This filter logs a message and sets frame metadata when it detects that the
10816 input video has no significant change in content during a specified duration.
10817 Video freeze detection calculates the mean average absolute difference of all
10818 the components of video frames and compares it to a noise floor.
10820 The printed times and duration are expressed in seconds. The
10821 @code{lavfi.freezedetect.freeze_start} metadata key is set on the first frame
10822 whose timestamp equals or exceeds the detection duration and it contains the
10823 timestamp of the first frame of the freeze. The
10824 @code{lavfi.freezedetect.freeze_duration} and
10825 @code{lavfi.freezedetect.freeze_end} metadata keys are set on the first frame
10828 The filter accepts the following options:
10832 Set noise tolerance. Can be specified in dB (in case "dB" is appended to the
10833 specified value) or as a difference ratio between 0 and 1. Default is -60dB, or
10837 Set freeze duration until notification (default is 2 seconds).
10843 Apply a frei0r effect to the input video.
10845 To enable the compilation of this filter, you need to install the frei0r
10846 header and configure FFmpeg with @code{--enable-frei0r}.
10848 It accepts the following parameters:
10853 The name of the frei0r effect to load. If the environment variable
10854 @env{FREI0R_PATH} is defined, the frei0r effect is searched for in each of the
10855 directories specified by the colon-separated list in @env{FREI0R_PATH}.
10856 Otherwise, the standard frei0r paths are searched, in this order:
10857 @file{HOME/.frei0r-1/lib/}, @file{/usr/local/lib/frei0r-1/},
10858 @file{/usr/lib/frei0r-1/}.
10860 @item filter_params
10861 A '|'-separated list of parameters to pass to the frei0r effect.
10865 A frei0r effect parameter can be a boolean (its value is either
10866 "y" or "n"), a double, a color (specified as
10867 @var{R}/@var{G}/@var{B}, where @var{R}, @var{G}, and @var{B} are floating point
10868 numbers between 0.0 and 1.0, inclusive) or a color description as specified in the
10869 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils},
10870 a position (specified as @var{X}/@var{Y}, where
10871 @var{X} and @var{Y} are floating point numbers) and/or a string.
10873 The number and types of parameters depend on the loaded effect. If an
10874 effect parameter is not specified, the default value is set.
10876 @subsection Examples
10880 Apply the distort0r effect, setting the first two double parameters:
10882 frei0r=filter_name=distort0r:filter_params=0.5|0.01
10886 Apply the colordistance effect, taking a color as the first parameter:
10888 frei0r=colordistance:0.2/0.3/0.4
10889 frei0r=colordistance:violet
10890 frei0r=colordistance:0x112233
10894 Apply the perspective effect, specifying the top left and top right image
10897 frei0r=perspective:0.2/0.2|0.8/0.2
10901 For more information, see
10902 @url{http://frei0r.dyne.org}
10906 Apply fast and simple postprocessing. It is a faster version of @ref{spp}.
10908 It splits (I)DCT into horizontal/vertical passes. Unlike the simple post-
10909 processing filter, one of them is performed once per block, not per pixel.
10910 This allows for much higher speed.
10912 The filter accepts the following options:
10916 Set quality. This option defines the number of levels for averaging. It accepts
10917 an integer in the range 4-5. Default value is @code{4}.
10920 Force a constant quantization parameter. It accepts an integer in range 0-63.
10921 If not set, the filter will use the QP from the video stream (if available).
10924 Set filter strength. It accepts an integer in range -15 to 32. Lower values mean
10925 more details but also more artifacts, while higher values make the image smoother
10926 but also blurrier. Default value is @code{0} − PSNR optimal.
10928 @item use_bframe_qp
10929 Enable the use of the QP from the B-Frames if set to @code{1}. Using this
10930 option may cause flicker since the B-Frames have often larger QP. Default is
10931 @code{0} (not enabled).
10937 Apply Gaussian blur filter.
10939 The filter accepts the following options:
10943 Set horizontal sigma, standard deviation of Gaussian blur. Default is @code{0.5}.
10946 Set number of steps for Gaussian approximation. Default is @code{1}.
10949 Set which planes to filter. By default all planes are filtered.
10952 Set vertical sigma, if negative it will be same as @code{sigma}.
10953 Default is @code{-1}.
10956 @subsection Commands
10957 This filter supports same commands as options.
10958 The command accepts the same syntax of the corresponding option.
10960 If the specified expression is not valid, it is kept at its current
10965 Apply generic equation to each pixel.
10967 The filter accepts the following options:
10970 @item lum_expr, lum
10971 Set the luminance expression.
10973 Set the chrominance blue expression.
10975 Set the chrominance red expression.
10976 @item alpha_expr, a
10977 Set the alpha expression.
10979 Set the red expression.
10980 @item green_expr, g
10981 Set the green expression.
10983 Set the blue expression.
10986 The colorspace is selected according to the specified options. If one
10987 of the @option{lum_expr}, @option{cb_expr}, or @option{cr_expr}
10988 options is specified, the filter will automatically select a YCbCr
10989 colorspace. If one of the @option{red_expr}, @option{green_expr}, or
10990 @option{blue_expr} options is specified, it will select an RGB
10993 If one of the chrominance expression is not defined, it falls back on the other
10994 one. If no alpha expression is specified it will evaluate to opaque value.
10995 If none of chrominance expressions are specified, they will evaluate
10996 to the luminance expression.
10998 The expressions can use the following variables and functions:
11002 The sequential number of the filtered frame, starting from @code{0}.
11006 The coordinates of the current sample.
11010 The width and height of the image.
11014 Width and height scale depending on the currently filtered plane. It is the
11015 ratio between the corresponding luma plane number of pixels and the current
11016 plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and
11017 @code{0.5,0.5} for chroma planes.
11020 Time of the current frame, expressed in seconds.
11023 Return the value of the pixel at location (@var{x},@var{y}) of the current
11027 Return the value of the pixel at location (@var{x},@var{y}) of the luminance
11031 Return the value of the pixel at location (@var{x},@var{y}) of the
11032 blue-difference chroma plane. Return 0 if there is no such plane.
11035 Return the value of the pixel at location (@var{x},@var{y}) of the
11036 red-difference chroma plane. Return 0 if there is no such plane.
11041 Return the value of the pixel at location (@var{x},@var{y}) of the
11042 red/green/blue component. Return 0 if there is no such component.
11045 Return the value of the pixel at location (@var{x},@var{y}) of the alpha
11046 plane. Return 0 if there is no such plane.
11048 @item interpolation
11049 Set one of interpolation methods:
11054 Default is bilinear.
11057 For functions, if @var{x} and @var{y} are outside the area, the value will be
11058 automatically clipped to the closer edge.
11060 @subsection Examples
11064 Flip the image horizontally:
11070 Generate a bidimensional sine wave, with angle @code{PI/3} and a
11071 wavelength of 100 pixels:
11073 geq=128 + 100*sin(2*(PI/100)*(cos(PI/3)*(X-50*T) + sin(PI/3)*Y)):128:128
11077 Generate a fancy enigmatic moving light:
11079 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
11083 Generate a quick emboss effect:
11085 format=gray,geq=lum_expr='(p(X,Y)+(256-p(X-4,Y-4)))/2'
11089 Modify RGB components depending on pixel position:
11091 geq=r='X/W*r(X,Y)':g='(1-X/W)*g(X,Y)':b='(H-Y)/H*b(X,Y)'
11095 Create a radial gradient that is the same size as the input (also see
11096 the @ref{vignette} filter):
11098 geq=lum=255*gauss((X/W-0.5)*3)*gauss((Y/H-0.5)*3)/gauss(0)/gauss(0),format=gray
11104 Fix the banding artifacts that are sometimes introduced into nearly flat
11105 regions by truncation to 8-bit color depth.
11106 Interpolate the gradients that should go where the bands are, and
11109 It is designed for playback only. Do not use it prior to
11110 lossy compression, because compression tends to lose the dither and
11111 bring back the bands.
11113 It accepts the following parameters:
11118 The maximum amount by which the filter will change any one pixel. This is also
11119 the threshold for detecting nearly flat regions. Acceptable values range from
11120 .51 to 64; the default value is 1.2. Out-of-range values will be clipped to the
11124 The neighborhood to fit the gradient to. A larger radius makes for smoother
11125 gradients, but also prevents the filter from modifying the pixels near detailed
11126 regions. Acceptable values are 8-32; the default value is 16. Out-of-range
11127 values will be clipped to the valid range.
11131 Alternatively, the options can be specified as a flat string:
11132 @var{strength}[:@var{radius}]
11134 @subsection Examples
11138 Apply the filter with a @code{3.5} strength and radius of @code{8}:
11144 Specify radius, omitting the strength (which will fall-back to the default
11152 @section graphmonitor, agraphmonitor
11153 Show various filtergraph stats.
11155 With this filter one can debug complete filtergraph.
11156 Especially issues with links filling with queued frames.
11158 The filter accepts the following options:
11162 Set video output size. Default is @var{hd720}.
11165 Set video opacity. Default is @var{0.9}. Allowed range is from @var{0} to @var{1}.
11168 Set output mode, can be @var{fulll} or @var{compact}.
11169 In @var{compact} mode only filters with some queued frames have displayed stats.
11172 Set flags which enable which stats are shown in video.
11174 Available values for flags are:
11177 Display number of queued frames in each link.
11179 @item frame_count_in
11180 Display number of frames taken from filter.
11182 @item frame_count_out
11183 Display number of frames given out from filter.
11186 Display current filtered frame pts.
11189 Display current filtered frame time.
11192 Display time base for filter link.
11195 Display used format for filter link.
11198 Display video size or number of audio channels in case of audio used by filter link.
11201 Display video frame rate or sample rate in case of audio used by filter link.
11205 Set upper limit for video rate of output stream, Default value is @var{25}.
11206 This guarantee that output video frame rate will not be higher than this value.
11210 A color constancy variation filter which estimates scene illumination via grey edge algorithm
11211 and corrects the scene colors accordingly.
11213 See: @url{https://staff.science.uva.nl/th.gevers/pub/GeversTIP07.pdf}
11215 The filter accepts the following options:
11219 The order of differentiation to be applied on the scene. Must be chosen in the range
11220 [0,2] and default value is 1.
11223 The Minkowski parameter to be used for calculating the Minkowski distance. Must
11224 be chosen in the range [0,20] and default value is 1. Set to 0 for getting
11225 max value instead of calculating Minkowski distance.
11228 The standard deviation of Gaussian blur to be applied on the scene. Must be
11229 chosen in the range [0,1024.0] and default value = 1. floor( @var{sigma} * break_off_sigma(3) )
11230 can't be equal to 0 if @var{difford} is greater than 0.
11233 @subsection Examples
11239 greyedge=difford=1:minknorm=5:sigma=2
11245 greyedge=difford=1:minknorm=0:sigma=2
11253 Apply a Hald CLUT to a video stream.
11255 First input is the video stream to process, and second one is the Hald CLUT.
11256 The Hald CLUT input can be a simple picture or a complete video stream.
11258 The filter accepts the following options:
11262 Force termination when the shortest input terminates. Default is @code{0}.
11264 Continue applying the last CLUT after the end of the stream. A value of
11265 @code{0} disable the filter after the last frame of the CLUT is reached.
11266 Default is @code{1}.
11269 @code{haldclut} also has the same interpolation options as @ref{lut3d} (both
11270 filters share the same internals).
11272 This filter also supports the @ref{framesync} options.
11274 More information about the Hald CLUT can be found on Eskil Steenberg's website
11275 (Hald CLUT author) at @url{http://www.quelsolaar.com/technology/clut.html}.
11277 @subsection Workflow examples
11279 @subsubsection Hald CLUT video stream
11281 Generate an identity Hald CLUT stream altered with various effects:
11283 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
11286 Note: make sure you use a lossless codec.
11288 Then use it with @code{haldclut} to apply it on some random stream:
11290 ffmpeg -f lavfi -i mandelbrot -i clut.nut -filter_complex '[0][1] haldclut' -t 20 mandelclut.mkv
11293 The Hald CLUT will be applied to the 10 first seconds (duration of
11294 @file{clut.nut}), then the latest picture of that CLUT stream will be applied
11295 to the remaining frames of the @code{mandelbrot} stream.
11297 @subsubsection Hald CLUT with preview
11299 A Hald CLUT is supposed to be a squared image of @code{Level*Level*Level} by
11300 @code{Level*Level*Level} pixels. For a given Hald CLUT, FFmpeg will select the
11301 biggest possible square starting at the top left of the picture. The remaining
11302 padding pixels (bottom or right) will be ignored. This area can be used to add
11303 a preview of the Hald CLUT.
11305 Typically, the following generated Hald CLUT will be supported by the
11306 @code{haldclut} filter:
11309 ffmpeg -f lavfi -i @ref{haldclutsrc}=8 -vf "
11310 pad=iw+320 [padded_clut];
11311 smptebars=s=320x256, split [a][b];
11312 [padded_clut][a] overlay=W-320:h, curves=color_negative [main];
11313 [main][b] overlay=W-320" -frames:v 1 clut.png
11316 It contains the original and a preview of the effect of the CLUT: SMPTE color
11317 bars are displayed on the right-top, and below the same color bars processed by
11320 Then, the effect of this Hald CLUT can be visualized with:
11322 ffplay input.mkv -vf "movie=clut.png, [in] haldclut"
11327 Flip the input video horizontally.
11329 For example, to horizontally flip the input video with @command{ffmpeg}:
11331 ffmpeg -i in.avi -vf "hflip" out.avi
11335 This filter applies a global color histogram equalization on a
11338 It can be used to correct video that has a compressed range of pixel
11339 intensities. The filter redistributes the pixel intensities to
11340 equalize their distribution across the intensity range. It may be
11341 viewed as an "automatically adjusting contrast filter". This filter is
11342 useful only for correcting degraded or poorly captured source
11345 The filter accepts the following options:
11349 Determine the amount of equalization to be applied. As the strength
11350 is reduced, the distribution of pixel intensities more-and-more
11351 approaches that of the input frame. The value must be a float number
11352 in the range [0,1] and defaults to 0.200.
11355 Set the maximum intensity that can generated and scale the output
11356 values appropriately. The strength should be set as desired and then
11357 the intensity can be limited if needed to avoid washing-out. The value
11358 must be a float number in the range [0,1] and defaults to 0.210.
11361 Set the antibanding level. If enabled the filter will randomly vary
11362 the luminance of output pixels by a small amount to avoid banding of
11363 the histogram. Possible values are @code{none}, @code{weak} or
11364 @code{strong}. It defaults to @code{none}.
11369 Compute and draw a color distribution histogram for the input video.
11371 The computed histogram is a representation of the color component
11372 distribution in an image.
11374 Standard histogram displays the color components distribution in an image.
11375 Displays color graph for each color component. Shows distribution of
11376 the Y, U, V, A or R, G, B components, depending on input format, in the
11377 current frame. Below each graph a color component scale meter is shown.
11379 The filter accepts the following options:
11383 Set height of level. Default value is @code{200}.
11384 Allowed range is [50, 2048].
11387 Set height of color scale. Default value is @code{12}.
11388 Allowed range is [0, 40].
11392 It accepts the following values:
11395 Per color component graphs are placed below each other.
11398 Per color component graphs are placed side by side.
11401 Presents information identical to that in the @code{parade}, except
11402 that the graphs representing color components are superimposed directly
11405 Default is @code{stack}.
11408 Set mode. Can be either @code{linear}, or @code{logarithmic}.
11409 Default is @code{linear}.
11412 Set what color components to display.
11413 Default is @code{7}.
11416 Set foreground opacity. Default is @code{0.7}.
11419 Set background opacity. Default is @code{0.5}.
11422 @subsection Examples
11427 Calculate and draw histogram:
11429 ffplay -i input -vf histogram
11437 This is a high precision/quality 3d denoise filter. It aims to reduce
11438 image noise, producing smooth images and making still images really
11439 still. It should enhance compressibility.
11441 It accepts the following optional parameters:
11445 A non-negative floating point number which specifies spatial luma strength.
11446 It defaults to 4.0.
11448 @item chroma_spatial
11449 A non-negative floating point number which specifies spatial chroma strength.
11450 It defaults to 3.0*@var{luma_spatial}/4.0.
11453 A floating point number which specifies luma temporal strength. It defaults to
11454 6.0*@var{luma_spatial}/4.0.
11457 A floating point number which specifies chroma temporal strength. It defaults to
11458 @var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}.
11461 @anchor{hwdownload}
11462 @section hwdownload
11464 Download hardware frames to system memory.
11466 The input must be in hardware frames, and the output a non-hardware format.
11467 Not all formats will be supported on the output - it may be necessary to insert
11468 an additional @option{format} filter immediately following in the graph to get
11469 the output in a supported format.
11473 Map hardware frames to system memory or to another device.
11475 This filter has several different modes of operation; which one is used depends
11476 on the input and output formats:
11479 Hardware frame input, normal frame output
11481 Map the input frames to system memory and pass them to the output. If the
11482 original hardware frame is later required (for example, after overlaying
11483 something else on part of it), the @option{hwmap} filter can be used again
11484 in the next mode to retrieve it.
11486 Normal frame input, hardware frame output
11488 If the input is actually a software-mapped hardware frame, then unmap it -
11489 that is, return the original hardware frame.
11491 Otherwise, a device must be provided. Create new hardware surfaces on that
11492 device for the output, then map them back to the software format at the input
11493 and give those frames to the preceding filter. This will then act like the
11494 @option{hwupload} filter, but may be able to avoid an additional copy when
11495 the input is already in a compatible format.
11497 Hardware frame input and output
11499 A device must be supplied for the output, either directly or with the
11500 @option{derive_device} option. The input and output devices must be of
11501 different types and compatible - the exact meaning of this is
11502 system-dependent, but typically it means that they must refer to the same
11503 underlying hardware context (for example, refer to the same graphics card).
11505 If the input frames were originally created on the output device, then unmap
11506 to retrieve the original frames.
11508 Otherwise, map the frames to the output device - create new hardware frames
11509 on the output corresponding to the frames on the input.
11512 The following additional parameters are accepted:
11516 Set the frame mapping mode. Some combination of:
11519 The mapped frame should be readable.
11521 The mapped frame should be writeable.
11523 The mapping will always overwrite the entire frame.
11525 This may improve performance in some cases, as the original contents of the
11526 frame need not be loaded.
11528 The mapping must not involve any copying.
11530 Indirect mappings to copies of frames are created in some cases where either
11531 direct mapping is not possible or it would have unexpected properties.
11532 Setting this flag ensures that the mapping is direct and will fail if that is
11535 Defaults to @var{read+write} if not specified.
11537 @item derive_device @var{type}
11538 Rather than using the device supplied at initialisation, instead derive a new
11539 device of type @var{type} from the device the input frames exist on.
11542 In a hardware to hardware mapping, map in reverse - create frames in the sink
11543 and map them back to the source. This may be necessary in some cases where
11544 a mapping in one direction is required but only the opposite direction is
11545 supported by the devices being used.
11547 This option is dangerous - it may break the preceding filter in undefined
11548 ways if there are any additional constraints on that filter's output.
11549 Do not use it without fully understanding the implications of its use.
11555 Upload system memory frames to hardware surfaces.
11557 The device to upload to must be supplied when the filter is initialised. If
11558 using ffmpeg, select the appropriate device with the @option{-filter_hw_device}
11561 @anchor{hwupload_cuda}
11562 @section hwupload_cuda
11564 Upload system memory frames to a CUDA device.
11566 It accepts the following optional parameters:
11570 The number of the CUDA device to use
11575 Apply a high-quality magnification filter designed for pixel art. This filter
11576 was originally created by Maxim Stepin.
11578 It accepts the following option:
11582 Set the scaling dimension: @code{2} for @code{hq2x}, @code{3} for
11583 @code{hq3x} and @code{4} for @code{hq4x}.
11584 Default is @code{3}.
11588 Stack input videos horizontally.
11590 All streams must be of same pixel format and of same height.
11592 Note that this filter is faster than using @ref{overlay} and @ref{pad} filter
11593 to create same output.
11595 The filter accepts the following option:
11599 Set number of input streams. Default is 2.
11602 If set to 1, force the output to terminate when the shortest input
11603 terminates. Default value is 0.
11608 Modify the hue and/or the saturation of the input.
11610 It accepts the following parameters:
11614 Specify the hue angle as a number of degrees. It accepts an expression,
11615 and defaults to "0".
11618 Specify the saturation in the [-10,10] range. It accepts an expression and
11622 Specify the hue angle as a number of radians. It accepts an
11623 expression, and defaults to "0".
11626 Specify the brightness in the [-10,10] range. It accepts an expression and
11630 @option{h} and @option{H} are mutually exclusive, and can't be
11631 specified at the same time.
11633 The @option{b}, @option{h}, @option{H} and @option{s} option values are
11634 expressions containing the following constants:
11638 frame count of the input frame starting from 0
11641 presentation timestamp of the input frame expressed in time base units
11644 frame rate of the input video, NAN if the input frame rate is unknown
11647 timestamp expressed in seconds, NAN if the input timestamp is unknown
11650 time base of the input video
11653 @subsection Examples
11657 Set the hue to 90 degrees and the saturation to 1.0:
11663 Same command but expressing the hue in radians:
11669 Rotate hue and make the saturation swing between 0
11670 and 2 over a period of 1 second:
11672 hue="H=2*PI*t: s=sin(2*PI*t)+1"
11676 Apply a 3 seconds saturation fade-in effect starting at 0:
11678 hue="s=min(t/3\,1)"
11681 The general fade-in expression can be written as:
11683 hue="s=min(0\, max((t-START)/DURATION\, 1))"
11687 Apply a 3 seconds saturation fade-out effect starting at 5 seconds:
11689 hue="s=max(0\, min(1\, (8-t)/3))"
11692 The general fade-out expression can be written as:
11694 hue="s=max(0\, min(1\, (START+DURATION-t)/DURATION))"
11699 @subsection Commands
11701 This filter supports the following commands:
11707 Modify the hue and/or the saturation and/or brightness of the input video.
11708 The command accepts the same syntax of the corresponding option.
11710 If the specified expression is not valid, it is kept at its current
11714 @section hysteresis
11716 Grow first stream into second stream by connecting components.
11717 This makes it possible to build more robust edge masks.
11719 This filter accepts the following options:
11723 Set which planes will be processed as bitmap, unprocessed planes will be
11724 copied from first stream.
11725 By default value 0xf, all planes will be processed.
11728 Set threshold which is used in filtering. If pixel component value is higher than
11729 this value filter algorithm for connecting components is activated.
11730 By default value is 0.
11735 Detect video interlacing type.
11737 This filter tries to detect if the input frames are interlaced, progressive,
11738 top or bottom field first. It will also try to detect fields that are
11739 repeated between adjacent frames (a sign of telecine).
11741 Single frame detection considers only immediately adjacent frames when classifying each frame.
11742 Multiple frame detection incorporates the classification history of previous frames.
11744 The filter will log these metadata values:
11747 @item single.current_frame
11748 Detected type of current frame using single-frame detection. One of:
11749 ``tff'' (top field first), ``bff'' (bottom field first),
11750 ``progressive'', or ``undetermined''
11753 Cumulative number of frames detected as top field first using single-frame detection.
11756 Cumulative number of frames detected as top field first using multiple-frame detection.
11759 Cumulative number of frames detected as bottom field first using single-frame detection.
11761 @item multiple.current_frame
11762 Detected type of current frame using multiple-frame detection. One of:
11763 ``tff'' (top field first), ``bff'' (bottom field first),
11764 ``progressive'', or ``undetermined''
11767 Cumulative number of frames detected as bottom field first using multiple-frame detection.
11769 @item single.progressive
11770 Cumulative number of frames detected as progressive using single-frame detection.
11772 @item multiple.progressive
11773 Cumulative number of frames detected as progressive using multiple-frame detection.
11775 @item single.undetermined
11776 Cumulative number of frames that could not be classified using single-frame detection.
11778 @item multiple.undetermined
11779 Cumulative number of frames that could not be classified using multiple-frame detection.
11781 @item repeated.current_frame
11782 Which field in the current frame is repeated from the last. One of ``neither'', ``top'', or ``bottom''.
11784 @item repeated.neither
11785 Cumulative number of frames with no repeated field.
11788 Cumulative number of frames with the top field repeated from the previous frame's top field.
11790 @item repeated.bottom
11791 Cumulative number of frames with the bottom field repeated from the previous frame's bottom field.
11794 The filter accepts the following options:
11798 Set interlacing threshold.
11800 Set progressive threshold.
11802 Threshold for repeated field detection.
11804 Number of frames after which a given frame's contribution to the
11805 statistics is halved (i.e., it contributes only 0.5 to its
11806 classification). The default of 0 means that all frames seen are given
11807 full weight of 1.0 forever.
11808 @item analyze_interlaced_flag
11809 When this is not 0 then idet will use the specified number of frames to determine
11810 if the interlaced flag is accurate, it will not count undetermined frames.
11811 If the flag is found to be accurate it will be used without any further
11812 computations, if it is found to be inaccurate it will be cleared without any
11813 further computations. This allows inserting the idet filter as a low computational
11814 method to clean up the interlaced flag
11819 Deinterleave or interleave fields.
11821 This filter allows one to process interlaced images fields without
11822 deinterlacing them. Deinterleaving splits the input frame into 2
11823 fields (so called half pictures). Odd lines are moved to the top
11824 half of the output image, even lines to the bottom half.
11825 You can process (filter) them independently and then re-interleave them.
11827 The filter accepts the following options:
11831 @item chroma_mode, c
11832 @item alpha_mode, a
11833 Available values for @var{luma_mode}, @var{chroma_mode} and
11834 @var{alpha_mode} are:
11840 @item deinterleave, d
11841 Deinterleave fields, placing one above the other.
11843 @item interleave, i
11844 Interleave fields. Reverse the effect of deinterleaving.
11846 Default value is @code{none}.
11848 @item luma_swap, ls
11849 @item chroma_swap, cs
11850 @item alpha_swap, as
11851 Swap luma/chroma/alpha fields. Exchange even & odd lines. Default value is @code{0}.
11856 Apply inflate effect to the video.
11858 This filter replaces the pixel by the local(3x3) average by taking into account
11859 only values higher than the pixel.
11861 It accepts the following options:
11868 Limit the maximum change for each plane, default is 65535.
11869 If 0, plane will remain unchanged.
11874 Simple interlacing filter from progressive contents. This interleaves upper (or
11875 lower) lines from odd frames with lower (or upper) lines from even frames,
11876 halving the frame rate and preserving image height.
11879 Original Original New Frame
11880 Frame 'j' Frame 'j+1' (tff)
11881 ========== =========== ==================
11882 Line 0 --------------------> Frame 'j' Line 0
11883 Line 1 Line 1 ----> Frame 'j+1' Line 1
11884 Line 2 ---------------------> Frame 'j' Line 2
11885 Line 3 Line 3 ----> Frame 'j+1' Line 3
11887 New Frame + 1 will be generated by Frame 'j+2' and Frame 'j+3' and so on
11890 It accepts the following optional parameters:
11894 This determines whether the interlaced frame is taken from the even
11895 (tff - default) or odd (bff) lines of the progressive frame.
11898 Vertical lowpass filter to avoid twitter interlacing and
11899 reduce moire patterns.
11903 Disable vertical lowpass filter
11906 Enable linear filter (default)
11909 Enable complex filter. This will slightly less reduce twitter and moire
11910 but better retain detail and subjective sharpness impression.
11917 Deinterlace input video by applying Donald Graft's adaptive kernel
11918 deinterling. Work on interlaced parts of a video to produce
11919 progressive frames.
11921 The description of the accepted parameters follows.
11925 Set the threshold which affects the filter's tolerance when
11926 determining if a pixel line must be processed. It must be an integer
11927 in the range [0,255] and defaults to 10. A value of 0 will result in
11928 applying the process on every pixels.
11931 Paint pixels exceeding the threshold value to white if set to 1.
11935 Set the fields order. Swap fields if set to 1, leave fields alone if
11939 Enable additional sharpening if set to 1. Default is 0.
11942 Enable twoway sharpening if set to 1. Default is 0.
11945 @subsection Examples
11949 Apply default values:
11951 kerndeint=thresh=10:map=0:order=0:sharp=0:twoway=0
11955 Enable additional sharpening:
11961 Paint processed pixels in white:
11969 Slowly update darker pixels.
11971 This filter makes short flashes of light appear longer.
11972 This filter accepts the following options:
11976 Set factor for decaying. Default is .95. Allowed range is from 0 to 1.
11979 Set which planes to filter. Default is all. Allowed range is from 0 to 15.
11982 @section lenscorrection
11984 Correct radial lens distortion
11986 This filter can be used to correct for radial distortion as can result from the use
11987 of wide angle lenses, and thereby re-rectify the image. To find the right parameters
11988 one can use tools available for example as part of opencv or simply trial-and-error.
11989 To use opencv use the calibration sample (under samples/cpp) from the opencv sources
11990 and extract the k1 and k2 coefficients from the resulting matrix.
11992 Note that effectively the same filter is available in the open-source tools Krita and
11993 Digikam from the KDE project.
11995 In contrast to the @ref{vignette} filter, which can also be used to compensate lens errors,
11996 this filter corrects the distortion of the image, whereas @ref{vignette} corrects the
11997 brightness distribution, so you may want to use both filters together in certain
11998 cases, though you will have to take care of ordering, i.e. whether vignetting should
11999 be applied before or after lens correction.
12001 @subsection Options
12003 The filter accepts the following options:
12007 Relative x-coordinate of the focal point of the image, and thereby the center of the
12008 distortion. This value has a range [0,1] and is expressed as fractions of the image
12009 width. Default is 0.5.
12011 Relative y-coordinate of the focal point of the image, and thereby the center of the
12012 distortion. This value has a range [0,1] and is expressed as fractions of the image
12013 height. Default is 0.5.
12015 Coefficient of the quadratic correction term. This value has a range [-1,1]. 0 means
12016 no correction. Default is 0.
12018 Coefficient of the double quadratic correction term. This value has a range [-1,1].
12019 0 means no correction. Default is 0.
12022 The formula that generates the correction is:
12024 @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)
12026 where @var{r_0} is halve of the image diagonal and @var{r_src} and @var{r_tgt} are the
12027 distances from the focal point in the source and target images, respectively.
12031 Apply lens correction via the lensfun library (@url{http://lensfun.sourceforge.net/}).
12033 The @code{lensfun} filter requires the camera make, camera model, and lens model
12034 to apply the lens correction. The filter will load the lensfun database and
12035 query it to find the corresponding camera and lens entries in the database. As
12036 long as these entries can be found with the given options, the filter can
12037 perform corrections on frames. Note that incomplete strings will result in the
12038 filter choosing the best match with the given options, and the filter will
12039 output the chosen camera and lens models (logged with level "info"). You must
12040 provide the make, camera model, and lens model as they are required.
12042 The filter accepts the following options:
12046 The make of the camera (for example, "Canon"). This option is required.
12049 The model of the camera (for example, "Canon EOS 100D"). This option is
12053 The model of the lens (for example, "Canon EF-S 18-55mm f/3.5-5.6 IS STM"). This
12054 option is required.
12057 The type of correction to apply. The following values are valid options:
12061 Enables fixing lens vignetting.
12064 Enables fixing lens geometry. This is the default.
12067 Enables fixing chromatic aberrations.
12070 Enables fixing lens vignetting and lens geometry.
12073 Enables fixing lens vignetting and chromatic aberrations.
12076 Enables fixing both lens geometry and chromatic aberrations.
12079 Enables all possible corrections.
12083 The focal length of the image/video (zoom; expected constant for video). For
12084 example, a 18--55mm lens has focal length range of [18--55], so a value in that
12085 range should be chosen when using that lens. Default 18.
12088 The aperture of the image/video (expected constant for video). Note that
12089 aperture is only used for vignetting correction. Default 3.5.
12091 @item focus_distance
12092 The focus distance of the image/video (expected constant for video). Note that
12093 focus distance is only used for vignetting and only slightly affects the
12094 vignetting correction process. If unknown, leave it at the default value (which
12098 The scale factor which is applied after transformation. After correction the
12099 video is no longer necessarily rectangular. This parameter controls how much of
12100 the resulting image is visible. The value 0 means that a value will be chosen
12101 automatically such that there is little or no unmapped area in the output
12102 image. 1.0 means that no additional scaling is done. Lower values may result
12103 in more of the corrected image being visible, while higher values may avoid
12104 unmapped areas in the output.
12106 @item target_geometry
12107 The target geometry of the output image/video. The following values are valid
12111 @item rectilinear (default)
12114 @item equirectangular
12115 @item fisheye_orthographic
12116 @item fisheye_stereographic
12117 @item fisheye_equisolid
12118 @item fisheye_thoby
12121 Apply the reverse of image correction (instead of correcting distortion, apply
12124 @item interpolation
12125 The type of interpolation used when correcting distortion. The following values
12130 @item linear (default)
12135 @subsection Examples
12139 Apply lens correction with make "Canon", camera model "Canon EOS 100D", and lens
12140 model "Canon EF-S 18-55mm f/3.5-5.6 IS STM" with focal length of "18" and
12144 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
12148 Apply the same as before, but only for the first 5 seconds of video.
12151 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
12158 Obtain the VMAF (Video Multi-Method Assessment Fusion)
12159 score between two input videos.
12161 The obtained VMAF score is printed through the logging system.
12163 It requires Netflix's vmaf library (libvmaf) as a pre-requisite.
12164 After installing the library it can be enabled using:
12165 @code{./configure --enable-libvmaf --enable-version3}.
12166 If no model path is specified it uses the default model: @code{vmaf_v0.6.1.pkl}.
12168 The filter has following options:
12172 Set the model path which is to be used for SVM.
12173 Default value: @code{"vmaf_v0.6.1.pkl"}
12176 Set the file path to be used to store logs.
12179 Set the format of the log file (xml or json).
12181 @item enable_transform
12182 This option can enable/disable the @code{score_transform} applied to the final predicted VMAF score,
12183 if you have specified score_transform option in the input parameter file passed to @code{run_vmaf_training.py}
12184 Default value: @code{false}
12187 Invokes the phone model which will generate VMAF scores higher than in the
12188 regular model, which is more suitable for laptop, TV, etc. viewing conditions.
12191 Enables computing psnr along with vmaf.
12194 Enables computing ssim along with vmaf.
12197 Enables computing ms_ssim along with vmaf.
12200 Set the pool method (mean, min or harmonic mean) to be used for computing vmaf.
12203 Set number of threads to be used when computing vmaf.
12206 Set interval for frame subsampling used when computing vmaf.
12208 @item enable_conf_interval
12209 Enables confidence interval.
12212 This filter also supports the @ref{framesync} options.
12214 On the below examples the input file @file{main.mpg} being processed is
12215 compared with the reference file @file{ref.mpg}.
12218 ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf -f null -
12221 Example with options:
12223 ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf="psnr=1:log_fmt=json" -f null -
12228 Limits the pixel components values to the specified range [min, max].
12230 The filter accepts the following options:
12234 Lower bound. Defaults to the lowest allowed value for the input.
12237 Upper bound. Defaults to the highest allowed value for the input.
12240 Specify which planes will be processed. Defaults to all available.
12247 The filter accepts the following options:
12251 Set the number of loops. Setting this value to -1 will result in infinite loops.
12255 Set maximal size in number of frames. Default is 0.
12258 Set first frame of loop. Default is 0.
12261 @subsection Examples
12265 Loop single first frame infinitely:
12267 loop=loop=-1:size=1:start=0
12271 Loop single first frame 10 times:
12273 loop=loop=10:size=1:start=0
12277 Loop 10 first frames 5 times:
12279 loop=loop=5:size=10:start=0
12285 Apply a 1D LUT to an input video.
12287 The filter accepts the following options:
12291 Set the 1D LUT file name.
12293 Currently supported formats:
12302 Select interpolation mode.
12304 Available values are:
12308 Use values from the nearest defined point.
12310 Interpolate values using the linear interpolation.
12312 Interpolate values using the cosine interpolation.
12314 Interpolate values using the cubic interpolation.
12316 Interpolate values using the spline interpolation.
12323 Apply a 3D LUT to an input video.
12325 The filter accepts the following options:
12329 Set the 3D LUT file name.
12331 Currently supported formats:
12345 Select interpolation mode.
12347 Available values are:
12351 Use values from the nearest defined point.
12353 Interpolate values using the 8 points defining a cube.
12355 Interpolate values using a tetrahedron.
12361 Turn certain luma values into transparency.
12363 The filter accepts the following options:
12367 Set the luma which will be used as base for transparency.
12368 Default value is @code{0}.
12371 Set the range of luma values to be keyed out.
12372 Default value is @code{0}.
12375 Set the range of softness. Default value is @code{0}.
12376 Use this to control gradual transition from zero to full transparency.
12379 @section lut, lutrgb, lutyuv
12381 Compute a look-up table for binding each pixel component input value
12382 to an output value, and apply it to the input video.
12384 @var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb}
12385 to an RGB input video.
12387 These filters accept the following parameters:
12390 set first pixel component expression
12392 set second pixel component expression
12394 set third pixel component expression
12396 set fourth pixel component expression, corresponds to the alpha component
12399 set red component expression
12401 set green component expression
12403 set blue component expression
12405 alpha component expression
12408 set Y/luminance component expression
12410 set U/Cb component expression
12412 set V/Cr component expression
12415 Each of them specifies the expression to use for computing the lookup table for
12416 the corresponding pixel component values.
12418 The exact component associated to each of the @var{c*} options depends on the
12421 The @var{lut} filter requires either YUV or RGB pixel formats in input,
12422 @var{lutrgb} requires RGB pixel formats in input, and @var{lutyuv} requires YUV.
12424 The expressions can contain the following constants and functions:
12429 The input width and height.
12432 The input value for the pixel component.
12435 The input value, clipped to the @var{minval}-@var{maxval} range.
12438 The maximum value for the pixel component.
12441 The minimum value for the pixel component.
12444 The negated value for the pixel component value, clipped to the
12445 @var{minval}-@var{maxval} range; it corresponds to the expression
12446 "maxval-clipval+minval".
12449 The computed value in @var{val}, clipped to the
12450 @var{minval}-@var{maxval} range.
12452 @item gammaval(gamma)
12453 The computed gamma correction value of the pixel component value,
12454 clipped to the @var{minval}-@var{maxval} range. It corresponds to the
12456 "pow((clipval-minval)/(maxval-minval)\,@var{gamma})*(maxval-minval)+minval"
12460 All expressions default to "val".
12462 @subsection Examples
12466 Negate input video:
12468 lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val"
12469 lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val"
12472 The above is the same as:
12474 lutrgb="r=negval:g=negval:b=negval"
12475 lutyuv="y=negval:u=negval:v=negval"
12485 Remove chroma components, turning the video into a graytone image:
12487 lutyuv="u=128:v=128"
12491 Apply a luma burning effect:
12497 Remove green and blue components:
12503 Set a constant alpha channel value on input:
12505 format=rgba,lutrgb=a="maxval-minval/2"
12509 Correct luminance gamma by a factor of 0.5:
12511 lutyuv=y=gammaval(0.5)
12515 Discard least significant bits of luma:
12517 lutyuv=y='bitand(val, 128+64+32)'
12521 Technicolor like effect:
12523 lutyuv=u='(val-maxval/2)*2+maxval/2':v='(val-maxval/2)*2+maxval/2'
12527 @section lut2, tlut2
12529 The @code{lut2} filter takes two input streams and outputs one
12532 The @code{tlut2} (time lut2) filter takes two consecutive frames
12533 from one single stream.
12535 This filter accepts the following parameters:
12538 set first pixel component expression
12540 set second pixel component expression
12542 set third pixel component expression
12544 set fourth pixel component expression, corresponds to the alpha component
12547 set output bit depth, only available for @code{lut2} filter. By default is 0,
12548 which means bit depth is automatically picked from first input format.
12551 Each of them specifies the expression to use for computing the lookup table for
12552 the corresponding pixel component values.
12554 The exact component associated to each of the @var{c*} options depends on the
12557 The expressions can contain the following constants:
12562 The input width and height.
12565 The first input value for the pixel component.
12568 The second input value for the pixel component.
12571 The first input video bit depth.
12574 The second input video bit depth.
12577 All expressions default to "x".
12579 @subsection Examples
12583 Highlight differences between two RGB video streams:
12585 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)'
12589 Highlight differences between two YUV video streams:
12591 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)'
12595 Show max difference between two video streams:
12597 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)))'
12601 @section maskedclamp
12603 Clamp the first input stream with the second input and third input stream.
12605 Returns the value of first stream to be between second input
12606 stream - @code{undershoot} and third input stream + @code{overshoot}.
12608 This filter accepts the following options:
12611 Default value is @code{0}.
12614 Default value is @code{0}.
12617 Set which planes will be processed as bitmap, unprocessed planes will be
12618 copied from first stream.
12619 By default value 0xf, all planes will be processed.
12622 @section maskedmerge
12624 Merge the first input stream with the second input stream using per pixel
12625 weights in the third input stream.
12627 A value of 0 in the third stream pixel component means that pixel component
12628 from first stream is returned unchanged, while maximum value (eg. 255 for
12629 8-bit videos) means that pixel component from second stream is returned
12630 unchanged. Intermediate values define the amount of merging between both
12631 input stream's pixel components.
12633 This filter accepts the following options:
12636 Set which planes will be processed as bitmap, unprocessed planes will be
12637 copied from first stream.
12638 By default value 0xf, all planes will be processed.
12642 Create mask from input video.
12644 For example it is useful to create motion masks after @code{tblend} filter.
12646 This filter accepts the following options:
12650 Set low threshold. Any pixel component lower or exact than this value will be set to 0.
12653 Set high threshold. Any pixel component higher than this value will be set to max value
12654 allowed for current pixel format.
12657 Set planes to filter, by default all available planes are filtered.
12660 Fill all frame pixels with this value.
12663 Set max average pixel value for frame. If sum of all pixel components is higher that this
12664 average, output frame will be completely filled with value set by @var{fill} option.
12665 Typically useful for scene changes when used in combination with @code{tblend} filter.
12670 Apply motion-compensation deinterlacing.
12672 It needs one field per frame as input and must thus be used together
12673 with yadif=1/3 or equivalent.
12675 This filter accepts the following options:
12678 Set the deinterlacing mode.
12680 It accepts one of the following values:
12685 use iterative motion estimation
12687 like @samp{slow}, but use multiple reference frames.
12689 Default value is @samp{fast}.
12692 Set the picture field parity assumed for the input video. It must be
12693 one of the following values:
12697 assume top field first
12699 assume bottom field first
12702 Default value is @samp{bff}.
12705 Set per-block quantization parameter (QP) used by the internal
12708 Higher values should result in a smoother motion vector field but less
12709 optimal individual vectors. Default value is 1.
12712 @section mergeplanes
12714 Merge color channel components from several video streams.
12716 The filter accepts up to 4 input streams, and merge selected input
12717 planes to the output video.
12719 This filter accepts the following options:
12722 Set input to output plane mapping. Default is @code{0}.
12724 The mappings is specified as a bitmap. It should be specified as a
12725 hexadecimal number in the form 0xAa[Bb[Cc[Dd]]]. 'Aa' describes the
12726 mapping for the first plane of the output stream. 'A' sets the number of
12727 the input stream to use (from 0 to 3), and 'a' the plane number of the
12728 corresponding input to use (from 0 to 3). The rest of the mappings is
12729 similar, 'Bb' describes the mapping for the output stream second
12730 plane, 'Cc' describes the mapping for the output stream third plane and
12731 'Dd' describes the mapping for the output stream fourth plane.
12734 Set output pixel format. Default is @code{yuva444p}.
12737 @subsection Examples
12741 Merge three gray video streams of same width and height into single video stream:
12743 [a0][a1][a2]mergeplanes=0x001020:yuv444p
12747 Merge 1st yuv444p stream and 2nd gray video stream into yuva444p video stream:
12749 [a0][a1]mergeplanes=0x00010210:yuva444p
12753 Swap Y and A plane in yuva444p stream:
12755 format=yuva444p,mergeplanes=0x03010200:yuva444p
12759 Swap U and V plane in yuv420p stream:
12761 format=yuv420p,mergeplanes=0x000201:yuv420p
12765 Cast a rgb24 clip to yuv444p:
12767 format=rgb24,mergeplanes=0x000102:yuv444p
12773 Estimate and export motion vectors using block matching algorithms.
12774 Motion vectors are stored in frame side data to be used by other filters.
12776 This filter accepts the following options:
12779 Specify the motion estimation method. Accepts one of the following values:
12783 Exhaustive search algorithm.
12785 Three step search algorithm.
12787 Two dimensional logarithmic search algorithm.
12789 New three step search algorithm.
12791 Four step search algorithm.
12793 Diamond search algorithm.
12795 Hexagon-based search algorithm.
12797 Enhanced predictive zonal search algorithm.
12799 Uneven multi-hexagon search algorithm.
12801 Default value is @samp{esa}.
12804 Macroblock size. Default @code{16}.
12807 Search parameter. Default @code{7}.
12810 @section midequalizer
12812 Apply Midway Image Equalization effect using two video streams.
12814 Midway Image Equalization adjusts a pair of images to have the same
12815 histogram, while maintaining their dynamics as much as possible. It's
12816 useful for e.g. matching exposures from a pair of stereo cameras.
12818 This filter has two inputs and one output, which must be of same pixel format, but
12819 may be of different sizes. The output of filter is first input adjusted with
12820 midway histogram of both inputs.
12822 This filter accepts the following option:
12826 Set which planes to process. Default is @code{15}, which is all available planes.
12829 @section minterpolate
12831 Convert the video to specified frame rate using motion interpolation.
12833 This filter accepts the following options:
12836 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}.
12839 Motion interpolation mode. Following values are accepted:
12842 Duplicate previous or next frame for interpolating new ones.
12844 Blend source frames. Interpolated frame is mean of previous and next frames.
12846 Motion compensated interpolation. Following options are effective when this mode is selected:
12850 Motion compensation mode. Following values are accepted:
12853 Overlapped block motion compensation.
12855 Adaptive overlapped block motion compensation. Window weighting coefficients are controlled adaptively according to the reliabilities of the neighboring motion vectors to reduce oversmoothing.
12857 Default mode is @samp{obmc}.
12860 Motion estimation mode. Following values are accepted:
12863 Bidirectional motion estimation. Motion vectors are estimated for each source frame in both forward and backward directions.
12865 Bilateral motion estimation. Motion vectors are estimated directly for interpolated frame.
12867 Default mode is @samp{bilat}.
12870 The algorithm to be used for motion estimation. Following values are accepted:
12873 Exhaustive search algorithm.
12875 Three step search algorithm.
12877 Two dimensional logarithmic search algorithm.
12879 New three step search algorithm.
12881 Four step search algorithm.
12883 Diamond search algorithm.
12885 Hexagon-based search algorithm.
12887 Enhanced predictive zonal search algorithm.
12889 Uneven multi-hexagon search algorithm.
12891 Default algorithm is @samp{epzs}.
12894 Macroblock size. Default @code{16}.
12897 Motion estimation search parameter. Default @code{32}.
12900 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).
12905 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:
12908 Disable scene change detection.
12910 Frame difference. Corresponding pixel values are compared and if it satisfies @var{scd_threshold} scene change is detected.
12912 Default method is @samp{fdiff}.
12914 @item scd_threshold
12915 Scene change detection threshold. Default is @code{5.0}.
12920 Mix several video input streams into one video stream.
12922 A description of the accepted options follows.
12926 The number of inputs. If unspecified, it defaults to 2.
12929 Specify weight of each input video stream as sequence.
12930 Each weight is separated by space. If number of weights
12931 is smaller than number of @var{frames} last specified
12932 weight will be used for all remaining unset weights.
12935 Specify scale, if it is set it will be multiplied with sum
12936 of each weight multiplied with pixel values to give final destination
12937 pixel value. By default @var{scale} is auto scaled to sum of weights.
12940 Specify how end of stream is determined.
12943 The duration of the longest input. (default)
12946 The duration of the shortest input.
12949 The duration of the first input.
12953 @section mpdecimate
12955 Drop frames that do not differ greatly from the previous frame in
12956 order to reduce frame rate.
12958 The main use of this filter is for very-low-bitrate encoding
12959 (e.g. streaming over dialup modem), but it could in theory be used for
12960 fixing movies that were inverse-telecined incorrectly.
12962 A description of the accepted options follows.
12966 Set the maximum number of consecutive frames which can be dropped (if
12967 positive), or the minimum interval between dropped frames (if
12968 negative). If the value is 0, the frame is dropped disregarding the
12969 number of previous sequentially dropped frames.
12971 Default value is 0.
12976 Set the dropping threshold values.
12978 Values for @option{hi} and @option{lo} are for 8x8 pixel blocks and
12979 represent actual pixel value differences, so a threshold of 64
12980 corresponds to 1 unit of difference for each pixel, or the same spread
12981 out differently over the block.
12983 A frame is a candidate for dropping if no 8x8 blocks differ by more
12984 than a threshold of @option{hi}, and if no more than @option{frac} blocks (1
12985 meaning the whole image) differ by more than a threshold of @option{lo}.
12987 Default value for @option{hi} is 64*12, default value for @option{lo} is
12988 64*5, and default value for @option{frac} is 0.33.
12994 Negate (invert) the input video.
12996 It accepts the following option:
13001 With value 1, it negates the alpha component, if present. Default value is 0.
13007 Denoise frames using Non-Local Means algorithm.
13009 Each pixel is adjusted by looking for other pixels with similar contexts. This
13010 context similarity is defined by comparing their surrounding patches of size
13011 @option{p}x@option{p}. Patches are searched in an area of @option{r}x@option{r}
13014 Note that the research area defines centers for patches, which means some
13015 patches will be made of pixels outside that research area.
13017 The filter accepts the following options.
13021 Set denoising strength. Default is 1.0. Must be in range [1.0, 30.0].
13024 Set patch size. Default is 7. Must be odd number in range [0, 99].
13027 Same as @option{p} but for chroma planes.
13029 The default value is @var{0} and means automatic.
13032 Set research size. Default is 15. Must be odd number in range [0, 99].
13035 Same as @option{r} but for chroma planes.
13037 The default value is @var{0} and means automatic.
13042 Deinterlace video using neural network edge directed interpolation.
13044 This filter accepts the following options:
13048 Mandatory option, without binary file filter can not work.
13049 Currently file can be found here:
13050 https://github.com/dubhater/vapoursynth-nnedi3/blob/master/src/nnedi3_weights.bin
13053 Set which frames to deinterlace, by default it is @code{all}.
13054 Can be @code{all} or @code{interlaced}.
13057 Set mode of operation.
13059 Can be one of the following:
13063 Use frame flags, both fields.
13065 Use frame flags, single field.
13067 Use top field only.
13069 Use bottom field only.
13071 Use both fields, top first.
13073 Use both fields, bottom first.
13077 Set which planes to process, by default filter process all frames.
13080 Set size of local neighborhood around each pixel, used by the predictor neural
13083 Can be one of the following:
13096 Set the number of neurons in predictor neural network.
13097 Can be one of the following:
13108 Controls the number of different neural network predictions that are blended
13109 together to compute the final output value. Can be @code{fast}, default or
13113 Set which set of weights to use in the predictor.
13114 Can be one of the following:
13118 weights trained to minimize absolute error
13120 weights trained to minimize squared error
13124 Controls whether or not the prescreener neural network is used to decide
13125 which pixels should be processed by the predictor neural network and which
13126 can be handled by simple cubic interpolation.
13127 The prescreener is trained to know whether cubic interpolation will be
13128 sufficient for a pixel or whether it should be predicted by the predictor nn.
13129 The computational complexity of the prescreener nn is much less than that of
13130 the predictor nn. Since most pixels can be handled by cubic interpolation,
13131 using the prescreener generally results in much faster processing.
13132 The prescreener is pretty accurate, so the difference between using it and not
13133 using it is almost always unnoticeable.
13135 Can be one of the following:
13143 Default is @code{new}.
13146 Set various debugging flags.
13151 Force libavfilter not to use any of the specified pixel formats for the
13152 input to the next filter.
13154 It accepts the following parameters:
13158 A '|'-separated list of pixel format names, such as
13159 pix_fmts=yuv420p|monow|rgb24".
13163 @subsection Examples
13167 Force libavfilter to use a format different from @var{yuv420p} for the
13168 input to the vflip filter:
13170 noformat=pix_fmts=yuv420p,vflip
13174 Convert the input video to any of the formats not contained in the list:
13176 noformat=yuv420p|yuv444p|yuv410p
13182 Add noise on video input frame.
13184 The filter accepts the following options:
13192 Set noise seed for specific pixel component or all pixel components in case
13193 of @var{all_seed}. Default value is @code{123457}.
13195 @item all_strength, alls
13196 @item c0_strength, c0s
13197 @item c1_strength, c1s
13198 @item c2_strength, c2s
13199 @item c3_strength, c3s
13200 Set noise strength for specific pixel component or all pixel components in case
13201 @var{all_strength}. Default value is @code{0}. Allowed range is [0, 100].
13203 @item all_flags, allf
13204 @item c0_flags, c0f
13205 @item c1_flags, c1f
13206 @item c2_flags, c2f
13207 @item c3_flags, c3f
13208 Set pixel component flags or set flags for all components if @var{all_flags}.
13209 Available values for component flags are:
13212 averaged temporal noise (smoother)
13214 mix random noise with a (semi)regular pattern
13216 temporal noise (noise pattern changes between frames)
13218 uniform noise (gaussian otherwise)
13222 @subsection Examples
13224 Add temporal and uniform noise to input video:
13226 noise=alls=20:allf=t+u
13231 Normalize RGB video (aka histogram stretching, contrast stretching).
13232 See: https://en.wikipedia.org/wiki/Normalization_(image_processing)
13234 For each channel of each frame, the filter computes the input range and maps
13235 it linearly to the user-specified output range. The output range defaults
13236 to the full dynamic range from pure black to pure white.
13238 Temporal smoothing can be used on the input range to reduce flickering (rapid
13239 changes in brightness) caused when small dark or bright objects enter or leave
13240 the scene. This is similar to the auto-exposure (automatic gain control) on a
13241 video camera, and, like a video camera, it may cause a period of over- or
13242 under-exposure of the video.
13244 The R,G,B channels can be normalized independently, which may cause some
13245 color shifting, or linked together as a single channel, which prevents
13246 color shifting. Linked normalization preserves hue. Independent normalization
13247 does not, so it can be used to remove some color casts. Independent and linked
13248 normalization can be combined in any ratio.
13250 The normalize filter accepts the following options:
13255 Colors which define the output range. The minimum input value is mapped to
13256 the @var{blackpt}. The maximum input value is mapped to the @var{whitept}.
13257 The defaults are black and white respectively. Specifying white for
13258 @var{blackpt} and black for @var{whitept} will give color-inverted,
13259 normalized video. Shades of grey can be used to reduce the dynamic range
13260 (contrast). Specifying saturated colors here can create some interesting
13264 The number of previous frames to use for temporal smoothing. The input range
13265 of each channel is smoothed using a rolling average over the current frame
13266 and the @var{smoothing} previous frames. The default is 0 (no temporal
13270 Controls the ratio of independent (color shifting) channel normalization to
13271 linked (color preserving) normalization. 0.0 is fully linked, 1.0 is fully
13272 independent. Defaults to 1.0 (fully independent).
13275 Overall strength of the filter. 1.0 is full strength. 0.0 is a rather
13276 expensive no-op. Defaults to 1.0 (full strength).
13280 @subsection Examples
13282 Stretch video contrast to use the full dynamic range, with no temporal
13283 smoothing; may flicker depending on the source content:
13285 normalize=blackpt=black:whitept=white:smoothing=0
13288 As above, but with 50 frames of temporal smoothing; flicker should be
13289 reduced, depending on the source content:
13291 normalize=blackpt=black:whitept=white:smoothing=50
13294 As above, but with hue-preserving linked channel normalization:
13296 normalize=blackpt=black:whitept=white:smoothing=50:independence=0
13299 As above, but with half strength:
13301 normalize=blackpt=black:whitept=white:smoothing=50:independence=0:strength=0.5
13304 Map the darkest input color to red, the brightest input color to cyan:
13306 normalize=blackpt=red:whitept=cyan
13311 Pass the video source unchanged to the output.
13314 Optical Character Recognition
13316 This filter uses Tesseract for optical character recognition. To enable
13317 compilation of this filter, you need to configure FFmpeg with
13318 @code{--enable-libtesseract}.
13320 It accepts the following options:
13324 Set datapath to tesseract data. Default is to use whatever was
13325 set at installation.
13328 Set language, default is "eng".
13331 Set character whitelist.
13334 Set character blacklist.
13337 The filter exports recognized text as the frame metadata @code{lavfi.ocr.text}.
13338 The filter exports confidence of recognized words as the frame metadata @code{lavfi.ocr.confidence}.
13342 Apply a video transform using libopencv.
13344 To enable this filter, install the libopencv library and headers and
13345 configure FFmpeg with @code{--enable-libopencv}.
13347 It accepts the following parameters:
13352 The name of the libopencv filter to apply.
13354 @item filter_params
13355 The parameters to pass to the libopencv filter. If not specified, the default
13356 values are assumed.
13360 Refer to the official libopencv documentation for more precise
13362 @url{http://docs.opencv.org/master/modules/imgproc/doc/filtering.html}
13364 Several libopencv filters are supported; see the following subsections.
13369 Dilate an image by using a specific structuring element.
13370 It corresponds to the libopencv function @code{cvDilate}.
13372 It accepts the parameters: @var{struct_el}|@var{nb_iterations}.
13374 @var{struct_el} represents a structuring element, and has the syntax:
13375 @var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape}
13377 @var{cols} and @var{rows} represent the number of columns and rows of
13378 the structuring element, @var{anchor_x} and @var{anchor_y} the anchor
13379 point, and @var{shape} the shape for the structuring element. @var{shape}
13380 must be "rect", "cross", "ellipse", or "custom".
13382 If the value for @var{shape} is "custom", it must be followed by a
13383 string of the form "=@var{filename}". The file with name
13384 @var{filename} is assumed to represent a binary image, with each
13385 printable character corresponding to a bright pixel. When a custom
13386 @var{shape} is used, @var{cols} and @var{rows} are ignored, the number
13387 or columns and rows of the read file are assumed instead.
13389 The default value for @var{struct_el} is "3x3+0x0/rect".
13391 @var{nb_iterations} specifies the number of times the transform is
13392 applied to the image, and defaults to 1.
13396 # Use the default values
13399 # Dilate using a structuring element with a 5x5 cross, iterating two times
13400 ocv=filter_name=dilate:filter_params=5x5+2x2/cross|2
13402 # Read the shape from the file diamond.shape, iterating two times.
13403 # The file diamond.shape may contain a pattern of characters like this
13409 # The specified columns and rows are ignored
13410 # but the anchor point coordinates are not
13411 ocv=dilate:0x0+2x2/custom=diamond.shape|2
13416 Erode an image by using a specific structuring element.
13417 It corresponds to the libopencv function @code{cvErode}.
13419 It accepts the parameters: @var{struct_el}:@var{nb_iterations},
13420 with the same syntax and semantics as the @ref{dilate} filter.
13424 Smooth the input video.
13426 The filter takes the following parameters:
13427 @var{type}|@var{param1}|@var{param2}|@var{param3}|@var{param4}.
13429 @var{type} is the type of smooth filter to apply, and must be one of
13430 the following values: "blur", "blur_no_scale", "median", "gaussian",
13431 or "bilateral". The default value is "gaussian".
13433 The meaning of @var{param1}, @var{param2}, @var{param3}, and @var{param4}
13434 depends on the smooth type. @var{param1} and
13435 @var{param2} accept integer positive values or 0. @var{param3} and
13436 @var{param4} accept floating point values.
13438 The default value for @var{param1} is 3. The default value for the
13439 other parameters is 0.
13441 These parameters correspond to the parameters assigned to the
13442 libopencv function @code{cvSmooth}.
13444 @section oscilloscope
13446 2D Video Oscilloscope.
13448 Useful to measure spatial impulse, step responses, chroma delays, etc.
13450 It accepts the following parameters:
13454 Set scope center x position.
13457 Set scope center y position.
13460 Set scope size, relative to frame diagonal.
13463 Set scope tilt/rotation.
13469 Set trace center x position.
13472 Set trace center y position.
13475 Set trace width, relative to width of frame.
13478 Set trace height, relative to height of frame.
13481 Set which components to trace. By default it traces first three components.
13484 Draw trace grid. By default is enabled.
13487 Draw some statistics. By default is enabled.
13490 Draw scope. By default is enabled.
13493 @subsection Examples
13497 Inspect full first row of video frame.
13499 oscilloscope=x=0.5:y=0:s=1
13503 Inspect full last row of video frame.
13505 oscilloscope=x=0.5:y=1:s=1
13509 Inspect full 5th line of video frame of height 1080.
13511 oscilloscope=x=0.5:y=5/1080:s=1
13515 Inspect full last column of video frame.
13517 oscilloscope=x=1:y=0.5:s=1:t=1
13525 Overlay one video on top of another.
13527 It takes two inputs and has one output. The first input is the "main"
13528 video on which the second input is overlaid.
13530 It accepts the following parameters:
13532 A description of the accepted options follows.
13537 Set the expression for the x and y coordinates of the overlaid video
13538 on the main video. Default value is "0" for both expressions. In case
13539 the expression is invalid, it is set to a huge value (meaning that the
13540 overlay will not be displayed within the output visible area).
13543 See @ref{framesync}.
13546 Set when the expressions for @option{x}, and @option{y} are evaluated.
13548 It accepts the following values:
13551 only evaluate expressions once during the filter initialization or
13552 when a command is processed
13555 evaluate expressions for each incoming frame
13558 Default value is @samp{frame}.
13561 See @ref{framesync}.
13564 Set the format for the output video.
13566 It accepts the following values:
13569 force YUV420 output
13572 force YUV422 output
13575 force YUV444 output
13578 force packed RGB output
13581 force planar RGB output
13584 automatically pick format
13587 Default value is @samp{yuv420}.
13590 See @ref{framesync}.
13593 Set format of alpha of the overlaid video, it can be @var{straight} or
13594 @var{premultiplied}. Default is @var{straight}.
13597 The @option{x}, and @option{y} expressions can contain the following
13603 The main input width and height.
13607 The overlay input width and height.
13611 The computed values for @var{x} and @var{y}. They are evaluated for
13616 horizontal and vertical chroma subsample values of the output
13617 format. For example for the pixel format "yuv422p" @var{hsub} is 2 and
13621 the number of input frame, starting from 0
13624 the position in the file of the input frame, NAN if unknown
13627 The timestamp, expressed in seconds. It's NAN if the input timestamp is unknown.
13631 This filter also supports the @ref{framesync} options.
13633 Note that the @var{n}, @var{pos}, @var{t} variables are available only
13634 when evaluation is done @emph{per frame}, and will evaluate to NAN
13635 when @option{eval} is set to @samp{init}.
13637 Be aware that frames are taken from each input video in timestamp
13638 order, hence, if their initial timestamps differ, it is a good idea
13639 to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to
13640 have them begin in the same zero timestamp, as the example for
13641 the @var{movie} filter does.
13643 You can chain together more overlays but you should test the
13644 efficiency of such approach.
13646 @subsection Commands
13648 This filter supports the following commands:
13652 Modify the x and y of the overlay input.
13653 The command accepts the same syntax of the corresponding option.
13655 If the specified expression is not valid, it is kept at its current
13659 @subsection Examples
13663 Draw the overlay at 10 pixels from the bottom right corner of the main
13666 overlay=main_w-overlay_w-10:main_h-overlay_h-10
13669 Using named options the example above becomes:
13671 overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10
13675 Insert a transparent PNG logo in the bottom left corner of the input,
13676 using the @command{ffmpeg} tool with the @code{-filter_complex} option:
13678 ffmpeg -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output
13682 Insert 2 different transparent PNG logos (second logo on bottom
13683 right corner) using the @command{ffmpeg} tool:
13685 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
13689 Add a transparent color layer on top of the main video; @code{WxH}
13690 must specify the size of the main input to the overlay filter:
13692 color=color=red@@.3:size=WxH [over]; [in][over] overlay [out]
13696 Play an original video and a filtered version (here with the deshake
13697 filter) side by side using the @command{ffplay} tool:
13699 ffplay input.avi -vf 'split[a][b]; [a]pad=iw*2:ih[src]; [b]deshake[filt]; [src][filt]overlay=w'
13702 The above command is the same as:
13704 ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w'
13708 Make a sliding overlay appearing from the left to the right top part of the
13709 screen starting since time 2:
13711 overlay=x='if(gte(t,2), -w+(t-2)*20, NAN)':y=0
13715 Compose output by putting two input videos side to side:
13717 ffmpeg -i left.avi -i right.avi -filter_complex "
13718 nullsrc=size=200x100 [background];
13719 [0:v] setpts=PTS-STARTPTS, scale=100x100 [left];
13720 [1:v] setpts=PTS-STARTPTS, scale=100x100 [right];
13721 [background][left] overlay=shortest=1 [background+left];
13722 [background+left][right] overlay=shortest=1:x=100 [left+right]
13727 Mask 10-20 seconds of a video by applying the delogo filter to a section
13729 ffmpeg -i test.avi -codec:v:0 wmv2 -ar 11025 -b:v 9000k
13730 -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]'
13735 Chain several overlays in cascade:
13737 nullsrc=s=200x200 [bg];
13738 testsrc=s=100x100, split=4 [in0][in1][in2][in3];
13739 [in0] lutrgb=r=0, [bg] overlay=0:0 [mid0];
13740 [in1] lutrgb=g=0, [mid0] overlay=100:0 [mid1];
13741 [in2] lutrgb=b=0, [mid1] overlay=0:100 [mid2];
13742 [in3] null, [mid2] overlay=100:100 [out0]
13749 Apply Overcomplete Wavelet denoiser.
13751 The filter accepts the following options:
13757 Larger depth values will denoise lower frequency components more, but
13758 slow down filtering.
13760 Must be an int in the range 8-16, default is @code{8}.
13762 @item luma_strength, ls
13765 Must be a double value in the range 0-1000, default is @code{1.0}.
13767 @item chroma_strength, cs
13768 Set chroma strength.
13770 Must be a double value in the range 0-1000, default is @code{1.0}.
13776 Add paddings to the input image, and place the original input at the
13777 provided @var{x}, @var{y} coordinates.
13779 It accepts the following parameters:
13784 Specify an expression for the size of the output image with the
13785 paddings added. If the value for @var{width} or @var{height} is 0, the
13786 corresponding input size is used for the output.
13788 The @var{width} expression can reference the value set by the
13789 @var{height} expression, and vice versa.
13791 The default value of @var{width} and @var{height} is 0.
13795 Specify the offsets to place the input image at within the padded area,
13796 with respect to the top/left border of the output image.
13798 The @var{x} expression can reference the value set by the @var{y}
13799 expression, and vice versa.
13801 The default value of @var{x} and @var{y} is 0.
13803 If @var{x} or @var{y} evaluate to a negative number, they'll be changed
13804 so the input image is centered on the padded area.
13807 Specify the color of the padded area. For the syntax of this option,
13808 check the @ref{color syntax,,"Color" section in the ffmpeg-utils
13809 manual,ffmpeg-utils}.
13811 The default value of @var{color} is "black".
13814 Specify when to evaluate @var{width}, @var{height}, @var{x} and @var{y} expression.
13816 It accepts the following values:
13820 Only evaluate expressions once during the filter initialization or when
13821 a command is processed.
13824 Evaluate expressions for each incoming frame.
13828 Default value is @samp{init}.
13831 Pad to aspect instead to a resolution.
13835 The value for the @var{width}, @var{height}, @var{x}, and @var{y}
13836 options are expressions containing the following constants:
13841 The input video width and height.
13845 These are the same as @var{in_w} and @var{in_h}.
13849 The output width and height (the size of the padded area), as
13850 specified by the @var{width} and @var{height} expressions.
13854 These are the same as @var{out_w} and @var{out_h}.
13858 The x and y offsets as specified by the @var{x} and @var{y}
13859 expressions, or NAN if not yet specified.
13862 same as @var{iw} / @var{ih}
13865 input sample aspect ratio
13868 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
13872 The horizontal and vertical chroma subsample values. For example for the
13873 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
13876 @subsection Examples
13880 Add paddings with the color "violet" to the input video. The output video
13881 size is 640x480, and the top-left corner of the input video is placed at
13884 pad=640:480:0:40:violet
13887 The example above is equivalent to the following command:
13889 pad=width=640:height=480:x=0:y=40:color=violet
13893 Pad the input to get an output with dimensions increased by 3/2,
13894 and put the input video at the center of the padded area:
13896 pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2"
13900 Pad the input to get a squared output with size equal to the maximum
13901 value between the input width and height, and put the input video at
13902 the center of the padded area:
13904 pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2"
13908 Pad the input to get a final w/h ratio of 16:9:
13910 pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2"
13914 In case of anamorphic video, in order to set the output display aspect
13915 correctly, it is necessary to use @var{sar} in the expression,
13916 according to the relation:
13918 (ih * X / ih) * sar = output_dar
13919 X = output_dar / sar
13922 Thus the previous example needs to be modified to:
13924 pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2"
13928 Double the output size and put the input video in the bottom-right
13929 corner of the output padded area:
13931 pad="2*iw:2*ih:ow-iw:oh-ih"
13935 @anchor{palettegen}
13936 @section palettegen
13938 Generate one palette for a whole video stream.
13940 It accepts the following options:
13944 Set the maximum number of colors to quantize in the palette.
13945 Note: the palette will still contain 256 colors; the unused palette entries
13948 @item reserve_transparent
13949 Create a palette of 255 colors maximum and reserve the last one for
13950 transparency. Reserving the transparency color is useful for GIF optimization.
13951 If not set, the maximum of colors in the palette will be 256. You probably want
13952 to disable this option for a standalone image.
13955 @item transparency_color
13956 Set the color that will be used as background for transparency.
13959 Set statistics mode.
13961 It accepts the following values:
13964 Compute full frame histograms.
13966 Compute histograms only for the part that differs from previous frame. This
13967 might be relevant to give more importance to the moving part of your input if
13968 the background is static.
13970 Compute new histogram for each frame.
13973 Default value is @var{full}.
13976 The filter also exports the frame metadata @code{lavfi.color_quant_ratio}
13977 (@code{nb_color_in / nb_color_out}) which you can use to evaluate the degree of
13978 color quantization of the palette. This information is also visible at
13979 @var{info} logging level.
13981 @subsection Examples
13985 Generate a representative palette of a given video using @command{ffmpeg}:
13987 ffmpeg -i input.mkv -vf palettegen palette.png
13991 @section paletteuse
13993 Use a palette to downsample an input video stream.
13995 The filter takes two inputs: one video stream and a palette. The palette must
13996 be a 256 pixels image.
13998 It accepts the following options:
14002 Select dithering mode. Available algorithms are:
14005 Ordered 8x8 bayer dithering (deterministic)
14007 Dithering as defined by Paul Heckbert in 1982 (simple error diffusion).
14008 Note: this dithering is sometimes considered "wrong" and is included as a
14010 @item floyd_steinberg
14011 Floyd and Steingberg dithering (error diffusion)
14013 Frankie Sierra dithering v2 (error diffusion)
14015 Frankie Sierra dithering v2 "Lite" (error diffusion)
14018 Default is @var{sierra2_4a}.
14021 When @var{bayer} dithering is selected, this option defines the scale of the
14022 pattern (how much the crosshatch pattern is visible). A low value means more
14023 visible pattern for less banding, and higher value means less visible pattern
14024 at the cost of more banding.
14026 The option must be an integer value in the range [0,5]. Default is @var{2}.
14029 If set, define the zone to process
14033 Only the changing rectangle will be reprocessed. This is similar to GIF
14034 cropping/offsetting compression mechanism. This option can be useful for speed
14035 if only a part of the image is changing, and has use cases such as limiting the
14036 scope of the error diffusal @option{dither} to the rectangle that bounds the
14037 moving scene (it leads to more deterministic output if the scene doesn't change
14038 much, and as a result less moving noise and better GIF compression).
14041 Default is @var{none}.
14044 Take new palette for each output frame.
14046 @item alpha_threshold
14047 Sets the alpha threshold for transparency. Alpha values above this threshold
14048 will be treated as completely opaque, and values below this threshold will be
14049 treated as completely transparent.
14051 The option must be an integer value in the range [0,255]. Default is @var{128}.
14054 @subsection Examples
14058 Use a palette (generated for example with @ref{palettegen}) to encode a GIF
14059 using @command{ffmpeg}:
14061 ffmpeg -i input.mkv -i palette.png -lavfi paletteuse output.gif
14065 @section perspective
14067 Correct perspective of video not recorded perpendicular to the screen.
14069 A description of the accepted parameters follows.
14080 Set coordinates expression for top left, top right, bottom left and bottom right corners.
14081 Default values are @code{0:0:W:0:0:H:W:H} with which perspective will remain unchanged.
14082 If the @code{sense} option is set to @code{source}, then the specified points will be sent
14083 to the corners of the destination. If the @code{sense} option is set to @code{destination},
14084 then the corners of the source will be sent to the specified coordinates.
14086 The expressions can use the following variables:
14091 the width and height of video frame.
14095 Output frame count.
14098 @item interpolation
14099 Set interpolation for perspective correction.
14101 It accepts the following values:
14107 Default value is @samp{linear}.
14110 Set interpretation of coordinate options.
14112 It accepts the following values:
14116 Send point in the source specified by the given coordinates to
14117 the corners of the destination.
14119 @item 1, destination
14121 Send the corners of the source to the point in the destination specified
14122 by the given coordinates.
14124 Default value is @samp{source}.
14128 Set when the expressions for coordinates @option{x0,y0,...x3,y3} are evaluated.
14130 It accepts the following values:
14133 only evaluate expressions once during the filter initialization or
14134 when a command is processed
14137 evaluate expressions for each incoming frame
14140 Default value is @samp{init}.
14145 Delay interlaced video by one field time so that the field order changes.
14147 The intended use is to fix PAL movies that have been captured with the
14148 opposite field order to the film-to-video transfer.
14150 A description of the accepted parameters follows.
14156 It accepts the following values:
14159 Capture field order top-first, transfer bottom-first.
14160 Filter will delay the bottom field.
14163 Capture field order bottom-first, transfer top-first.
14164 Filter will delay the top field.
14167 Capture and transfer with the same field order. This mode only exists
14168 for the documentation of the other options to refer to, but if you
14169 actually select it, the filter will faithfully do nothing.
14172 Capture field order determined automatically by field flags, transfer
14174 Filter selects among @samp{t} and @samp{b} modes on a frame by frame
14175 basis using field flags. If no field information is available,
14176 then this works just like @samp{u}.
14179 Capture unknown or varying, transfer opposite.
14180 Filter selects among @samp{t} and @samp{b} on a frame by frame basis by
14181 analyzing the images and selecting the alternative that produces best
14182 match between the fields.
14185 Capture top-first, transfer unknown or varying.
14186 Filter selects among @samp{t} and @samp{p} using image analysis.
14189 Capture bottom-first, transfer unknown or varying.
14190 Filter selects among @samp{b} and @samp{p} using image analysis.
14193 Capture determined by field flags, transfer unknown or varying.
14194 Filter selects among @samp{t}, @samp{b} and @samp{p} using field flags and
14195 image analysis. If no field information is available, then this works just
14196 like @samp{U}. This is the default mode.
14199 Both capture and transfer unknown or varying.
14200 Filter selects among @samp{t}, @samp{b} and @samp{p} using image analysis only.
14204 @section photosensitivity
14205 Reduce various flashes in video, so to help users with epilepsy.
14207 It accepts the following options:
14210 Set how many frames to use when filtering. Default is 30.
14213 Set detection threshold factor. Default is 1.
14217 Set how many pixels to skip when sampling frames. Defalt is 1.
14218 Allowed range is from 1 to 1024.
14221 Leave frames unchanged. Default is disabled.
14224 @section pixdesctest
14226 Pixel format descriptor test filter, mainly useful for internal
14227 testing. The output video should be equal to the input video.
14231 format=monow, pixdesctest
14234 can be used to test the monowhite pixel format descriptor definition.
14238 Display sample values of color channels. Mainly useful for checking color
14239 and levels. Minimum supported resolution is 640x480.
14241 The filters accept the following options:
14245 Set scope X position, relative offset on X axis.
14248 Set scope Y position, relative offset on Y axis.
14257 Set window opacity. This window also holds statistics about pixel area.
14260 Set window X position, relative offset on X axis.
14263 Set window Y position, relative offset on Y axis.
14268 Enable the specified chain of postprocessing subfilters using libpostproc. This
14269 library should be automatically selected with a GPL build (@code{--enable-gpl}).
14270 Subfilters must be separated by '/' and can be disabled by prepending a '-'.
14271 Each subfilter and some options have a short and a long name that can be used
14272 interchangeably, i.e. dr/dering are the same.
14274 The filters accept the following options:
14278 Set postprocessing subfilters string.
14281 All subfilters share common options to determine their scope:
14285 Honor the quality commands for this subfilter.
14288 Do chrominance filtering, too (default).
14291 Do luminance filtering only (no chrominance).
14294 Do chrominance filtering only (no luminance).
14297 These options can be appended after the subfilter name, separated by a '|'.
14299 Available subfilters are:
14302 @item hb/hdeblock[|difference[|flatness]]
14303 Horizontal deblocking filter
14306 Difference factor where higher values mean more deblocking (default: @code{32}).
14308 Flatness threshold where lower values mean more deblocking (default: @code{39}).
14311 @item vb/vdeblock[|difference[|flatness]]
14312 Vertical deblocking filter
14315 Difference factor where higher values mean more deblocking (default: @code{32}).
14317 Flatness threshold where lower values mean more deblocking (default: @code{39}).
14320 @item ha/hadeblock[|difference[|flatness]]
14321 Accurate horizontal deblocking filter
14324 Difference factor where higher values mean more deblocking (default: @code{32}).
14326 Flatness threshold where lower values mean more deblocking (default: @code{39}).
14329 @item va/vadeblock[|difference[|flatness]]
14330 Accurate vertical deblocking filter
14333 Difference factor where higher values mean more deblocking (default: @code{32}).
14335 Flatness threshold where lower values mean more deblocking (default: @code{39}).
14339 The horizontal and vertical deblocking filters share the difference and
14340 flatness values so you cannot set different horizontal and vertical
14344 @item h1/x1hdeblock
14345 Experimental horizontal deblocking filter
14347 @item v1/x1vdeblock
14348 Experimental vertical deblocking filter
14353 @item tn/tmpnoise[|threshold1[|threshold2[|threshold3]]], temporal noise reducer
14356 larger -> stronger filtering
14358 larger -> stronger filtering
14360 larger -> stronger filtering
14363 @item al/autolevels[:f/fullyrange], automatic brightness / contrast correction
14366 Stretch luminance to @code{0-255}.
14369 @item lb/linblenddeint
14370 Linear blend deinterlacing filter that deinterlaces the given block by
14371 filtering all lines with a @code{(1 2 1)} filter.
14373 @item li/linipoldeint
14374 Linear interpolating deinterlacing filter that deinterlaces the given block by
14375 linearly interpolating every second line.
14377 @item ci/cubicipoldeint
14378 Cubic interpolating deinterlacing filter deinterlaces the given block by
14379 cubically interpolating every second line.
14381 @item md/mediandeint
14382 Median deinterlacing filter that deinterlaces the given block by applying a
14383 median filter to every second line.
14385 @item fd/ffmpegdeint
14386 FFmpeg deinterlacing filter that deinterlaces the given block by filtering every
14387 second line with a @code{(-1 4 2 4 -1)} filter.
14390 Vertically applied FIR lowpass deinterlacing filter that deinterlaces the given
14391 block by filtering all lines with a @code{(-1 2 6 2 -1)} filter.
14393 @item fq/forceQuant[|quantizer]
14394 Overrides the quantizer table from the input with the constant quantizer you
14402 Default pp filter combination (@code{hb|a,vb|a,dr|a})
14405 Fast pp filter combination (@code{h1|a,v1|a,dr|a})
14408 High quality pp filter combination (@code{ha|a|128|7,va|a,dr|a})
14411 @subsection Examples
14415 Apply horizontal and vertical deblocking, deringing and automatic
14416 brightness/contrast:
14422 Apply default filters without brightness/contrast correction:
14428 Apply default filters and temporal denoiser:
14430 pp=default/tmpnoise|1|2|3
14434 Apply deblocking on luminance only, and switch vertical deblocking on or off
14435 automatically depending on available CPU time:
14442 Apply Postprocessing filter 7. It is variant of the @ref{spp} filter,
14443 similar to spp = 6 with 7 point DCT, where only the center sample is
14446 The filter accepts the following options:
14450 Force a constant quantization parameter. It accepts an integer in range
14451 0 to 63. If not set, the filter will use the QP from the video stream
14455 Set thresholding mode. Available modes are:
14459 Set hard thresholding.
14461 Set soft thresholding (better de-ringing effect, but likely blurrier).
14463 Set medium thresholding (good results, default).
14467 @section premultiply
14468 Apply alpha premultiply effect to input video stream using first plane
14469 of second stream as alpha.
14471 Both streams must have same dimensions and same pixel format.
14473 The filter accepts the following option:
14477 Set which planes will be processed, unprocessed planes will be copied.
14478 By default value 0xf, all planes will be processed.
14481 Do not require 2nd input for processing, instead use alpha plane from input stream.
14485 Apply prewitt operator to input video stream.
14487 The filter accepts the following option:
14491 Set which planes will be processed, unprocessed planes will be copied.
14492 By default value 0xf, all planes will be processed.
14495 Set value which will be multiplied with filtered result.
14498 Set value which will be added to filtered result.
14501 @anchor{program_opencl}
14502 @section program_opencl
14504 Filter video using an OpenCL program.
14509 OpenCL program source file.
14512 Kernel name in program.
14515 Number of inputs to the filter. Defaults to 1.
14518 Size of output frames. Defaults to the same as the first input.
14522 The program source file must contain a kernel function with the given name,
14523 which will be run once for each plane of the output. Each run on a plane
14524 gets enqueued as a separate 2D global NDRange with one work-item for each
14525 pixel to be generated. The global ID offset for each work-item is therefore
14526 the coordinates of a pixel in the destination image.
14528 The kernel function needs to take the following arguments:
14531 Destination image, @var{__write_only image2d_t}.
14533 This image will become the output; the kernel should write all of it.
14535 Frame index, @var{unsigned int}.
14537 This is a counter starting from zero and increasing by one for each frame.
14539 Source images, @var{__read_only image2d_t}.
14541 These are the most recent images on each input. The kernel may read from
14542 them to generate the output, but they can't be written to.
14549 Copy the input to the output (output must be the same size as the input).
14551 __kernel void copy(__write_only image2d_t destination,
14552 unsigned int index,
14553 __read_only image2d_t source)
14555 const sampler_t sampler = CLK_NORMALIZED_COORDS_FALSE;
14557 int2 location = (int2)(get_global_id(0), get_global_id(1));
14559 float4 value = read_imagef(source, sampler, location);
14561 write_imagef(destination, location, value);
14566 Apply a simple transformation, rotating the input by an amount increasing
14567 with the index counter. Pixel values are linearly interpolated by the
14568 sampler, and the output need not have the same dimensions as the input.
14570 __kernel void rotate_image(__write_only image2d_t dst,
14571 unsigned int index,
14572 __read_only image2d_t src)
14574 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
14575 CLK_FILTER_LINEAR);
14577 float angle = (float)index / 100.0f;
14579 float2 dst_dim = convert_float2(get_image_dim(dst));
14580 float2 src_dim = convert_float2(get_image_dim(src));
14582 float2 dst_cen = dst_dim / 2.0f;
14583 float2 src_cen = src_dim / 2.0f;
14585 int2 dst_loc = (int2)(get_global_id(0), get_global_id(1));
14587 float2 dst_pos = convert_float2(dst_loc) - dst_cen;
14589 cos(angle) * dst_pos.x - sin(angle) * dst_pos.y,
14590 sin(angle) * dst_pos.x + cos(angle) * dst_pos.y
14592 src_pos = src_pos * src_dim / dst_dim;
14594 float2 src_loc = src_pos + src_cen;
14596 if (src_loc.x < 0.0f || src_loc.y < 0.0f ||
14597 src_loc.x > src_dim.x || src_loc.y > src_dim.y)
14598 write_imagef(dst, dst_loc, 0.5f);
14600 write_imagef(dst, dst_loc, read_imagef(src, sampler, src_loc));
14605 Blend two inputs together, with the amount of each input used varying
14606 with the index counter.
14608 __kernel void blend_images(__write_only image2d_t dst,
14609 unsigned int index,
14610 __read_only image2d_t src1,
14611 __read_only image2d_t src2)
14613 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
14614 CLK_FILTER_LINEAR);
14616 float blend = (cos((float)index / 50.0f) + 1.0f) / 2.0f;
14618 int2 dst_loc = (int2)(get_global_id(0), get_global_id(1));
14619 int2 src1_loc = dst_loc * get_image_dim(src1) / get_image_dim(dst);
14620 int2 src2_loc = dst_loc * get_image_dim(src2) / get_image_dim(dst);
14622 float4 val1 = read_imagef(src1, sampler, src1_loc);
14623 float4 val2 = read_imagef(src2, sampler, src2_loc);
14625 write_imagef(dst, dst_loc, val1 * blend + val2 * (1.0f - blend));
14631 @section pseudocolor
14633 Alter frame colors in video with pseudocolors.
14635 This filter accepts the following options:
14639 set pixel first component expression
14642 set pixel second component expression
14645 set pixel third component expression
14648 set pixel fourth component expression, corresponds to the alpha component
14651 set component to use as base for altering colors
14654 Each of them specifies the expression to use for computing the lookup table for
14655 the corresponding pixel component values.
14657 The expressions can contain the following constants and functions:
14662 The input width and height.
14665 The input value for the pixel component.
14667 @item ymin, umin, vmin, amin
14668 The minimum allowed component value.
14670 @item ymax, umax, vmax, amax
14671 The maximum allowed component value.
14674 All expressions default to "val".
14676 @subsection Examples
14680 Change too high luma values to gradient:
14682 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'"
14688 Obtain the average, maximum and minimum PSNR (Peak Signal to Noise
14689 Ratio) between two input videos.
14691 This filter takes in input two input videos, the first input is
14692 considered the "main" source and is passed unchanged to the
14693 output. The second input is used as a "reference" video for computing
14696 Both video inputs must have the same resolution and pixel format for
14697 this filter to work correctly. Also it assumes that both inputs
14698 have the same number of frames, which are compared one by one.
14700 The obtained average PSNR is printed through the logging system.
14702 The filter stores the accumulated MSE (mean squared error) of each
14703 frame, and at the end of the processing it is averaged across all frames
14704 equally, and the following formula is applied to obtain the PSNR:
14707 PSNR = 10*log10(MAX^2/MSE)
14710 Where MAX is the average of the maximum values of each component of the
14713 The description of the accepted parameters follows.
14716 @item stats_file, f
14717 If specified the filter will use the named file to save the PSNR of
14718 each individual frame. When filename equals "-" the data is sent to
14721 @item stats_version
14722 Specifies which version of the stats file format to use. Details of
14723 each format are written below.
14724 Default value is 1.
14726 @item stats_add_max
14727 Determines whether the max value is output to the stats log.
14728 Default value is 0.
14729 Requires stats_version >= 2. If this is set and stats_version < 2,
14730 the filter will return an error.
14733 This filter also supports the @ref{framesync} options.
14735 The file printed if @var{stats_file} is selected, contains a sequence of
14736 key/value pairs of the form @var{key}:@var{value} for each compared
14739 If a @var{stats_version} greater than 1 is specified, a header line precedes
14740 the list of per-frame-pair stats, with key value pairs following the frame
14741 format with the following parameters:
14744 @item psnr_log_version
14745 The version of the log file format. Will match @var{stats_version}.
14748 A comma separated list of the per-frame-pair parameters included in
14752 A description of each shown per-frame-pair parameter follows:
14756 sequential number of the input frame, starting from 1
14759 Mean Square Error pixel-by-pixel average difference of the compared
14760 frames, averaged over all the image components.
14762 @item mse_y, mse_u, mse_v, mse_r, mse_g, mse_b, mse_a
14763 Mean Square Error pixel-by-pixel average difference of the compared
14764 frames for the component specified by the suffix.
14766 @item psnr_y, psnr_u, psnr_v, psnr_r, psnr_g, psnr_b, psnr_a
14767 Peak Signal to Noise ratio of the compared frames for the component
14768 specified by the suffix.
14770 @item max_avg, max_y, max_u, max_v
14771 Maximum allowed value for each channel, and average over all
14777 movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
14778 [main][ref] psnr="stats_file=stats.log" [out]
14781 On this example the input file being processed is compared with the
14782 reference file @file{ref_movie.mpg}. The PSNR of each individual frame
14783 is stored in @file{stats.log}.
14788 Pulldown reversal (inverse telecine) filter, capable of handling mixed
14789 hard-telecine, 24000/1001 fps progressive, and 30000/1001 fps progressive
14792 The pullup filter is designed to take advantage of future context in making
14793 its decisions. This filter is stateless in the sense that it does not lock
14794 onto a pattern to follow, but it instead looks forward to the following
14795 fields in order to identify matches and rebuild progressive frames.
14797 To produce content with an even framerate, insert the fps filter after
14798 pullup, use @code{fps=24000/1001} if the input frame rate is 29.97fps,
14799 @code{fps=24} for 30fps and the (rare) telecined 25fps input.
14801 The filter accepts the following options:
14808 These options set the amount of "junk" to ignore at the left, right, top, and
14809 bottom of the image, respectively. Left and right are in units of 8 pixels,
14810 while top and bottom are in units of 2 lines.
14811 The default is 8 pixels on each side.
14814 Set the strict breaks. Setting this option to 1 will reduce the chances of
14815 filter generating an occasional mismatched frame, but it may also cause an
14816 excessive number of frames to be dropped during high motion sequences.
14817 Conversely, setting it to -1 will make filter match fields more easily.
14818 This may help processing of video where there is slight blurring between
14819 the fields, but may also cause there to be interlaced frames in the output.
14820 Default value is @code{0}.
14823 Set the metric plane to use. It accepts the following values:
14829 Use chroma blue plane.
14832 Use chroma red plane.
14835 This option may be set to use chroma plane instead of the default luma plane
14836 for doing filter's computations. This may improve accuracy on very clean
14837 source material, but more likely will decrease accuracy, especially if there
14838 is chroma noise (rainbow effect) or any grayscale video.
14839 The main purpose of setting @option{mp} to a chroma plane is to reduce CPU
14840 load and make pullup usable in realtime on slow machines.
14843 For best results (without duplicated frames in the output file) it is
14844 necessary to change the output frame rate. For example, to inverse
14845 telecine NTSC input:
14847 ffmpeg -i input -vf pullup -r 24000/1001 ...
14852 Change video quantization parameters (QP).
14854 The filter accepts the following option:
14858 Set expression for quantization parameter.
14861 The expression is evaluated through the eval API and can contain, among others,
14862 the following constants:
14866 1 if index is not 129, 0 otherwise.
14869 Sequential index starting from -129 to 128.
14872 @subsection Examples
14876 Some equation like:
14884 Flush video frames from internal cache of frames into a random order.
14885 No frame is discarded.
14886 Inspired by @ref{frei0r} nervous filter.
14890 Set size in number of frames of internal cache, in range from @code{2} to
14891 @code{512}. Default is @code{30}.
14894 Set seed for random number generator, must be an integer included between
14895 @code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to
14896 less than @code{0}, the filter will try to use a good random seed on a
14900 @section readeia608
14902 Read closed captioning (EIA-608) information from the top lines of a video frame.
14904 This filter adds frame metadata for @code{lavfi.readeia608.X.cc} and
14905 @code{lavfi.readeia608.X.line}, where @code{X} is the number of the identified line
14906 with EIA-608 data (starting from 0). A description of each metadata value follows:
14909 @item lavfi.readeia608.X.cc
14910 The two bytes stored as EIA-608 data (printed in hexadecimal).
14912 @item lavfi.readeia608.X.line
14913 The number of the line on which the EIA-608 data was identified and read.
14916 This filter accepts the following options:
14920 Set the line to start scanning for EIA-608 data. Default is @code{0}.
14923 Set the line to end scanning for EIA-608 data. Default is @code{29}.
14926 Set minimal acceptable amplitude change for sync codes detection.
14927 Default is @code{0.2}. Allowed range is @code{[0.001 - 1]}.
14930 Set the ratio of width reserved for sync code detection.
14931 Default is @code{0.27}. Allowed range is @code{[0.01 - 0.7]}.
14934 Set the max peaks height difference for sync code detection.
14935 Default is @code{0.1}. Allowed range is @code{[0.0 - 0.5]}.
14938 Set max peaks period difference for sync code detection.
14939 Default is @code{0.1}. Allowed range is @code{[0.0 - 0.5]}.
14942 Set the first two max start code bits differences.
14943 Default is @code{0.02}. Allowed range is @code{[0.0 - 0.5]}.
14946 Set the minimum ratio of bits height compared to 3rd start code bit.
14947 Default is @code{0.75}. Allowed range is @code{[0.01 - 1]}.
14950 Set the white color threshold. Default is @code{0.35}. Allowed range is @code{[0.1 - 1]}.
14953 Set the black color threshold. Default is @code{0.15}. Allowed range is @code{[0.0 - 0.5]}.
14956 Enable checking the parity bit. In the event of a parity error, the filter will output
14957 @code{0x00} for that character. Default is false.
14960 Lowpass lines prior to further processing. Default is disabled.
14963 @subsection Examples
14967 Output a csv with presentation time and the first two lines of identified EIA-608 captioning data.
14969 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
14975 Read vertical interval timecode (VITC) information from the top lines of a
14978 The filter adds frame metadata key @code{lavfi.readvitc.tc_str} with the
14979 timecode value, if a valid timecode has been detected. Further metadata key
14980 @code{lavfi.readvitc.found} is set to 0/1 depending on whether
14981 timecode data has been found or not.
14983 This filter accepts the following options:
14987 Set the maximum number of lines to scan for VITC data. If the value is set to
14988 @code{-1} the full video frame is scanned. Default is @code{45}.
14991 Set the luma threshold for black. Accepts float numbers in the range [0.0,1.0],
14992 default value is @code{0.2}. The value must be equal or less than @code{thr_w}.
14995 Set the luma threshold for white. Accepts float numbers in the range [0.0,1.0],
14996 default value is @code{0.6}. The value must be equal or greater than @code{thr_b}.
14999 @subsection Examples
15003 Detect and draw VITC data onto the video frame; if no valid VITC is detected,
15004 draw @code{--:--:--:--} as a placeholder:
15006 ffmpeg -i input.avi -filter:v 'readvitc,drawtext=fontfile=FreeMono.ttf:text=%@{metadata\\:lavfi.readvitc.tc_str\\:--\\\\\\:--\\\\\\:--\\\\\\:--@}:x=(w-tw)/2:y=400-ascent'
15012 Remap pixels using 2nd: Xmap and 3rd: Ymap input video stream.
15014 Destination pixel at position (X, Y) will be picked from source (x, y) position
15015 where x = Xmap(X, Y) and y = Ymap(X, Y). If mapping values are out of range, zero
15016 value for pixel will be used for destination pixel.
15018 Xmap and Ymap input video streams must be of same dimensions. Output video stream
15019 will have Xmap/Ymap video stream dimensions.
15020 Xmap and Ymap input video streams are 16bit depth, single channel.
15024 Specify pixel format of output from this filter. Can be @code{color} or @code{gray}.
15025 Default is @code{color}.
15028 @section removegrain
15030 The removegrain filter is a spatial denoiser for progressive video.
15034 Set mode for the first plane.
15037 Set mode for the second plane.
15040 Set mode for the third plane.
15043 Set mode for the fourth plane.
15046 Range of mode is from 0 to 24. Description of each mode follows:
15050 Leave input plane unchanged. Default.
15053 Clips the pixel with the minimum and maximum of the 8 neighbour pixels.
15056 Clips the pixel with the second minimum and maximum of the 8 neighbour pixels.
15059 Clips the pixel with the third minimum and maximum of the 8 neighbour pixels.
15062 Clips the pixel with the fourth minimum and maximum of the 8 neighbour pixels.
15063 This is equivalent to a median filter.
15066 Line-sensitive clipping giving the minimal change.
15069 Line-sensitive clipping, intermediate.
15072 Line-sensitive clipping, intermediate.
15075 Line-sensitive clipping, intermediate.
15078 Line-sensitive clipping on a line where the neighbours pixels are the closest.
15081 Replaces the target pixel with the closest neighbour.
15084 [1 2 1] horizontal and vertical kernel blur.
15090 Bob mode, interpolates top field from the line where the neighbours
15091 pixels are the closest.
15094 Bob mode, interpolates bottom field from the line where the neighbours
15095 pixels are the closest.
15098 Bob mode, interpolates top field. Same as 13 but with a more complicated
15099 interpolation formula.
15102 Bob mode, interpolates bottom field. Same as 14 but with a more complicated
15103 interpolation formula.
15106 Clips the pixel with the minimum and maximum of respectively the maximum and
15107 minimum of each pair of opposite neighbour pixels.
15110 Line-sensitive clipping using opposite neighbours whose greatest distance from
15111 the current pixel is minimal.
15114 Replaces the pixel with the average of its 8 neighbours.
15117 Averages the 9 pixels ([1 1 1] horizontal and vertical blur).
15120 Clips pixels using the averages of opposite neighbour.
15123 Same as mode 21 but simpler and faster.
15126 Small edge and halo removal, but reputed useless.
15132 @section removelogo
15134 Suppress a TV station logo, using an image file to determine which
15135 pixels comprise the logo. It works by filling in the pixels that
15136 comprise the logo with neighboring pixels.
15138 The filter accepts the following options:
15142 Set the filter bitmap file, which can be any image format supported by
15143 libavformat. The width and height of the image file must match those of the
15144 video stream being processed.
15147 Pixels in the provided bitmap image with a value of zero are not
15148 considered part of the logo, non-zero pixels are considered part of
15149 the logo. If you use white (255) for the logo and black (0) for the
15150 rest, you will be safe. For making the filter bitmap, it is
15151 recommended to take a screen capture of a black frame with the logo
15152 visible, and then using a threshold filter followed by the erode
15153 filter once or twice.
15155 If needed, little splotches can be fixed manually. Remember that if
15156 logo pixels are not covered, the filter quality will be much
15157 reduced. Marking too many pixels as part of the logo does not hurt as
15158 much, but it will increase the amount of blurring needed to cover over
15159 the image and will destroy more information than necessary, and extra
15160 pixels will slow things down on a large logo.
15162 @section repeatfields
15164 This filter uses the repeat_field flag from the Video ES headers and hard repeats
15165 fields based on its value.
15169 Reverse a video clip.
15171 Warning: This filter requires memory to buffer the entire clip, so trimming
15174 @subsection Examples
15178 Take the first 5 seconds of a clip, and reverse it.
15185 Shift R/G/B/A pixels horizontally and/or vertically.
15187 The filter accepts the following options:
15190 Set amount to shift red horizontally.
15192 Set amount to shift red vertically.
15194 Set amount to shift green horizontally.
15196 Set amount to shift green vertically.
15198 Set amount to shift blue horizontally.
15200 Set amount to shift blue vertically.
15202 Set amount to shift alpha horizontally.
15204 Set amount to shift alpha vertically.
15206 Set edge mode, can be @var{smear}, default, or @var{warp}.
15210 Apply roberts cross operator to input video stream.
15212 The filter accepts the following option:
15216 Set which planes will be processed, unprocessed planes will be copied.
15217 By default value 0xf, all planes will be processed.
15220 Set value which will be multiplied with filtered result.
15223 Set value which will be added to filtered result.
15228 Rotate video by an arbitrary angle expressed in radians.
15230 The filter accepts the following options:
15232 A description of the optional parameters follows.
15235 Set an expression for the angle by which to rotate the input video
15236 clockwise, expressed as a number of radians. A negative value will
15237 result in a counter-clockwise rotation. By default it is set to "0".
15239 This expression is evaluated for each frame.
15242 Set the output width expression, default value is "iw".
15243 This expression is evaluated just once during configuration.
15246 Set the output height expression, default value is "ih".
15247 This expression is evaluated just once during configuration.
15250 Enable bilinear interpolation if set to 1, a value of 0 disables
15251 it. Default value is 1.
15254 Set the color used to fill the output area not covered by the rotated
15255 image. For the general syntax of this option, check the
15256 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
15257 If the special value "none" is selected then no
15258 background is printed (useful for example if the background is never shown).
15260 Default value is "black".
15263 The expressions for the angle and the output size can contain the
15264 following constants and functions:
15268 sequential number of the input frame, starting from 0. It is always NAN
15269 before the first frame is filtered.
15272 time in seconds of the input frame, it is set to 0 when the filter is
15273 configured. It is always NAN before the first frame is filtered.
15277 horizontal and vertical chroma subsample values. For example for the
15278 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
15282 the input video width and height
15286 the output width and height, that is the size of the padded area as
15287 specified by the @var{width} and @var{height} expressions
15291 the minimal width/height required for completely containing the input
15292 video rotated by @var{a} radians.
15294 These are only available when computing the @option{out_w} and
15295 @option{out_h} expressions.
15298 @subsection Examples
15302 Rotate the input by PI/6 radians clockwise:
15308 Rotate the input by PI/6 radians counter-clockwise:
15314 Rotate the input by 45 degrees clockwise:
15320 Apply a constant rotation with period T, starting from an angle of PI/3:
15322 rotate=PI/3+2*PI*t/T
15326 Make the input video rotation oscillating with a period of T
15327 seconds and an amplitude of A radians:
15329 rotate=A*sin(2*PI/T*t)
15333 Rotate the video, output size is chosen so that the whole rotating
15334 input video is always completely contained in the output:
15336 rotate='2*PI*t:ow=hypot(iw,ih):oh=ow'
15340 Rotate the video, reduce the output size so that no background is ever
15343 rotate=2*PI*t:ow='min(iw,ih)/sqrt(2)':oh=ow:c=none
15347 @subsection Commands
15349 The filter supports the following commands:
15353 Set the angle expression.
15354 The command accepts the same syntax of the corresponding option.
15356 If the specified expression is not valid, it is kept at its current
15362 Apply Shape Adaptive Blur.
15364 The filter accepts the following options:
15367 @item luma_radius, lr
15368 Set luma blur filter strength, must be a value in range 0.1-4.0, default
15369 value is 1.0. A greater value will result in a more blurred image, and
15370 in slower processing.
15372 @item luma_pre_filter_radius, lpfr
15373 Set luma pre-filter radius, must be a value in the 0.1-2.0 range, default
15376 @item luma_strength, ls
15377 Set luma maximum difference between pixels to still be considered, must
15378 be a value in the 0.1-100.0 range, default value is 1.0.
15380 @item chroma_radius, cr
15381 Set chroma blur filter strength, must be a value in range -0.9-4.0. A
15382 greater value will result in a more blurred image, and in slower
15385 @item chroma_pre_filter_radius, cpfr
15386 Set chroma pre-filter radius, must be a value in the -0.9-2.0 range.
15388 @item chroma_strength, cs
15389 Set chroma maximum difference between pixels to still be considered,
15390 must be a value in the -0.9-100.0 range.
15393 Each chroma option value, if not explicitly specified, is set to the
15394 corresponding luma option value.
15399 Scale (resize) the input video, using the libswscale library.
15401 The scale filter forces the output display aspect ratio to be the same
15402 of the input, by changing the output sample aspect ratio.
15404 If the input image format is different from the format requested by
15405 the next filter, the scale filter will convert the input to the
15408 @subsection Options
15409 The filter accepts the following options, or any of the options
15410 supported by the libswscale scaler.
15412 See @ref{scaler_options,,the ffmpeg-scaler manual,ffmpeg-scaler} for
15413 the complete list of scaler options.
15418 Set the output video dimension expression. Default value is the input
15421 If the @var{width} or @var{w} value is 0, the input width is used for
15422 the output. If the @var{height} or @var{h} value is 0, the input height
15423 is used for the output.
15425 If one and only one of the values is -n with n >= 1, the scale filter
15426 will use a value that maintains the aspect ratio of the input image,
15427 calculated from the other specified dimension. After that it will,
15428 however, make sure that the calculated dimension is divisible by n and
15429 adjust the value if necessary.
15431 If both values are -n with n >= 1, the behavior will be identical to
15432 both values being set to 0 as previously detailed.
15434 See below for the list of accepted constants for use in the dimension
15438 Specify when to evaluate @var{width} and @var{height} expression. It accepts the following values:
15442 Only evaluate expressions once during the filter initialization or when a command is processed.
15445 Evaluate expressions for each incoming frame.
15449 Default value is @samp{init}.
15453 Set the interlacing mode. It accepts the following values:
15457 Force interlaced aware scaling.
15460 Do not apply interlaced scaling.
15463 Select interlaced aware scaling depending on whether the source frames
15464 are flagged as interlaced or not.
15467 Default value is @samp{0}.
15470 Set libswscale scaling flags. See
15471 @ref{sws_flags,,the ffmpeg-scaler manual,ffmpeg-scaler} for the
15472 complete list of values. If not explicitly specified the filter applies
15476 @item param0, param1
15477 Set libswscale input parameters for scaling algorithms that need them. See
15478 @ref{sws_params,,the ffmpeg-scaler manual,ffmpeg-scaler} for the
15479 complete documentation. If not explicitly specified the filter applies
15485 Set the video size. For the syntax of this option, check the
15486 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
15488 @item in_color_matrix
15489 @item out_color_matrix
15490 Set in/output YCbCr color space type.
15492 This allows the autodetected value to be overridden as well as allows forcing
15493 a specific value used for the output and encoder.
15495 If not specified, the color space type depends on the pixel format.
15501 Choose automatically.
15504 Format conforming to International Telecommunication Union (ITU)
15505 Recommendation BT.709.
15508 Set color space conforming to the United States Federal Communications
15509 Commission (FCC) Code of Federal Regulations (CFR) Title 47 (2003) 73.682 (a).
15514 Set color space conforming to:
15518 ITU Radiocommunication Sector (ITU-R) Recommendation BT.601
15521 ITU-R Rec. BT.470-6 (1998) Systems B, B1, and G
15524 Society of Motion Picture and Television Engineers (SMPTE) ST 170:2004
15529 Set color space conforming to SMPTE ST 240:1999.
15532 Set color space conforming to ITU-R BT.2020 non-constant luminance system.
15537 Set in/output YCbCr sample range.
15539 This allows the autodetected value to be overridden as well as allows forcing
15540 a specific value used for the output and encoder. If not specified, the
15541 range depends on the pixel format. Possible values:
15545 Choose automatically.
15548 Set full range (0-255 in case of 8-bit luma).
15550 @item mpeg/limited/tv
15551 Set "MPEG" range (16-235 in case of 8-bit luma).
15554 @item force_original_aspect_ratio
15555 Enable decreasing or increasing output video width or height if necessary to
15556 keep the original aspect ratio. Possible values:
15560 Scale the video as specified and disable this feature.
15563 The output video dimensions will automatically be decreased if needed.
15566 The output video dimensions will automatically be increased if needed.
15570 One useful instance of this option is that when you know a specific device's
15571 maximum allowed resolution, you can use this to limit the output video to
15572 that, while retaining the aspect ratio. For example, device A allows
15573 1280x720 playback, and your video is 1920x800. Using this option (set it to
15574 decrease) and specifying 1280x720 to the command line makes the output
15577 Please note that this is a different thing than specifying -1 for @option{w}
15578 or @option{h}, you still need to specify the output resolution for this option
15581 @item force_divisible_by Ensures that the output resolution is divisible by the
15582 given integer when used together with @option{force_original_aspect_ratio}. This
15583 works similar to using -n in the @option{w} and @option{h} options.
15585 This option respects the value set for @option{force_original_aspect_ratio},
15586 increasing or decreasing the resolution accordingly. This may slightly modify
15587 the video's aspect ration.
15589 This can be handy, for example, if you want to have a video fit within a defined
15590 resolution using the @option{force_original_aspect_ratio} option but have
15591 encoder restrictions when it comes to width or height.
15595 The values of the @option{w} and @option{h} options are expressions
15596 containing the following constants:
15601 The input width and height
15605 These are the same as @var{in_w} and @var{in_h}.
15609 The output (scaled) width and height
15613 These are the same as @var{out_w} and @var{out_h}
15616 The same as @var{iw} / @var{ih}
15619 input sample aspect ratio
15622 The input display aspect ratio. Calculated from @code{(iw / ih) * sar}.
15626 horizontal and vertical input chroma subsample values. For example for the
15627 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
15631 horizontal and vertical output chroma subsample values. For example for the
15632 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
15635 @subsection Examples
15639 Scale the input video to a size of 200x100
15644 This is equivalent to:
15655 Specify a size abbreviation for the output size:
15660 which can also be written as:
15666 Scale the input to 2x:
15668 scale=w=2*iw:h=2*ih
15672 The above is the same as:
15674 scale=2*in_w:2*in_h
15678 Scale the input to 2x with forced interlaced scaling:
15680 scale=2*iw:2*ih:interl=1
15684 Scale the input to half size:
15686 scale=w=iw/2:h=ih/2
15690 Increase the width, and set the height to the same size:
15696 Seek Greek harmony:
15703 Increase the height, and set the width to 3/2 of the height:
15705 scale=w=3/2*oh:h=3/5*ih
15709 Increase the size, making the size a multiple of the chroma
15712 scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub"
15716 Increase the width to a maximum of 500 pixels,
15717 keeping the same aspect ratio as the input:
15719 scale=w='min(500\, iw*3/2):h=-1'
15723 Make pixels square by combining scale and setsar:
15725 scale='trunc(ih*dar):ih',setsar=1/1
15729 Make pixels square by combining scale and setsar,
15730 making sure the resulting resolution is even (required by some codecs):
15732 scale='trunc(ih*dar/2)*2:trunc(ih/2)*2',setsar=1/1
15736 @subsection Commands
15738 This filter supports the following commands:
15742 Set the output video dimension expression.
15743 The command accepts the same syntax of the corresponding option.
15745 If the specified expression is not valid, it is kept at its current
15751 Use the NVIDIA Performance Primitives (libnpp) to perform scaling and/or pixel
15752 format conversion on CUDA video frames. Setting the output width and height
15753 works in the same way as for the @var{scale} filter.
15755 The following additional options are accepted:
15758 The pixel format of the output CUDA frames. If set to the string "same" (the
15759 default), the input format will be kept. Note that automatic format negotiation
15760 and conversion is not yet supported for hardware frames
15763 The interpolation algorithm used for resizing. One of the following:
15770 @item cubic2p_bspline
15771 2-parameter cubic (B=1, C=0)
15773 @item cubic2p_catmullrom
15774 2-parameter cubic (B=0, C=1/2)
15776 @item cubic2p_b05c03
15777 2-parameter cubic (B=1/2, C=3/10)
15789 Scale (resize) the input video, based on a reference video.
15791 See the scale filter for available options, scale2ref supports the same but
15792 uses the reference video instead of the main input as basis. scale2ref also
15793 supports the following additional constants for the @option{w} and
15794 @option{h} options:
15799 The main input video's width and height
15802 The same as @var{main_w} / @var{main_h}
15805 The main input video's sample aspect ratio
15807 @item main_dar, mdar
15808 The main input video's display aspect ratio. Calculated from
15809 @code{(main_w / main_h) * main_sar}.
15813 The main input video's horizontal and vertical chroma subsample values.
15814 For example for the pixel format "yuv422p" @var{hsub} is 2 and @var{vsub}
15818 @subsection Examples
15822 Scale a subtitle stream (b) to match the main video (a) in size before overlaying
15824 'scale2ref[b][a];[a][b]overlay'
15828 Scale a logo to 1/10th the height of a video, while preserving its display aspect ratio.
15830 [logo-in][video-in]scale2ref=w=oh*mdar:h=ih/10[logo-out][video-out]
15835 Scroll input video horizontally and/or vertically by constant speed.
15837 The filter accepts the following options:
15839 @item horizontal, h
15840 Set the horizontal scrolling speed. Default is 0. Allowed range is from -1 to 1.
15841 Negative values changes scrolling direction.
15844 Set the vertical scrolling speed. Default is 0. Allowed range is from -1 to 1.
15845 Negative values changes scrolling direction.
15848 Set the initial horizontal scrolling position. Default is 0. Allowed range is from 0 to 1.
15851 Set the initial vertical scrolling position. Default is 0. Allowed range is from 0 to 1.
15854 @subsection Commands
15856 This filter supports the following @ref{commands}:
15858 @item horizontal, h
15859 Set the horizontal scrolling speed.
15861 Set the vertical scrolling speed.
15864 @anchor{selectivecolor}
15865 @section selectivecolor
15867 Adjust cyan, magenta, yellow and black (CMYK) to certain ranges of colors (such
15868 as "reds", "yellows", "greens", "cyans", ...). The adjustment range is defined
15869 by the "purity" of the color (that is, how saturated it already is).
15871 This filter is similar to the Adobe Photoshop Selective Color tool.
15873 The filter accepts the following options:
15876 @item correction_method
15877 Select color correction method.
15879 Available values are:
15882 Specified adjustments are applied "as-is" (added/subtracted to original pixel
15885 Specified adjustments are relative to the original component value.
15887 Default is @code{absolute}.
15889 Adjustments for red pixels (pixels where the red component is the maximum)
15891 Adjustments for yellow pixels (pixels where the blue component is the minimum)
15893 Adjustments for green pixels (pixels where the green component is the maximum)
15895 Adjustments for cyan pixels (pixels where the red component is the minimum)
15897 Adjustments for blue pixels (pixels where the blue component is the maximum)
15899 Adjustments for magenta pixels (pixels where the green component is the minimum)
15901 Adjustments for white pixels (pixels where all components are greater than 128)
15903 Adjustments for all pixels except pure black and pure white
15905 Adjustments for black pixels (pixels where all components are lesser than 128)
15907 Specify a Photoshop selective color file (@code{.asv}) to import the settings from.
15910 All the adjustment settings (@option{reds}, @option{yellows}, ...) accept up to
15911 4 space separated floating point adjustment values in the [-1,1] range,
15912 respectively to adjust the amount of cyan, magenta, yellow and black for the
15913 pixels of its range.
15915 @subsection Examples
15919 Increase cyan by 50% and reduce yellow by 33% in every green areas, and
15920 increase magenta by 27% in blue areas:
15922 selectivecolor=greens=.5 0 -.33 0:blues=0 .27
15926 Use a Photoshop selective color preset:
15928 selectivecolor=psfile=MySelectiveColorPresets/Misty.asv
15932 @anchor{separatefields}
15933 @section separatefields
15935 The @code{separatefields} takes a frame-based video input and splits
15936 each frame into its components fields, producing a new half height clip
15937 with twice the frame rate and twice the frame count.
15939 This filter use field-dominance information in frame to decide which
15940 of each pair of fields to place first in the output.
15941 If it gets it wrong use @ref{setfield} filter before @code{separatefields} filter.
15943 @section setdar, setsar
15945 The @code{setdar} filter sets the Display Aspect Ratio for the filter
15948 This is done by changing the specified Sample (aka Pixel) Aspect
15949 Ratio, according to the following equation:
15951 @var{DAR} = @var{HORIZONTAL_RESOLUTION} / @var{VERTICAL_RESOLUTION} * @var{SAR}
15954 Keep in mind that the @code{setdar} filter does not modify the pixel
15955 dimensions of the video frame. Also, the display aspect ratio set by
15956 this filter may be changed by later filters in the filterchain,
15957 e.g. in case of scaling or if another "setdar" or a "setsar" filter is
15960 The @code{setsar} filter sets the Sample (aka Pixel) Aspect Ratio for
15961 the filter output video.
15963 Note that as a consequence of the application of this filter, the
15964 output display aspect ratio will change according to the equation
15967 Keep in mind that the sample aspect ratio set by the @code{setsar}
15968 filter may be changed by later filters in the filterchain, e.g. if
15969 another "setsar" or a "setdar" filter is applied.
15971 It accepts the following parameters:
15974 @item r, ratio, dar (@code{setdar} only), sar (@code{setsar} only)
15975 Set the aspect ratio used by the filter.
15977 The parameter can be a floating point number string, an expression, or
15978 a string of the form @var{num}:@var{den}, where @var{num} and
15979 @var{den} are the numerator and denominator of the aspect ratio. If
15980 the parameter is not specified, it is assumed the value "0".
15981 In case the form "@var{num}:@var{den}" is used, the @code{:} character
15985 Set the maximum integer value to use for expressing numerator and
15986 denominator when reducing the expressed aspect ratio to a rational.
15987 Default value is @code{100}.
15991 The parameter @var{sar} is an expression containing
15992 the following constants:
15996 These are approximated values for the mathematical constants e
15997 (Euler's number), pi (Greek pi), and phi (the golden ratio).
16000 The input width and height.
16003 These are the same as @var{w} / @var{h}.
16006 The input sample aspect ratio.
16009 The input display aspect ratio. It is the same as
16010 (@var{w} / @var{h}) * @var{sar}.
16013 Horizontal and vertical chroma subsample values. For example, for the
16014 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
16017 @subsection Examples
16022 To change the display aspect ratio to 16:9, specify one of the following:
16029 To change the sample aspect ratio to 10:11, specify:
16035 To set a display aspect ratio of 16:9, and specify a maximum integer value of
16036 1000 in the aspect ratio reduction, use the command:
16038 setdar=ratio=16/9:max=1000
16046 Force field for the output video frame.
16048 The @code{setfield} filter marks the interlace type field for the
16049 output frames. It does not change the input frame, but only sets the
16050 corresponding property, which affects how the frame is treated by
16051 following filters (e.g. @code{fieldorder} or @code{yadif}).
16053 The filter accepts the following options:
16058 Available values are:
16062 Keep the same field property.
16065 Mark the frame as bottom-field-first.
16068 Mark the frame as top-field-first.
16071 Mark the frame as progressive.
16078 Force frame parameter for the output video frame.
16080 The @code{setparams} filter marks interlace and color range for the
16081 output frames. It does not change the input frame, but only sets the
16082 corresponding property, which affects how the frame is treated by
16087 Available values are:
16091 Keep the same field property (default).
16094 Mark the frame as bottom-field-first.
16097 Mark the frame as top-field-first.
16100 Mark the frame as progressive.
16104 Available values are:
16108 Keep the same color range property (default).
16110 @item unspecified, unknown
16111 Mark the frame as unspecified color range.
16113 @item limited, tv, mpeg
16114 Mark the frame as limited range.
16116 @item full, pc, jpeg
16117 Mark the frame as full range.
16120 @item color_primaries
16121 Set the color primaries.
16122 Available values are:
16126 Keep the same color primaries property (default).
16143 Set the color transfer.
16144 Available values are:
16148 Keep the same color trc property (default).
16170 Set the colorspace.
16171 Available values are:
16175 Keep the same colorspace property (default).
16188 @item chroma-derived-nc
16189 @item chroma-derived-c
16196 Show a line containing various information for each input video frame.
16197 The input video is not modified.
16199 This filter supports the following options:
16203 Calculate checksums of each plane. By default enabled.
16206 The shown line contains a sequence of key/value pairs of the form
16207 @var{key}:@var{value}.
16209 The following values are shown in the output:
16213 The (sequential) number of the input frame, starting from 0.
16216 The Presentation TimeStamp of the input frame, expressed as a number of
16217 time base units. The time base unit depends on the filter input pad.
16220 The Presentation TimeStamp of the input frame, expressed as a number of
16224 The position of the frame in the input stream, or -1 if this information is
16225 unavailable and/or meaningless (for example in case of synthetic video).
16228 The pixel format name.
16231 The sample aspect ratio of the input frame, expressed in the form
16232 @var{num}/@var{den}.
16235 The size of the input frame. For the syntax of this option, check the
16236 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
16239 The type of interlaced mode ("P" for "progressive", "T" for top field first, "B"
16240 for bottom field first).
16243 This is 1 if the frame is a key frame, 0 otherwise.
16246 The picture type of the input frame ("I" for an I-frame, "P" for a
16247 P-frame, "B" for a B-frame, or "?" for an unknown type).
16248 Also refer to the documentation of the @code{AVPictureType} enum and of
16249 the @code{av_get_picture_type_char} function defined in
16250 @file{libavutil/avutil.h}.
16253 The Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame.
16255 @item plane_checksum
16256 The Adler-32 checksum (printed in hexadecimal) of each plane of the input frame,
16257 expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3}]".
16260 @section showpalette
16262 Displays the 256 colors palette of each frame. This filter is only relevant for
16263 @var{pal8} pixel format frames.
16265 It accepts the following option:
16269 Set the size of the box used to represent one palette color entry. Default is
16270 @code{30} (for a @code{30x30} pixel box).
16273 @section shuffleframes
16275 Reorder and/or duplicate and/or drop video frames.
16277 It accepts the following parameters:
16281 Set the destination indexes of input frames.
16282 This is space or '|' separated list of indexes that maps input frames to output
16283 frames. Number of indexes also sets maximal value that each index may have.
16284 '-1' index have special meaning and that is to drop frame.
16287 The first frame has the index 0. The default is to keep the input unchanged.
16289 @subsection Examples
16293 Swap second and third frame of every three frames of the input:
16295 ffmpeg -i INPUT -vf "shuffleframes=0 2 1" OUTPUT
16299 Swap 10th and 1st frame of every ten frames of the input:
16301 ffmpeg -i INPUT -vf "shuffleframes=9 1 2 3 4 5 6 7 8 0" OUTPUT
16305 @section shuffleplanes
16307 Reorder and/or duplicate video planes.
16309 It accepts the following parameters:
16314 The index of the input plane to be used as the first output plane.
16317 The index of the input plane to be used as the second output plane.
16320 The index of the input plane to be used as the third output plane.
16323 The index of the input plane to be used as the fourth output plane.
16327 The first plane has the index 0. The default is to keep the input unchanged.
16329 @subsection Examples
16333 Swap the second and third planes of the input:
16335 ffmpeg -i INPUT -vf shuffleplanes=0:2:1:3 OUTPUT
16339 @anchor{signalstats}
16340 @section signalstats
16341 Evaluate various visual metrics that assist in determining issues associated
16342 with the digitization of analog video media.
16344 By default the filter will log these metadata values:
16348 Display the minimal Y value contained within the input frame. Expressed in
16352 Display the Y value at the 10% percentile within the input frame. Expressed in
16356 Display the average Y value within the input frame. Expressed in range of
16360 Display the Y value at the 90% percentile within the input frame. Expressed in
16364 Display the maximum Y value contained within the input frame. Expressed in
16368 Display the minimal U value contained within the input frame. Expressed in
16372 Display the U value at the 10% percentile within the input frame. Expressed in
16376 Display the average U value within the input frame. Expressed in range of
16380 Display the U value at the 90% percentile within the input frame. Expressed in
16384 Display the maximum U value contained within the input frame. Expressed in
16388 Display the minimal V value contained within the input frame. Expressed in
16392 Display the V value at the 10% percentile within the input frame. Expressed in
16396 Display the average V value within the input frame. Expressed in range of
16400 Display the V value at the 90% percentile within the input frame. Expressed in
16404 Display the maximum V value contained within the input frame. Expressed in
16408 Display the minimal saturation value contained within the input frame.
16409 Expressed in range of [0-~181.02].
16412 Display the saturation value at the 10% percentile within the input frame.
16413 Expressed in range of [0-~181.02].
16416 Display the average saturation value within the input frame. Expressed in range
16420 Display the saturation value at the 90% percentile within the input frame.
16421 Expressed in range of [0-~181.02].
16424 Display the maximum saturation value contained within the input frame.
16425 Expressed in range of [0-~181.02].
16428 Display the median value for hue within the input frame. Expressed in range of
16432 Display the average value for hue within the input frame. Expressed in range of
16436 Display the average of sample value difference between all values of the Y
16437 plane in the current frame and corresponding values of the previous input frame.
16438 Expressed in range of [0-255].
16441 Display the average of sample value difference between all values of the U
16442 plane in the current frame and corresponding values of the previous input frame.
16443 Expressed in range of [0-255].
16446 Display the average of sample value difference between all values of the V
16447 plane in the current frame and corresponding values of the previous input frame.
16448 Expressed in range of [0-255].
16451 Display bit depth of Y plane in current frame.
16452 Expressed in range of [0-16].
16455 Display bit depth of U plane in current frame.
16456 Expressed in range of [0-16].
16459 Display bit depth of V plane in current frame.
16460 Expressed in range of [0-16].
16463 The filter accepts the following options:
16469 @option{stat} specify an additional form of image analysis.
16470 @option{out} output video with the specified type of pixel highlighted.
16472 Both options accept the following values:
16476 Identify @var{temporal outliers} pixels. A @var{temporal outlier} is a pixel
16477 unlike the neighboring pixels of the same field. Examples of temporal outliers
16478 include the results of video dropouts, head clogs, or tape tracking issues.
16481 Identify @var{vertical line repetition}. Vertical line repetition includes
16482 similar rows of pixels within a frame. In born-digital video vertical line
16483 repetition is common, but this pattern is uncommon in video digitized from an
16484 analog source. When it occurs in video that results from the digitization of an
16485 analog source it can indicate concealment from a dropout compensator.
16488 Identify pixels that fall outside of legal broadcast range.
16492 Set the highlight color for the @option{out} option. The default color is
16496 @subsection Examples
16500 Output data of various video metrics:
16502 ffprobe -f lavfi movie=example.mov,signalstats="stat=tout+vrep+brng" -show_frames
16506 Output specific data about the minimum and maximum values of the Y plane per frame:
16508 ffprobe -f lavfi movie=example.mov,signalstats -show_entries frame_tags=lavfi.signalstats.YMAX,lavfi.signalstats.YMIN
16512 Playback video while highlighting pixels that are outside of broadcast range in red.
16514 ffplay example.mov -vf signalstats="out=brng:color=red"
16518 Playback video with signalstats metadata drawn over the frame.
16520 ffplay example.mov -vf signalstats=stat=brng+vrep+tout,drawtext=fontfile=FreeSerif.ttf:textfile=signalstat_drawtext.txt
16523 The contents of signalstat_drawtext.txt used in the command are:
16526 Y (%@{metadata:lavfi.signalstats.YMIN@}-%@{metadata:lavfi.signalstats.YMAX@})
16527 U (%@{metadata:lavfi.signalstats.UMIN@}-%@{metadata:lavfi.signalstats.UMAX@})
16528 V (%@{metadata:lavfi.signalstats.VMIN@}-%@{metadata:lavfi.signalstats.VMAX@})
16529 saturation maximum: %@{metadata:lavfi.signalstats.SATMAX@}
16537 Calculates the MPEG-7 Video Signature. The filter can handle more than one
16538 input. In this case the matching between the inputs can be calculated additionally.
16539 The filter always passes through the first input. The signature of each stream can
16540 be written into a file.
16542 It accepts the following options:
16546 Enable or disable the matching process.
16548 Available values are:
16552 Disable the calculation of a matching (default).
16554 Calculate the matching for the whole video and output whether the whole video
16555 matches or only parts.
16557 Calculate only until a matching is found or the video ends. Should be faster in
16562 Set the number of inputs. The option value must be a non negative integer.
16563 Default value is 1.
16566 Set the path to which the output is written. If there is more than one input,
16567 the path must be a prototype, i.e. must contain %d or %0nd (where n is a positive
16568 integer), that will be replaced with the input number. If no filename is
16569 specified, no output will be written. This is the default.
16572 Choose the output format.
16574 Available values are:
16578 Use the specified binary representation (default).
16580 Use the specified xml representation.
16584 Set threshold to detect one word as similar. The option value must be an integer
16585 greater than zero. The default value is 9000.
16588 Set threshold to detect all words as similar. The option value must be an integer
16589 greater than zero. The default value is 60000.
16592 Set threshold to detect frames as similar. The option value must be an integer
16593 greater than zero. The default value is 116.
16596 Set the minimum length of a sequence in frames to recognize it as matching
16597 sequence. The option value must be a non negative integer value.
16598 The default value is 0.
16601 Set the minimum relation, that matching frames to all frames must have.
16602 The option value must be a double value between 0 and 1. The default value is 0.5.
16605 @subsection Examples
16609 To calculate the signature of an input video and store it in signature.bin:
16611 ffmpeg -i input.mkv -vf signature=filename=signature.bin -map 0:v -f null -
16615 To detect whether two videos match and store the signatures in XML format in
16616 signature0.xml and signature1.xml:
16618 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 -
16626 Blur the input video without impacting the outlines.
16628 It accepts the following options:
16631 @item luma_radius, lr
16632 Set the luma radius. The option value must be a float number in
16633 the range [0.1,5.0] that specifies the variance of the gaussian filter
16634 used to blur the image (slower if larger). Default value is 1.0.
16636 @item luma_strength, ls
16637 Set the luma strength. The option value must be a float number
16638 in the range [-1.0,1.0] that configures the blurring. A value included
16639 in [0.0,1.0] will blur the image whereas a value included in
16640 [-1.0,0.0] will sharpen the image. Default value is 1.0.
16642 @item luma_threshold, lt
16643 Set the luma threshold used as a coefficient to determine
16644 whether a pixel should be blurred or not. The option value must be an
16645 integer in the range [-30,30]. A value of 0 will filter all the image,
16646 a value included in [0,30] will filter flat areas and a value included
16647 in [-30,0] will filter edges. Default value is 0.
16649 @item chroma_radius, cr
16650 Set the chroma radius. The option value must be a float number in
16651 the range [0.1,5.0] that specifies the variance of the gaussian filter
16652 used to blur the image (slower if larger). Default value is @option{luma_radius}.
16654 @item chroma_strength, cs
16655 Set the chroma strength. The option value must be a float number
16656 in the range [-1.0,1.0] that configures the blurring. A value included
16657 in [0.0,1.0] will blur the image whereas a value included in
16658 [-1.0,0.0] will sharpen the image. Default value is @option{luma_strength}.
16660 @item chroma_threshold, ct
16661 Set the chroma threshold used as a coefficient to determine
16662 whether a pixel should be blurred or not. The option value must be an
16663 integer in the range [-30,30]. A value of 0 will filter all the image,
16664 a value included in [0,30] will filter flat areas and a value included
16665 in [-30,0] will filter edges. Default value is @option{luma_threshold}.
16668 If a chroma option is not explicitly set, the corresponding luma value
16672 Apply sobel operator to input video stream.
16674 The filter accepts the following option:
16678 Set which planes will be processed, unprocessed planes will be copied.
16679 By default value 0xf, all planes will be processed.
16682 Set value which will be multiplied with filtered result.
16685 Set value which will be added to filtered result.
16691 Apply a simple postprocessing filter that compresses and decompresses the image
16692 at several (or - in the case of @option{quality} level @code{6} - all) shifts
16693 and average the results.
16695 The filter accepts the following options:
16699 Set quality. This option defines the number of levels for averaging. It accepts
16700 an integer in the range 0-6. If set to @code{0}, the filter will have no
16701 effect. A value of @code{6} means the higher quality. For each increment of
16702 that value the speed drops by a factor of approximately 2. Default value is
16706 Force a constant quantization parameter. If not set, the filter will use the QP
16707 from the video stream (if available).
16710 Set thresholding mode. Available modes are:
16714 Set hard thresholding (default).
16716 Set soft thresholding (better de-ringing effect, but likely blurrier).
16719 @item use_bframe_qp
16720 Enable the use of the QP from the B-Frames if set to @code{1}. Using this
16721 option may cause flicker since the B-Frames have often larger QP. Default is
16722 @code{0} (not enabled).
16727 Scale the input by applying one of the super-resolution methods based on
16728 convolutional neural networks. Supported models:
16732 Super-Resolution Convolutional Neural Network model (SRCNN).
16733 See @url{https://arxiv.org/abs/1501.00092}.
16736 Efficient Sub-Pixel Convolutional Neural Network model (ESPCN).
16737 See @url{https://arxiv.org/abs/1609.05158}.
16740 Training scripts as well as scripts for model file (.pb) saving can be found at
16741 @url{https://github.com/XueweiMeng/sr/tree/sr_dnn_native}. Original repository
16742 is at @url{https://github.com/HighVoltageRocknRoll/sr.git}.
16744 Native model files (.model) can be generated from TensorFlow model
16745 files (.pb) by using tools/python/convert.py
16747 The filter accepts the following options:
16751 Specify which DNN backend to use for model loading and execution. This option accepts
16752 the following values:
16756 Native implementation of DNN loading and execution.
16759 TensorFlow backend. To enable this backend you
16760 need to install the TensorFlow for C library (see
16761 @url{https://www.tensorflow.org/install/install_c}) and configure FFmpeg with
16762 @code{--enable-libtensorflow}
16765 Default value is @samp{native}.
16768 Set path to model file specifying network architecture and its parameters.
16769 Note that different backends use different file formats. TensorFlow backend
16770 can load files for both formats, while native backend can load files for only
16774 Set scale factor for SRCNN model. Allowed values are @code{2}, @code{3} and @code{4}.
16775 Default value is @code{2}. Scale factor is necessary for SRCNN model, because it accepts
16776 input upscaled using bicubic upscaling with proper scale factor.
16781 Obtain the SSIM (Structural SImilarity Metric) between two input videos.
16783 This filter takes in input two input videos, the first input is
16784 considered the "main" source and is passed unchanged to the
16785 output. The second input is used as a "reference" video for computing
16788 Both video inputs must have the same resolution and pixel format for
16789 this filter to work correctly. Also it assumes that both inputs
16790 have the same number of frames, which are compared one by one.
16792 The filter stores the calculated SSIM of each frame.
16794 The description of the accepted parameters follows.
16797 @item stats_file, f
16798 If specified the filter will use the named file to save the SSIM of
16799 each individual frame. When filename equals "-" the data is sent to
16803 The file printed if @var{stats_file} is selected, contains a sequence of
16804 key/value pairs of the form @var{key}:@var{value} for each compared
16807 A description of each shown parameter follows:
16811 sequential number of the input frame, starting from 1
16813 @item Y, U, V, R, G, B
16814 SSIM of the compared frames for the component specified by the suffix.
16817 SSIM of the compared frames for the whole frame.
16820 Same as above but in dB representation.
16823 This filter also supports the @ref{framesync} options.
16827 movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
16828 [main][ref] ssim="stats_file=stats.log" [out]
16831 On this example the input file being processed is compared with the
16832 reference file @file{ref_movie.mpg}. The SSIM of each individual frame
16833 is stored in @file{stats.log}.
16835 Another example with both psnr and ssim at same time:
16837 ffmpeg -i main.mpg -i ref.mpg -lavfi "ssim;[0:v][1:v]psnr" -f null -
16842 Convert between different stereoscopic image formats.
16844 The filters accept the following options:
16848 Set stereoscopic image format of input.
16850 Available values for input image formats are:
16853 side by side parallel (left eye left, right eye right)
16856 side by side crosseye (right eye left, left eye right)
16859 side by side parallel with half width resolution
16860 (left eye left, right eye right)
16863 side by side crosseye with half width resolution
16864 (right eye left, left eye right)
16868 above-below (left eye above, right eye below)
16872 above-below (right eye above, left eye below)
16876 above-below with half height resolution
16877 (left eye above, right eye below)
16881 above-below with half height resolution
16882 (right eye above, left eye below)
16885 alternating frames (left eye first, right eye second)
16888 alternating frames (right eye first, left eye second)
16891 interleaved rows (left eye has top row, right eye starts on next row)
16894 interleaved rows (right eye has top row, left eye starts on next row)
16897 interleaved columns, left eye first
16900 interleaved columns, right eye first
16902 Default value is @samp{sbsl}.
16906 Set stereoscopic image format of output.
16910 side by side parallel (left eye left, right eye right)
16913 side by side crosseye (right eye left, left eye right)
16916 side by side parallel with half width resolution
16917 (left eye left, right eye right)
16920 side by side crosseye with half width resolution
16921 (right eye left, left eye right)
16925 above-below (left eye above, right eye below)
16929 above-below (right eye above, left eye below)
16933 above-below with half height resolution
16934 (left eye above, right eye below)
16938 above-below with half height resolution
16939 (right eye above, left eye below)
16942 alternating frames (left eye first, right eye second)
16945 alternating frames (right eye first, left eye second)
16948 interleaved rows (left eye has top row, right eye starts on next row)
16951 interleaved rows (right eye has top row, left eye starts on next row)
16954 anaglyph red/blue gray
16955 (red filter on left eye, blue filter on right eye)
16958 anaglyph red/green gray
16959 (red filter on left eye, green filter on right eye)
16962 anaglyph red/cyan gray
16963 (red filter on left eye, cyan filter on right eye)
16966 anaglyph red/cyan half colored
16967 (red filter on left eye, cyan filter on right eye)
16970 anaglyph red/cyan color
16971 (red filter on left eye, cyan filter on right eye)
16974 anaglyph red/cyan color optimized with the least squares projection of dubois
16975 (red filter on left eye, cyan filter on right eye)
16978 anaglyph green/magenta gray
16979 (green filter on left eye, magenta filter on right eye)
16982 anaglyph green/magenta half colored
16983 (green filter on left eye, magenta filter on right eye)
16986 anaglyph green/magenta colored
16987 (green filter on left eye, magenta filter on right eye)
16990 anaglyph green/magenta color optimized with the least squares projection of dubois
16991 (green filter on left eye, magenta filter on right eye)
16994 anaglyph yellow/blue gray
16995 (yellow filter on left eye, blue filter on right eye)
16998 anaglyph yellow/blue half colored
16999 (yellow filter on left eye, blue filter on right eye)
17002 anaglyph yellow/blue colored
17003 (yellow filter on left eye, blue filter on right eye)
17006 anaglyph yellow/blue color optimized with the least squares projection of dubois
17007 (yellow filter on left eye, blue filter on right eye)
17010 mono output (left eye only)
17013 mono output (right eye only)
17016 checkerboard, left eye first
17019 checkerboard, right eye first
17022 interleaved columns, left eye first
17025 interleaved columns, right eye first
17031 Default value is @samp{arcd}.
17034 @subsection Examples
17038 Convert input video from side by side parallel to anaglyph yellow/blue dubois:
17044 Convert input video from above below (left eye above, right eye below) to side by side crosseye.
17050 @section streamselect, astreamselect
17051 Select video or audio streams.
17053 The filter accepts the following options:
17057 Set number of inputs. Default is 2.
17060 Set input indexes to remap to outputs.
17063 @subsection Commands
17065 The @code{streamselect} and @code{astreamselect} filter supports the following
17070 Set input indexes to remap to outputs.
17073 @subsection Examples
17077 Select first 5 seconds 1st stream and rest of time 2nd stream:
17079 sendcmd='5.0 streamselect map 1',streamselect=inputs=2:map=0
17083 Same as above, but for audio:
17085 asendcmd='5.0 astreamselect map 1',astreamselect=inputs=2:map=0
17092 Draw subtitles on top of input video using the libass library.
17094 To enable compilation of this filter you need to configure FFmpeg with
17095 @code{--enable-libass}. This filter also requires a build with libavcodec and
17096 libavformat to convert the passed subtitles file to ASS (Advanced Substation
17097 Alpha) subtitles format.
17099 The filter accepts the following options:
17103 Set the filename of the subtitle file to read. It must be specified.
17105 @item original_size
17106 Specify the size of the original video, the video for which the ASS file
17107 was composed. For the syntax of this option, check the
17108 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
17109 Due to a misdesign in ASS aspect ratio arithmetic, this is necessary to
17110 correctly scale the fonts if the aspect ratio has been changed.
17113 Set a directory path containing fonts that can be used by the filter.
17114 These fonts will be used in addition to whatever the font provider uses.
17117 Process alpha channel, by default alpha channel is untouched.
17120 Set subtitles input character encoding. @code{subtitles} filter only. Only
17121 useful if not UTF-8.
17123 @item stream_index, si
17124 Set subtitles stream index. @code{subtitles} filter only.
17127 Override default style or script info parameters of the subtitles. It accepts a
17128 string containing ASS style format @code{KEY=VALUE} couples separated by ",".
17131 If the first key is not specified, it is assumed that the first value
17132 specifies the @option{filename}.
17134 For example, to render the file @file{sub.srt} on top of the input
17135 video, use the command:
17140 which is equivalent to:
17142 subtitles=filename=sub.srt
17145 To render the default subtitles stream from file @file{video.mkv}, use:
17147 subtitles=video.mkv
17150 To render the second subtitles stream from that file, use:
17152 subtitles=video.mkv:si=1
17155 To make the subtitles stream from @file{sub.srt} appear in 80% transparent blue
17156 @code{DejaVu Serif}, use:
17158 subtitles=sub.srt:force_style='FontName=DejaVu Serif,PrimaryColour=&HCCFF0000'
17161 @section super2xsai
17163 Scale the input by 2x and smooth using the Super2xSaI (Scale and
17164 Interpolate) pixel art scaling algorithm.
17166 Useful for enlarging pixel art images without reducing sharpness.
17170 Swap two rectangular objects in video.
17172 This filter accepts the following options:
17182 Set 1st rect x coordinate.
17185 Set 1st rect y coordinate.
17188 Set 2nd rect x coordinate.
17191 Set 2nd rect y coordinate.
17193 All expressions are evaluated once for each frame.
17196 The all options are expressions containing the following constants:
17201 The input width and height.
17204 same as @var{w} / @var{h}
17207 input sample aspect ratio
17210 input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
17213 The number of the input frame, starting from 0.
17216 The timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
17219 the position in the file of the input frame, NAN if unknown
17227 Apply telecine process to the video.
17229 This filter accepts the following options:
17238 The default value is @code{top}.
17242 A string of numbers representing the pulldown pattern you wish to apply.
17243 The default value is @code{23}.
17247 Some typical patterns:
17252 24p: 2332 (preferred)
17259 24p: 222222222223 ("Euro pulldown")
17266 Apply threshold effect to video stream.
17268 This filter needs four video streams to perform thresholding.
17269 First stream is stream we are filtering.
17270 Second stream is holding threshold values, third stream is holding min values,
17271 and last, fourth stream is holding max values.
17273 The filter accepts the following option:
17277 Set which planes will be processed, unprocessed planes will be copied.
17278 By default value 0xf, all planes will be processed.
17281 For example if first stream pixel's component value is less then threshold value
17282 of pixel component from 2nd threshold stream, third stream value will picked,
17283 otherwise fourth stream pixel component value will be picked.
17285 Using color source filter one can perform various types of thresholding:
17287 @subsection Examples
17291 Binary threshold, using gray color as threshold:
17293 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=black -f lavfi -i color=white -lavfi threshold output.avi
17297 Inverted binary threshold, using gray color as threshold:
17299 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -f lavfi -i color=black -lavfi threshold output.avi
17303 Truncate binary threshold, using gray color as threshold:
17305 ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=gray -lavfi threshold output.avi
17309 Threshold to zero, using gray color as threshold:
17311 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -i 320x240.avi -lavfi threshold output.avi
17315 Inverted threshold to zero, using gray color as threshold:
17317 ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=white -lavfi threshold output.avi
17322 Select the most representative frame in a given sequence of consecutive frames.
17324 The filter accepts the following options:
17328 Set the frames batch size to analyze; in a set of @var{n} frames, the filter
17329 will pick one of them, and then handle the next batch of @var{n} frames until
17330 the end. Default is @code{100}.
17333 Since the filter keeps track of the whole frames sequence, a bigger @var{n}
17334 value will result in a higher memory usage, so a high value is not recommended.
17336 @subsection Examples
17340 Extract one picture each 50 frames:
17346 Complete example of a thumbnail creation with @command{ffmpeg}:
17348 ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png
17354 Tile several successive frames together.
17356 The filter accepts the following options:
17361 Set the grid size (i.e. the number of lines and columns). For the syntax of
17362 this option, check the
17363 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
17366 Set the maximum number of frames to render in the given area. It must be less
17367 than or equal to @var{w}x@var{h}. The default value is @code{0}, meaning all
17368 the area will be used.
17371 Set the outer border margin in pixels.
17374 Set the inner border thickness (i.e. the number of pixels between frames). For
17375 more advanced padding options (such as having different values for the edges),
17376 refer to the pad video filter.
17379 Specify the color of the unused area. For the syntax of this option, check the
17380 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
17381 The default value of @var{color} is "black".
17384 Set the number of frames to overlap when tiling several successive frames together.
17385 The value must be between @code{0} and @var{nb_frames - 1}.
17388 Set the number of frames to initially be empty before displaying first output frame.
17389 This controls how soon will one get first output frame.
17390 The value must be between @code{0} and @var{nb_frames - 1}.
17393 @subsection Examples
17397 Produce 8x8 PNG tiles of all keyframes (@option{-skip_frame nokey}) in a movie:
17399 ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -vsync 0 keyframes%03d.png
17401 The @option{-vsync 0} is necessary to prevent @command{ffmpeg} from
17402 duplicating each output frame to accommodate the originally detected frame
17406 Display @code{5} pictures in an area of @code{3x2} frames,
17407 with @code{7} pixels between them, and @code{2} pixels of initial margin, using
17408 mixed flat and named options:
17410 tile=3x2:nb_frames=5:padding=7:margin=2
17414 @section tinterlace
17416 Perform various types of temporal field interlacing.
17418 Frames are counted starting from 1, so the first input frame is
17421 The filter accepts the following options:
17426 Specify the mode of the interlacing. This option can also be specified
17427 as a value alone. See below for a list of values for this option.
17429 Available values are:
17433 Move odd frames into the upper field, even into the lower field,
17434 generating a double height frame at half frame rate.
17438 Frame 1 Frame 2 Frame 3 Frame 4
17440 11111 22222 33333 44444
17441 11111 22222 33333 44444
17442 11111 22222 33333 44444
17443 11111 22222 33333 44444
17457 Only output odd frames, even frames are dropped, generating a frame with
17458 unchanged height at half frame rate.
17463 Frame 1 Frame 2 Frame 3 Frame 4
17465 11111 22222 33333 44444
17466 11111 22222 33333 44444
17467 11111 22222 33333 44444
17468 11111 22222 33333 44444
17478 Only output even frames, odd frames are dropped, generating a frame with
17479 unchanged height at half frame rate.
17484 Frame 1 Frame 2 Frame 3 Frame 4
17486 11111 22222 33333 44444
17487 11111 22222 33333 44444
17488 11111 22222 33333 44444
17489 11111 22222 33333 44444
17499 Expand each frame to full height, but pad alternate lines with black,
17500 generating a frame with double height at the same input frame rate.
17505 Frame 1 Frame 2 Frame 3 Frame 4
17507 11111 22222 33333 44444
17508 11111 22222 33333 44444
17509 11111 22222 33333 44444
17510 11111 22222 33333 44444
17513 11111 ..... 33333 .....
17514 ..... 22222 ..... 44444
17515 11111 ..... 33333 .....
17516 ..... 22222 ..... 44444
17517 11111 ..... 33333 .....
17518 ..... 22222 ..... 44444
17519 11111 ..... 33333 .....
17520 ..... 22222 ..... 44444
17524 @item interleave_top, 4
17525 Interleave the upper field from odd frames with the lower field from
17526 even frames, generating a frame with unchanged height at half frame rate.
17531 Frame 1 Frame 2 Frame 3 Frame 4
17533 11111<- 22222 33333<- 44444
17534 11111 22222<- 33333 44444<-
17535 11111<- 22222 33333<- 44444
17536 11111 22222<- 33333 44444<-
17546 @item interleave_bottom, 5
17547 Interleave the lower field from odd frames with the upper field from
17548 even frames, generating a frame with unchanged height at half frame rate.
17553 Frame 1 Frame 2 Frame 3 Frame 4
17555 11111 22222<- 33333 44444<-
17556 11111<- 22222 33333<- 44444
17557 11111 22222<- 33333 44444<-
17558 11111<- 22222 33333<- 44444
17568 @item interlacex2, 6
17569 Double frame rate with unchanged height. Frames are inserted each
17570 containing the second temporal field from the previous input frame and
17571 the first temporal field from the next input frame. This mode relies on
17572 the top_field_first flag. Useful for interlaced video displays with no
17573 field synchronisation.
17578 Frame 1 Frame 2 Frame 3 Frame 4
17580 11111 22222 33333 44444
17581 11111 22222 33333 44444
17582 11111 22222 33333 44444
17583 11111 22222 33333 44444
17586 11111 22222 22222 33333 33333 44444 44444
17587 11111 11111 22222 22222 33333 33333 44444
17588 11111 22222 22222 33333 33333 44444 44444
17589 11111 11111 22222 22222 33333 33333 44444
17594 Move odd frames into the upper field, even into the lower field,
17595 generating a double height frame at same frame rate.
17600 Frame 1 Frame 2 Frame 3 Frame 4
17602 11111 22222 33333 44444
17603 11111 22222 33333 44444
17604 11111 22222 33333 44444
17605 11111 22222 33333 44444
17608 11111 33333 33333 55555
17609 22222 22222 44444 44444
17610 11111 33333 33333 55555
17611 22222 22222 44444 44444
17612 11111 33333 33333 55555
17613 22222 22222 44444 44444
17614 11111 33333 33333 55555
17615 22222 22222 44444 44444
17620 Numeric values are deprecated but are accepted for backward
17621 compatibility reasons.
17623 Default mode is @code{merge}.
17626 Specify flags influencing the filter process.
17628 Available value for @var{flags} is:
17631 @item low_pass_filter, vlpf
17632 Enable linear vertical low-pass filtering in the filter.
17633 Vertical low-pass filtering is required when creating an interlaced
17634 destination from a progressive source which contains high-frequency
17635 vertical detail. Filtering will reduce interlace 'twitter' and Moire
17638 @item complex_filter, cvlpf
17639 Enable complex vertical low-pass filtering.
17640 This will slightly less reduce interlace 'twitter' and Moire
17641 patterning but better retain detail and subjective sharpness impression.
17645 Vertical low-pass filtering can only be enabled for @option{mode}
17646 @var{interleave_top} and @var{interleave_bottom}.
17652 Mix successive video frames.
17654 A description of the accepted options follows.
17658 The number of successive frames to mix. If unspecified, it defaults to 3.
17661 Specify weight of each input video frame.
17662 Each weight is separated by space. If number of weights is smaller than
17663 number of @var{frames} last specified weight will be used for all remaining
17667 Specify scale, if it is set it will be multiplied with sum
17668 of each weight multiplied with pixel values to give final destination
17669 pixel value. By default @var{scale} is auto scaled to sum of weights.
17672 @subsection Examples
17676 Average 7 successive frames:
17678 tmix=frames=7:weights="1 1 1 1 1 1 1"
17682 Apply simple temporal convolution:
17684 tmix=frames=3:weights="-1 3 -1"
17688 Similar as above but only showing temporal differences:
17690 tmix=frames=3:weights="-1 2 -1":scale=1
17696 Tone map colors from different dynamic ranges.
17698 This filter expects data in single precision floating point, as it needs to
17699 operate on (and can output) out-of-range values. Another filter, such as
17700 @ref{zscale}, is needed to convert the resulting frame to a usable format.
17702 The tonemapping algorithms implemented only work on linear light, so input
17703 data should be linearized beforehand (and possibly correctly tagged).
17706 ffmpeg -i INPUT -vf zscale=transfer=linear,tonemap=clip,zscale=transfer=bt709,format=yuv420p OUTPUT
17709 @subsection Options
17710 The filter accepts the following options.
17714 Set the tone map algorithm to use.
17716 Possible values are:
17719 Do not apply any tone map, only desaturate overbright pixels.
17722 Hard-clip any out-of-range values. Use it for perfect color accuracy for
17723 in-range values, while distorting out-of-range values.
17726 Stretch the entire reference gamut to a linear multiple of the display.
17729 Fit a logarithmic transfer between the tone curves.
17732 Preserve overall image brightness with a simple curve, using nonlinear
17733 contrast, which results in flattening details and degrading color accuracy.
17736 Preserve both dark and bright details better than @var{reinhard}, at the cost
17737 of slightly darkening everything. Use it when detail preservation is more
17738 important than color and brightness accuracy.
17741 Smoothly map out-of-range values, while retaining contrast and colors for
17742 in-range material as much as possible. Use it when color accuracy is more
17743 important than detail preservation.
17749 Tune the tone mapping algorithm.
17751 This affects the following algorithms:
17757 Specifies the scale factor to use while stretching.
17761 Specifies the exponent of the function.
17765 Specify an extra linear coefficient to multiply into the signal before clipping.
17769 Specify the local contrast coefficient at the display peak.
17770 Default to 0.5, which means that in-gamut values will be about half as bright
17777 Specify the transition point from linear to mobius transform. Every value
17778 below this point is guaranteed to be mapped 1:1. The higher the value, the
17779 more accurate the result will be, at the cost of losing bright details.
17780 Default to 0.3, which due to the steep initial slope still preserves in-range
17781 colors fairly accurately.
17785 Apply desaturation for highlights that exceed this level of brightness. The
17786 higher the parameter, the more color information will be preserved. This
17787 setting helps prevent unnaturally blown-out colors for super-highlights, by
17788 (smoothly) turning into white instead. This makes images feel more natural,
17789 at the cost of reducing information about out-of-range colors.
17791 The default of 2.0 is somewhat conservative and will mostly just apply to
17792 skies or directly sunlit surfaces. A setting of 0.0 disables this option.
17794 This option works only if the input frame has a supported color tag.
17797 Override signal/nominal/reference peak with this value. Useful when the
17798 embedded peak information in display metadata is not reliable or when tone
17799 mapping from a lower range to a higher range.
17804 Temporarily pad video frames.
17806 The filter accepts the following options:
17810 Specify number of delay frames before input video stream.
17813 Specify number of padding frames after input video stream.
17814 Set to -1 to pad indefinitely.
17817 Set kind of frames added to beginning of stream.
17818 Can be either @var{add} or @var{clone}.
17819 With @var{add} frames of solid-color are added.
17820 With @var{clone} frames are clones of first frame.
17823 Set kind of frames added to end of stream.
17824 Can be either @var{add} or @var{clone}.
17825 With @var{add} frames of solid-color are added.
17826 With @var{clone} frames are clones of last frame.
17828 @item start_duration, stop_duration
17829 Specify the duration of the start/stop delay. See
17830 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
17831 for the accepted syntax.
17832 These options override @var{start} and @var{stop}.
17835 Specify the color of the padded area. For the syntax of this option,
17836 check the @ref{color syntax,,"Color" section in the ffmpeg-utils
17837 manual,ffmpeg-utils}.
17839 The default value of @var{color} is "black".
17845 Transpose rows with columns in the input video and optionally flip it.
17847 It accepts the following parameters:
17852 Specify the transposition direction.
17854 Can assume the following values:
17856 @item 0, 4, cclock_flip
17857 Rotate by 90 degrees counterclockwise and vertically flip (default), that is:
17865 Rotate by 90 degrees clockwise, that is:
17873 Rotate by 90 degrees counterclockwise, that is:
17880 @item 3, 7, clock_flip
17881 Rotate by 90 degrees clockwise and vertically flip, that is:
17889 For values between 4-7, the transposition is only done if the input
17890 video geometry is portrait and not landscape. These values are
17891 deprecated, the @code{passthrough} option should be used instead.
17893 Numerical values are deprecated, and should be dropped in favor of
17894 symbolic constants.
17897 Do not apply the transposition if the input geometry matches the one
17898 specified by the specified value. It accepts the following values:
17901 Always apply transposition.
17903 Preserve portrait geometry (when @var{height} >= @var{width}).
17905 Preserve landscape geometry (when @var{width} >= @var{height}).
17908 Default value is @code{none}.
17911 For example to rotate by 90 degrees clockwise and preserve portrait
17914 transpose=dir=1:passthrough=portrait
17917 The command above can also be specified as:
17919 transpose=1:portrait
17922 @section transpose_npp
17924 Transpose rows with columns in the input video and optionally flip it.
17925 For more in depth examples see the @ref{transpose} video filter, which shares mostly the same options.
17927 It accepts the following parameters:
17932 Specify the transposition direction.
17934 Can assume the following values:
17937 Rotate by 90 degrees counterclockwise and vertically flip. (default)
17940 Rotate by 90 degrees clockwise.
17943 Rotate by 90 degrees counterclockwise.
17946 Rotate by 90 degrees clockwise and vertically flip.
17950 Do not apply the transposition if the input geometry matches the one
17951 specified by the specified value. It accepts the following values:
17954 Always apply transposition. (default)
17956 Preserve portrait geometry (when @var{height} >= @var{width}).
17958 Preserve landscape geometry (when @var{width} >= @var{height}).
17964 Trim the input so that the output contains one continuous subpart of the input.
17966 It accepts the following parameters:
17969 Specify the time of the start of the kept section, i.e. the frame with the
17970 timestamp @var{start} will be the first frame in the output.
17973 Specify the time of the first frame that will be dropped, i.e. the frame
17974 immediately preceding the one with the timestamp @var{end} will be the last
17975 frame in the output.
17978 This is the same as @var{start}, except this option sets the start timestamp
17979 in timebase units instead of seconds.
17982 This is the same as @var{end}, except this option sets the end timestamp
17983 in timebase units instead of seconds.
17986 The maximum duration of the output in seconds.
17989 The number of the first frame that should be passed to the output.
17992 The number of the first frame that should be dropped.
17995 @option{start}, @option{end}, and @option{duration} are expressed as time
17996 duration specifications; see
17997 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
17998 for the accepted syntax.
18000 Note that the first two sets of the start/end options and the @option{duration}
18001 option look at the frame timestamp, while the _frame variants simply count the
18002 frames that pass through the filter. Also note that this filter does not modify
18003 the timestamps. If you wish for the output timestamps to start at zero, insert a
18004 setpts filter after the trim filter.
18006 If multiple start or end options are set, this filter tries to be greedy and
18007 keep all the frames that match at least one of the specified constraints. To keep
18008 only the part that matches all the constraints at once, chain multiple trim
18011 The defaults are such that all the input is kept. So it is possible to set e.g.
18012 just the end values to keep everything before the specified time.
18017 Drop everything except the second minute of input:
18019 ffmpeg -i INPUT -vf trim=60:120
18023 Keep only the first second:
18025 ffmpeg -i INPUT -vf trim=duration=1
18030 @section unpremultiply
18031 Apply alpha unpremultiply effect to input video stream using first plane
18032 of second stream as alpha.
18034 Both streams must have same dimensions and same pixel format.
18036 The filter accepts the following option:
18040 Set which planes will be processed, unprocessed planes will be copied.
18041 By default value 0xf, all planes will be processed.
18043 If the format has 1 or 2 components, then luma is bit 0.
18044 If the format has 3 or 4 components:
18045 for RGB formats bit 0 is green, bit 1 is blue and bit 2 is red;
18046 for YUV formats bit 0 is luma, bit 1 is chroma-U and bit 2 is chroma-V.
18047 If present, the alpha channel is always the last bit.
18050 Do not require 2nd input for processing, instead use alpha plane from input stream.
18056 Sharpen or blur the input video.
18058 It accepts the following parameters:
18061 @item luma_msize_x, lx
18062 Set the luma matrix horizontal size. It must be an odd integer between
18063 3 and 23. The default value is 5.
18065 @item luma_msize_y, ly
18066 Set the luma matrix vertical size. It must be an odd integer between 3
18067 and 23. The default value is 5.
18069 @item luma_amount, la
18070 Set the luma effect strength. It must be a floating point number, reasonable
18071 values lay between -1.5 and 1.5.
18073 Negative values will blur the input video, while positive values will
18074 sharpen it, a value of zero will disable the effect.
18076 Default value is 1.0.
18078 @item chroma_msize_x, cx
18079 Set the chroma matrix horizontal size. It must be an odd integer
18080 between 3 and 23. The default value is 5.
18082 @item chroma_msize_y, cy
18083 Set the chroma matrix vertical size. It must be an odd integer
18084 between 3 and 23. The default value is 5.
18086 @item chroma_amount, ca
18087 Set the chroma effect strength. It must be a floating point number, reasonable
18088 values lay between -1.5 and 1.5.
18090 Negative values will blur the input video, while positive values will
18091 sharpen it, a value of zero will disable the effect.
18093 Default value is 0.0.
18097 All parameters are optional and default to the equivalent of the
18098 string '5:5:1.0:5:5:0.0'.
18100 @subsection Examples
18104 Apply strong luma sharpen effect:
18106 unsharp=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5
18110 Apply a strong blur of both luma and chroma parameters:
18112 unsharp=7:7:-2:7:7:-2
18118 Apply ultra slow/simple postprocessing filter that compresses and decompresses
18119 the image at several (or - in the case of @option{quality} level @code{8} - all)
18120 shifts and average the results.
18122 The way this differs from the behavior of spp is that uspp actually encodes &
18123 decodes each case with libavcodec Snow, whereas spp uses a simplified intra only 8x8
18124 DCT similar to MJPEG.
18126 The filter accepts the following options:
18130 Set quality. This option defines the number of levels for averaging. It accepts
18131 an integer in the range 0-8. If set to @code{0}, the filter will have no
18132 effect. A value of @code{8} means the higher quality. For each increment of
18133 that value the speed drops by a factor of approximately 2. Default value is
18137 Force a constant quantization parameter. If not set, the filter will use the QP
18138 from the video stream (if available).
18143 Convert 360 videos between various formats.
18145 The filter accepts the following options:
18151 Set format of the input/output video.
18159 Equirectangular projection.
18164 Cubemap with 3x2/6x1/1x6 layout.
18166 Format specific options:
18171 Set padding proportion for the input/output cubemap. Values in decimals.
18178 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)
18181 Default value is @b{@samp{0}}.
18185 Set fixed padding for the input/output cubemap. Values in pixels.
18187 Default value is @b{@samp{0}}. If greater than zero it overrides other padding options.
18191 Set order of faces for the input/output cubemap. Choose one direction for each position.
18193 Designation of directions:
18209 Default value is @b{@samp{rludfb}}.
18213 Set rotation of faces for the input/output cubemap. Choose one angle for each position.
18215 Designation of angles:
18218 0 degrees clockwise
18220 90 degrees clockwise
18222 180 degrees clockwise
18224 270 degrees clockwise
18227 Default value is @b{@samp{000000}}.
18231 Equi-Angular Cubemap.
18236 Regular video. @i{(output only)}
18238 Format specific options:
18243 Set horizontal/vertical/diagonal field of view. Values in degrees.
18245 If diagonal field of view is set it overrides horizontal and vertical field of view.
18251 Format specific options:
18255 Set padding proportion. Values in decimals.
18265 Default value is @b{@samp{0}}.
18270 Facebook's 360 format.
18273 Stereographic format.
18275 Format specific options:
18280 Set horizontal/vertical/diagonal field of view. Values in degrees.
18282 If diagonal field of view is set it overrides horizontal and vertical field of view.
18289 Ball format, gives significant distortion toward the back.
18292 Hammer-Aitoff map projection format.
18295 Sinusoidal map projection format.
18300 Set interpolation method.@*
18301 @i{Note: more complex interpolation methods require much more memory to run.}
18311 Bilinear interpolation.
18314 Bicubic interpolation.
18317 Lanczos interpolation.
18320 Default value is @b{@samp{line}}.
18324 Set the output video resolution.
18326 Default resolution depends on formats.
18330 Set the input/output stereo format.
18341 Default value is @b{@samp{2d}} for input and output format.
18346 Set rotation for the output video. Values in degrees.
18349 Set rotation order for the output video. Choose one item for each position.
18360 Default value is @b{@samp{ypr}}.
18365 Flip the output video horizontally(swaps left-right)/vertically(swaps up-down)/in-depth(swaps back-forward). Boolean values.
18369 Set if input video is flipped horizontally/vertically. Boolean values.
18372 Set if input video is transposed. Boolean value, by default disabled.
18375 Set if output video needs to be transposed. Boolean value, by default disabled.
18379 @subsection Examples
18383 Convert equirectangular video to cubemap with 3x2 layout and 1% padding using bicubic interpolation:
18385 ffmpeg -i input.mkv -vf v360=e:c3x2:cubic:out_pad=0.01 output.mkv
18388 Extract back view of Equi-Angular Cubemap:
18390 ffmpeg -i input.mkv -vf v360=eac:flat:yaw=180 output.mkv
18393 Convert transposed and horizontally flipped Equi-Angular Cubemap in side-by-side stereo format to equirectangular top-bottom stereo format:
18395 v360=eac:equirect:in_stereo=sbs:in_trans=1:ih_flip=1:out_stereo=tb
18399 @section vaguedenoiser
18401 Apply a wavelet based denoiser.
18403 It transforms each frame from the video input into the wavelet domain,
18404 using Cohen-Daubechies-Feauveau 9/7. Then it applies some filtering to
18405 the obtained coefficients. It does an inverse wavelet transform after.
18406 Due to wavelet properties, it should give a nice smoothed result, and
18407 reduced noise, without blurring picture features.
18409 This filter accepts the following options:
18413 The filtering strength. The higher, the more filtered the video will be.
18414 Hard thresholding can use a higher threshold than soft thresholding
18415 before the video looks overfiltered. Default value is 2.
18418 The filtering method the filter will use.
18420 It accepts the following values:
18423 All values under the threshold will be zeroed.
18426 All values under the threshold will be zeroed. All values above will be
18427 reduced by the threshold.
18430 Scales or nullifies coefficients - intermediary between (more) soft and
18431 (less) hard thresholding.
18434 Default is garrote.
18437 Number of times, the wavelet will decompose the picture. Picture can't
18438 be decomposed beyond a particular point (typically, 8 for a 640x480
18439 frame - as 2^9 = 512 > 480). Valid values are integers between 1 and 32. Default value is 6.
18442 Partial of full denoising (limited coefficients shrinking), from 0 to 100. Default value is 85.
18445 A list of the planes to process. By default all planes are processed.
18448 @section vectorscope
18450 Display 2 color component values in the two dimensional graph (which is called
18453 This filter accepts the following options:
18457 Set vectorscope mode.
18459 It accepts the following values:
18462 Gray values are displayed on graph, higher brightness means more pixels have
18463 same component color value on location in graph. This is the default mode.
18466 Gray values are displayed on graph. Surrounding pixels values which are not
18467 present in video frame are drawn in gradient of 2 color components which are
18468 set by option @code{x} and @code{y}. The 3rd color component is static.
18471 Actual color components values present in video frame are displayed on graph.
18474 Similar as color2 but higher frequency of same values @code{x} and @code{y}
18475 on graph increases value of another color component, which is luminance by
18476 default values of @code{x} and @code{y}.
18479 Actual colors present in video frame are displayed on graph. If two different
18480 colors map to same position on graph then color with higher value of component
18481 not present in graph is picked.
18484 Gray values are displayed on graph. Similar to @code{color} but with 3rd color
18485 component picked from radial gradient.
18489 Set which color component will be represented on X-axis. Default is @code{1}.
18492 Set which color component will be represented on Y-axis. Default is @code{2}.
18495 Set intensity, used by modes: gray, color, color3 and color5 for increasing brightness
18496 of color component which represents frequency of (X, Y) location in graph.
18501 No envelope, this is default.
18504 Instant envelope, even darkest single pixel will be clearly highlighted.
18507 Hold maximum and minimum values presented in graph over time. This way you
18508 can still spot out of range values without constantly looking at vectorscope.
18511 Peak and instant envelope combined together.
18515 Set what kind of graticule to draw.
18523 Set graticule opacity.
18526 Set graticule flags.
18530 Draw graticule for white point.
18533 Draw graticule for black point.
18536 Draw color points short names.
18540 Set background opacity.
18542 @item lthreshold, l
18543 Set low threshold for color component not represented on X or Y axis.
18544 Values lower than this value will be ignored. Default is 0.
18545 Note this value is multiplied with actual max possible value one pixel component
18546 can have. So for 8-bit input and low threshold value of 0.1 actual threshold
18549 @item hthreshold, h
18550 Set high threshold for color component not represented on X or Y axis.
18551 Values higher than this value will be ignored. Default is 1.
18552 Note this value is multiplied with actual max possible value one pixel component
18553 can have. So for 8-bit input and high threshold value of 0.9 actual threshold
18554 is 0.9 * 255 = 230.
18556 @item colorspace, c
18557 Set what kind of colorspace to use when drawing graticule.
18566 @anchor{vidstabdetect}
18567 @section vidstabdetect
18569 Analyze video stabilization/deshaking. Perform pass 1 of 2, see
18570 @ref{vidstabtransform} for pass 2.
18572 This filter generates a file with relative translation and rotation
18573 transform information about subsequent frames, which is then used by
18574 the @ref{vidstabtransform} filter.
18576 To enable compilation of this filter you need to configure FFmpeg with
18577 @code{--enable-libvidstab}.
18579 This filter accepts the following options:
18583 Set the path to the file used to write the transforms information.
18584 Default value is @file{transforms.trf}.
18587 Set how shaky the video is and how quick the camera is. It accepts an
18588 integer in the range 1-10, a value of 1 means little shakiness, a
18589 value of 10 means strong shakiness. Default value is 5.
18592 Set the accuracy of the detection process. It must be a value in the
18593 range 1-15. A value of 1 means low accuracy, a value of 15 means high
18594 accuracy. Default value is 15.
18597 Set stepsize of the search process. The region around minimum is
18598 scanned with 1 pixel resolution. Default value is 6.
18601 Set minimum contrast. Below this value a local measurement field is
18602 discarded. Must be a floating point value in the range 0-1. Default
18606 Set reference frame number for tripod mode.
18608 If enabled, the motion of the frames is compared to a reference frame
18609 in the filtered stream, identified by the specified number. The idea
18610 is to compensate all movements in a more-or-less static scene and keep
18611 the camera view absolutely still.
18613 If set to 0, it is disabled. The frames are counted starting from 1.
18616 Show fields and transforms in the resulting frames. It accepts an
18617 integer in the range 0-2. Default value is 0, which disables any
18621 @subsection Examples
18625 Use default values:
18631 Analyze strongly shaky movie and put the results in file
18632 @file{mytransforms.trf}:
18634 vidstabdetect=shakiness=10:accuracy=15:result="mytransforms.trf"
18638 Visualize the result of internal transformations in the resulting
18641 vidstabdetect=show=1
18645 Analyze a video with medium shakiness using @command{ffmpeg}:
18647 ffmpeg -i input -vf vidstabdetect=shakiness=5:show=1 dummy.avi
18651 @anchor{vidstabtransform}
18652 @section vidstabtransform
18654 Video stabilization/deshaking: pass 2 of 2,
18655 see @ref{vidstabdetect} for pass 1.
18657 Read a file with transform information for each frame and
18658 apply/compensate them. Together with the @ref{vidstabdetect}
18659 filter this can be used to deshake videos. See also
18660 @url{http://public.hronopik.de/vid.stab}. It is important to also use
18661 the @ref{unsharp} filter, see below.
18663 To enable compilation of this filter you need to configure FFmpeg with
18664 @code{--enable-libvidstab}.
18666 @subsection Options
18670 Set path to the file used to read the transforms. Default value is
18671 @file{transforms.trf}.
18674 Set the number of frames (value*2 + 1) used for lowpass filtering the
18675 camera movements. Default value is 10.
18677 For example a number of 10 means that 21 frames are used (10 in the
18678 past and 10 in the future) to smoothen the motion in the video. A
18679 larger value leads to a smoother video, but limits the acceleration of
18680 the camera (pan/tilt movements). 0 is a special case where a static
18681 camera is simulated.
18684 Set the camera path optimization algorithm.
18686 Accepted values are:
18689 gaussian kernel low-pass filter on camera motion (default)
18691 averaging on transformations
18695 Set maximal number of pixels to translate frames. Default value is -1,
18699 Set maximal angle in radians (degree*PI/180) to rotate frames. Default
18700 value is -1, meaning no limit.
18703 Specify how to deal with borders that may be visible due to movement
18706 Available values are:
18709 keep image information from previous frame (default)
18711 fill the border black
18715 Invert transforms if set to 1. Default value is 0.
18718 Consider transforms as relative to previous frame if set to 1,
18719 absolute if set to 0. Default value is 0.
18722 Set percentage to zoom. A positive value will result in a zoom-in
18723 effect, a negative value in a zoom-out effect. Default value is 0 (no
18727 Set optimal zooming to avoid borders.
18729 Accepted values are:
18734 optimal static zoom value is determined (only very strong movements
18735 will lead to visible borders) (default)
18737 optimal adaptive zoom value is determined (no borders will be
18738 visible), see @option{zoomspeed}
18741 Note that the value given at zoom is added to the one calculated here.
18744 Set percent to zoom maximally each frame (enabled when
18745 @option{optzoom} is set to 2). Range is from 0 to 5, default value is
18749 Specify type of interpolation.
18751 Available values are:
18756 linear only horizontal
18758 linear in both directions (default)
18760 cubic in both directions (slow)
18764 Enable virtual tripod mode if set to 1, which is equivalent to
18765 @code{relative=0:smoothing=0}. Default value is 0.
18767 Use also @code{tripod} option of @ref{vidstabdetect}.
18770 Increase log verbosity if set to 1. Also the detected global motions
18771 are written to the temporary file @file{global_motions.trf}. Default
18775 @subsection Examples
18779 Use @command{ffmpeg} for a typical stabilization with default values:
18781 ffmpeg -i inp.mpeg -vf vidstabtransform,unsharp=5:5:0.8:3:3:0.4 inp_stabilized.mpeg
18784 Note the use of the @ref{unsharp} filter which is always recommended.
18787 Zoom in a bit more and load transform data from a given file:
18789 vidstabtransform=zoom=5:input="mytransforms.trf"
18793 Smoothen the video even more:
18795 vidstabtransform=smoothing=30
18801 Flip the input video vertically.
18803 For example, to vertically flip a video with @command{ffmpeg}:
18805 ffmpeg -i in.avi -vf "vflip" out.avi
18810 Detect variable frame rate video.
18812 This filter tries to detect if the input is variable or constant frame rate.
18814 At end it will output number of frames detected as having variable delta pts,
18815 and ones with constant delta pts.
18816 If there was frames with variable delta, than it will also show min and max delta
18821 Boost or alter saturation.
18823 The filter accepts the following options:
18826 Set strength of boost if positive value or strength of alter if negative value.
18827 Default is 0. Allowed range is from -2 to 2.
18830 Set the red balance. Default is 1. Allowed range is from -10 to 10.
18833 Set the green balance. Default is 1. Allowed range is from -10 to 10.
18836 Set the blue balance. Default is 1. Allowed range is from -10 to 10.
18839 Set the red luma coefficient.
18842 Set the green luma coefficient.
18845 Set the blue luma coefficient.
18848 If @code{intensity} is negative and this is set to 1, colors will change,
18849 otherwise colors will be less saturated, more towards gray.
18855 Make or reverse a natural vignetting effect.
18857 The filter accepts the following options:
18861 Set lens angle expression as a number of radians.
18863 The value is clipped in the @code{[0,PI/2]} range.
18865 Default value: @code{"PI/5"}
18869 Set center coordinates expressions. Respectively @code{"w/2"} and @code{"h/2"}
18873 Set forward/backward mode.
18875 Available modes are:
18878 The larger the distance from the central point, the darker the image becomes.
18881 The larger the distance from the central point, the brighter the image becomes.
18882 This can be used to reverse a vignette effect, though there is no automatic
18883 detection to extract the lens @option{angle} and other settings (yet). It can
18884 also be used to create a burning effect.
18887 Default value is @samp{forward}.
18890 Set evaluation mode for the expressions (@option{angle}, @option{x0}, @option{y0}).
18892 It accepts the following values:
18895 Evaluate expressions only once during the filter initialization.
18898 Evaluate expressions for each incoming frame. This is way slower than the
18899 @samp{init} mode since it requires all the scalers to be re-computed, but it
18900 allows advanced dynamic expressions.
18903 Default value is @samp{init}.
18906 Set dithering to reduce the circular banding effects. Default is @code{1}
18910 Set vignette aspect. This setting allows one to adjust the shape of the vignette.
18911 Setting this value to the SAR of the input will make a rectangular vignetting
18912 following the dimensions of the video.
18914 Default is @code{1/1}.
18917 @subsection Expressions
18919 The @option{alpha}, @option{x0} and @option{y0} expressions can contain the
18920 following parameters.
18925 input width and height
18928 the number of input frame, starting from 0
18931 the PTS (Presentation TimeStamp) time of the filtered video frame, expressed in
18932 @var{TB} units, NAN if undefined
18935 frame rate of the input video, NAN if the input frame rate is unknown
18938 the PTS (Presentation TimeStamp) of the filtered video frame,
18939 expressed in seconds, NAN if undefined
18942 time base of the input video
18946 @subsection Examples
18950 Apply simple strong vignetting effect:
18956 Make a flickering vignetting:
18958 vignette='PI/4+random(1)*PI/50':eval=frame
18963 @section vmafmotion
18965 Obtain the average vmaf motion score of a video.
18966 It is one of the component filters of VMAF.
18968 The obtained average motion score is printed through the logging system.
18970 In the below example the input file @file{ref.mpg} is being processed and score
18974 ffmpeg -i ref.mpg -lavfi vmafmotion -f null -
18978 Stack input videos vertically.
18980 All streams must be of same pixel format and of same width.
18982 Note that this filter is faster than using @ref{overlay} and @ref{pad} filter
18983 to create same output.
18985 The filter accepts the following options:
18989 Set number of input streams. Default is 2.
18992 If set to 1, force the output to terminate when the shortest input
18993 terminates. Default value is 0.
18998 Deinterlace the input video ("w3fdif" stands for "Weston 3 Field
18999 Deinterlacing Filter").
19001 Based on the process described by Martin Weston for BBC R&D, and
19002 implemented based on the de-interlace algorithm written by Jim
19003 Easterbrook for BBC R&D, the Weston 3 field deinterlacing filter
19004 uses filter coefficients calculated by BBC R&D.
19006 This filter uses field-dominance information in frame to decide which
19007 of each pair of fields to place first in the output.
19008 If it gets it wrong use @ref{setfield} filter before @code{w3fdif} filter.
19010 There are two sets of filter coefficients, so called "simple"
19011 and "complex". Which set of filter coefficients is used can
19012 be set by passing an optional parameter:
19016 Set the interlacing filter coefficients. Accepts one of the following values:
19020 Simple filter coefficient set.
19022 More-complex filter coefficient set.
19024 Default value is @samp{complex}.
19027 Specify which frames to deinterlace. Accepts one of the following values:
19031 Deinterlace all frames,
19033 Only deinterlace frames marked as interlaced.
19036 Default value is @samp{all}.
19040 Video waveform monitor.
19042 The waveform monitor plots color component intensity. By default luminance
19043 only. Each column of the waveform corresponds to a column of pixels in the
19046 It accepts the following options:
19050 Can be either @code{row}, or @code{column}. Default is @code{column}.
19051 In row mode, the graph on the left side represents color component value 0 and
19052 the right side represents value = 255. In column mode, the top side represents
19053 color component value = 0 and bottom side represents value = 255.
19056 Set intensity. Smaller values are useful to find out how many values of the same
19057 luminance are distributed across input rows/columns.
19058 Default value is @code{0.04}. Allowed range is [0, 1].
19061 Set mirroring mode. @code{0} means unmirrored, @code{1} means mirrored.
19062 In mirrored mode, higher values will be represented on the left
19063 side for @code{row} mode and at the top for @code{column} mode. Default is
19064 @code{1} (mirrored).
19068 It accepts the following values:
19071 Presents information identical to that in the @code{parade}, except
19072 that the graphs representing color components are superimposed directly
19075 This display mode makes it easier to spot relative differences or similarities
19076 in overlapping areas of the color components that are supposed to be identical,
19077 such as neutral whites, grays, or blacks.
19080 Display separate graph for the color components side by side in
19081 @code{row} mode or one below the other in @code{column} mode.
19084 Display separate graph for the color components side by side in
19085 @code{column} mode or one below the other in @code{row} mode.
19087 Using this display mode makes it easy to spot color casts in the highlights
19088 and shadows of an image, by comparing the contours of the top and the bottom
19089 graphs of each waveform. Since whites, grays, and blacks are characterized
19090 by exactly equal amounts of red, green, and blue, neutral areas of the picture
19091 should display three waveforms of roughly equal width/height. If not, the
19092 correction is easy to perform by making level adjustments the three waveforms.
19094 Default is @code{stack}.
19096 @item components, c
19097 Set which color components to display. Default is 1, which means only luminance
19098 or red color component if input is in RGB colorspace. If is set for example to
19099 7 it will display all 3 (if) available color components.
19104 No envelope, this is default.
19107 Instant envelope, minimum and maximum values presented in graph will be easily
19108 visible even with small @code{step} value.
19111 Hold minimum and maximum values presented in graph across time. This way you
19112 can still spot out of range values without constantly looking at waveforms.
19115 Peak and instant envelope combined together.
19121 No filtering, this is default.
19124 Luma and chroma combined together.
19127 Similar as above, but shows difference between blue and red chroma.
19130 Similar as above, but use different colors.
19133 Similar as above, but again with different colors.
19136 Displays only chroma.
19139 Displays actual color value on waveform.
19142 Similar as above, but with luma showing frequency of chroma values.
19146 Set which graticule to display.
19150 Do not display graticule.
19153 Display green graticule showing legal broadcast ranges.
19156 Display orange graticule showing legal broadcast ranges.
19159 Display invert graticule showing legal broadcast ranges.
19163 Set graticule opacity.
19166 Set graticule flags.
19170 Draw numbers above lines. By default enabled.
19173 Draw dots instead of lines.
19177 Set scale used for displaying graticule.
19184 Default is digital.
19187 Set background opacity.
19190 @section weave, doubleweave
19192 The @code{weave} takes a field-based video input and join
19193 each two sequential fields into single frame, producing a new double
19194 height clip with half the frame rate and half the frame count.
19196 The @code{doubleweave} works same as @code{weave} but without
19197 halving frame rate and frame count.
19199 It accepts the following option:
19203 Set first field. Available values are:
19207 Set the frame as top-field-first.
19210 Set the frame as bottom-field-first.
19214 @subsection Examples
19218 Interlace video using @ref{select} and @ref{separatefields} filter:
19220 separatefields,select=eq(mod(n,4),0)+eq(mod(n,4),3),weave
19225 Apply the xBR high-quality magnification filter which is designed for pixel
19226 art. It follows a set of edge-detection rules, see
19227 @url{https://forums.libretro.com/t/xbr-algorithm-tutorial/123}.
19229 It accepts the following option:
19233 Set the scaling dimension: @code{2} for @code{2xBR}, @code{3} for
19234 @code{3xBR} and @code{4} for @code{4xBR}.
19235 Default is @code{3}.
19239 Pick median pixels from several input videos.
19241 The filter accepts the following options:
19245 Set number of inputs.
19246 Default is 3. Allowed range is from 3 to 255.
19247 If number of inputs is even number, than result will be mean value between two median values.
19250 Set which planes to filter. Default value is @code{15}, by which all planes are processed.
19254 Stack video inputs into custom layout.
19256 All streams must be of same pixel format.
19258 The filter accepts the following options:
19262 Set number of input streams. Default is 2.
19265 Specify layout of inputs.
19266 This option requires the desired layout configuration to be explicitly set by the user.
19267 This sets position of each video input in output. Each input
19268 is separated by '|'.
19269 The first number represents the column, and the second number represents the row.
19270 Numbers start at 0 and are separated by '_'. Optionally one can use wX and hX,
19271 where X is video input from which to take width or height.
19272 Multiple values can be used when separated by '+'. In such
19273 case values are summed together.
19275 Note that if inputs are of different sizes gaps may appear, as not all of
19276 the output video frame will be filled. Similarly, videos can overlap each
19277 other if their position doesn't leave enough space for the full frame of
19280 For 2 inputs, a default layout of @code{0_0|w0_0} is set. In all other cases,
19281 a layout must be set by the user.
19284 If set to 1, force the output to terminate when the shortest input
19285 terminates. Default value is 0.
19288 @subsection Examples
19292 Display 4 inputs into 2x2 grid.
19296 input1(0, 0) | input3(w0, 0)
19297 input2(0, h0) | input4(w0, h0)
19301 xstack=inputs=4:layout=0_0|0_h0|w0_0|w0_h0
19304 Note that if inputs are of different sizes, gaps or overlaps may occur.
19307 Display 4 inputs into 1x4 grid.
19314 input4(0, h0+h1+h2)
19318 xstack=inputs=4:layout=0_0|0_h0|0_h0+h1|0_h0+h1+h2
19321 Note that if inputs are of different widths, unused space will appear.
19324 Display 9 inputs into 3x3 grid.
19328 input1(0, 0) | input4(w0, 0) | input7(w0+w3, 0)
19329 input2(0, h0) | input5(w0, h0) | input8(w0+w3, h0)
19330 input3(0, h0+h1) | input6(w0, h0+h1) | input9(w0+w3, h0+h1)
19334 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
19337 Note that if inputs are of different sizes, gaps or overlaps may occur.
19340 Display 16 inputs into 4x4 grid.
19344 input1(0, 0) | input5(w0, 0) | input9 (w0+w4, 0) | input13(w0+w4+w8, 0)
19345 input2(0, h0) | input6(w0, h0) | input10(w0+w4, h0) | input14(w0+w4+w8, h0)
19346 input3(0, h0+h1) | input7(w0, h0+h1) | input11(w0+w4, h0+h1) | input15(w0+w4+w8, h0+h1)
19347 input4(0, h0+h1+h2)| input8(w0, h0+h1+h2)| input12(w0+w4, h0+h1+h2)| input16(w0+w4+w8, h0+h1+h2)
19351 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|
19352 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
19355 Note that if inputs are of different sizes, gaps or overlaps may occur.
19362 Deinterlace the input video ("yadif" means "yet another deinterlacing
19365 It accepts the following parameters:
19371 The interlacing mode to adopt. It accepts one of the following values:
19374 @item 0, send_frame
19375 Output one frame for each frame.
19376 @item 1, send_field
19377 Output one frame for each field.
19378 @item 2, send_frame_nospatial
19379 Like @code{send_frame}, but it skips the spatial interlacing check.
19380 @item 3, send_field_nospatial
19381 Like @code{send_field}, but it skips the spatial interlacing check.
19384 The default value is @code{send_frame}.
19387 The picture field parity assumed for the input interlaced video. It accepts one
19388 of the following values:
19392 Assume the top field is first.
19394 Assume the bottom field is first.
19396 Enable automatic detection of field parity.
19399 The default value is @code{auto}.
19400 If the interlacing is unknown or the decoder does not export this information,
19401 top field first will be assumed.
19404 Specify which frames to deinterlace. Accepts one of the following
19409 Deinterlace all frames.
19410 @item 1, interlaced
19411 Only deinterlace frames marked as interlaced.
19414 The default value is @code{all}.
19417 @section yadif_cuda
19419 Deinterlace the input video using the @ref{yadif} algorithm, but implemented
19420 in CUDA so that it can work as part of a GPU accelerated pipeline with nvdec
19423 It accepts the following parameters:
19429 The interlacing mode to adopt. It accepts one of the following values:
19432 @item 0, send_frame
19433 Output one frame for each frame.
19434 @item 1, send_field
19435 Output one frame for each field.
19436 @item 2, send_frame_nospatial
19437 Like @code{send_frame}, but it skips the spatial interlacing check.
19438 @item 3, send_field_nospatial
19439 Like @code{send_field}, but it skips the spatial interlacing check.
19442 The default value is @code{send_frame}.
19445 The picture field parity assumed for the input interlaced video. It accepts one
19446 of the following values:
19450 Assume the top field is first.
19452 Assume the bottom field is first.
19454 Enable automatic detection of field parity.
19457 The default value is @code{auto}.
19458 If the interlacing is unknown or the decoder does not export this information,
19459 top field first will be assumed.
19462 Specify which frames to deinterlace. Accepts one of the following
19467 Deinterlace all frames.
19468 @item 1, interlaced
19469 Only deinterlace frames marked as interlaced.
19472 The default value is @code{all}.
19477 Apply Zoom & Pan effect.
19479 This filter accepts the following options:
19483 Set the zoom expression. Range is 1-10. Default is 1.
19487 Set the x and y expression. Default is 0.
19490 Set the duration expression in number of frames.
19491 This sets for how many number of frames effect will last for
19492 single input image.
19495 Set the output image size, default is 'hd720'.
19498 Set the output frame rate, default is '25'.
19501 Each expression can contain the following constants:
19520 Output frame count.
19524 Last calculated 'x' and 'y' position from 'x' and 'y' expression
19525 for current input frame.
19529 'x' and 'y' of last output frame of previous input frame or 0 when there was
19530 not yet such frame (first input frame).
19533 Last calculated zoom from 'z' expression for current input frame.
19536 Last calculated zoom of last output frame of previous input frame.
19539 Number of output frames for current input frame. Calculated from 'd' expression
19540 for each input frame.
19543 number of output frames created for previous input frame
19546 Rational number: input width / input height
19549 sample aspect ratio
19552 display aspect ratio
19556 @subsection Examples
19560 Zoom-in up to 1.5 and pan at same time to some spot near center of picture:
19562 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
19566 Zoom-in up to 1.5 and pan always at center of picture:
19568 zoompan=z='min(zoom+0.0015,1.5)':d=700:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
19572 Same as above but without pausing:
19574 zoompan=z='min(max(zoom,pzoom)+0.0015,1.5)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
19580 Scale (resize) the input video, using the z.lib library:
19581 @url{https://github.com/sekrit-twc/zimg}. To enable compilation of this
19582 filter, you need to configure FFmpeg with @code{--enable-libzimg}.
19584 The zscale filter forces the output display aspect ratio to be the same
19585 as the input, by changing the output sample aspect ratio.
19587 If the input image format is different from the format requested by
19588 the next filter, the zscale filter will convert the input to the
19591 @subsection Options
19592 The filter accepts the following options.
19597 Set the output video dimension expression. Default value is the input
19600 If the @var{width} or @var{w} value is 0, the input width is used for
19601 the output. If the @var{height} or @var{h} value is 0, the input height
19602 is used for the output.
19604 If one and only one of the values is -n with n >= 1, the zscale filter
19605 will use a value that maintains the aspect ratio of the input image,
19606 calculated from the other specified dimension. After that it will,
19607 however, make sure that the calculated dimension is divisible by n and
19608 adjust the value if necessary.
19610 If both values are -n with n >= 1, the behavior will be identical to
19611 both values being set to 0 as previously detailed.
19613 See below for the list of accepted constants for use in the dimension
19617 Set the video size. For the syntax of this option, check the
19618 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
19621 Set the dither type.
19623 Possible values are:
19628 @item error_diffusion
19634 Set the resize filter type.
19636 Possible values are:
19646 Default is bilinear.
19649 Set the color range.
19651 Possible values are:
19658 Default is same as input.
19661 Set the color primaries.
19663 Possible values are:
19673 Default is same as input.
19676 Set the transfer characteristics.
19678 Possible values are:
19692 Default is same as input.
19695 Set the colorspace matrix.
19697 Possible value are:
19708 Default is same as input.
19711 Set the input color range.
19713 Possible values are:
19720 Default is same as input.
19722 @item primariesin, pin
19723 Set the input color primaries.
19725 Possible values are:
19735 Default is same as input.
19737 @item transferin, tin
19738 Set the input transfer characteristics.
19740 Possible values are:
19751 Default is same as input.
19753 @item matrixin, min
19754 Set the input colorspace matrix.
19756 Possible value are:
19768 Set the output chroma location.
19770 Possible values are:
19781 @item chromalin, cin
19782 Set the input chroma location.
19784 Possible values are:
19796 Set the nominal peak luminance.
19799 The values of the @option{w} and @option{h} options are expressions
19800 containing the following constants:
19805 The input width and height
19809 These are the same as @var{in_w} and @var{in_h}.
19813 The output (scaled) width and height
19817 These are the same as @var{out_w} and @var{out_h}
19820 The same as @var{iw} / @var{ih}
19823 input sample aspect ratio
19826 The input display aspect ratio. Calculated from @code{(iw / ih) * sar}.
19830 horizontal and vertical input chroma subsample values. For example for the
19831 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
19835 horizontal and vertical output chroma subsample values. For example for the
19836 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
19842 @c man end VIDEO FILTERS
19844 @chapter OpenCL Video Filters
19845 @c man begin OPENCL VIDEO FILTERS
19847 Below is a description of the currently available OpenCL video filters.
19849 To enable compilation of these filters you need to configure FFmpeg with
19850 @code{--enable-opencl}.
19852 Running OpenCL filters requires you to initialize a hardware device and to pass that device to all filters in any filter graph.
19855 @item -init_hw_device opencl[=@var{name}][:@var{device}[,@var{key=value}...]]
19856 Initialise a new hardware device of type @var{opencl} called @var{name}, using the
19857 given device parameters.
19859 @item -filter_hw_device @var{name}
19860 Pass the hardware device called @var{name} to all filters in any filter graph.
19864 For more detailed information see @url{https://www.ffmpeg.org/ffmpeg.html#Advanced-Video-options}
19868 Example of choosing the first device on the second platform and running avgblur_opencl filter with default parameters on it.
19870 -init_hw_device opencl=gpu:1.0 -filter_hw_device gpu -i INPUT -vf "hwupload, avgblur_opencl, hwdownload" OUTPUT
19874 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.
19876 @section avgblur_opencl
19878 Apply average blur filter.
19880 The filter accepts the following options:
19884 Set horizontal radius size.
19885 Range is @code{[1, 1024]} and default value is @code{1}.
19888 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
19891 Set vertical radius size. Range is @code{[1, 1024]} and default value is @code{0}. If zero, @code{sizeX} value will be used.
19894 @subsection Example
19898 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.
19900 -i INPUT -vf "hwupload, avgblur_opencl=3, hwdownload" OUTPUT
19904 @section boxblur_opencl
19906 Apply a boxblur algorithm to the input video.
19908 It accepts the following parameters:
19912 @item luma_radius, lr
19913 @item luma_power, lp
19914 @item chroma_radius, cr
19915 @item chroma_power, cp
19916 @item alpha_radius, ar
19917 @item alpha_power, ap
19921 A description of the accepted options follows.
19924 @item luma_radius, lr
19925 @item chroma_radius, cr
19926 @item alpha_radius, ar
19927 Set an expression for the box radius in pixels used for blurring the
19928 corresponding input plane.
19930 The radius value must be a non-negative number, and must not be
19931 greater than the value of the expression @code{min(w,h)/2} for the
19932 luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma
19935 Default value for @option{luma_radius} is "2". If not specified,
19936 @option{chroma_radius} and @option{alpha_radius} default to the
19937 corresponding value set for @option{luma_radius}.
19939 The expressions can contain the following constants:
19943 The input width and height in pixels.
19947 The input chroma image width and height in pixels.
19951 The horizontal and vertical chroma subsample values. For example, for the
19952 pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1.
19955 @item luma_power, lp
19956 @item chroma_power, cp
19957 @item alpha_power, ap
19958 Specify how many times the boxblur filter is applied to the
19959 corresponding plane.
19961 Default value for @option{luma_power} is 2. If not specified,
19962 @option{chroma_power} and @option{alpha_power} default to the
19963 corresponding value set for @option{luma_power}.
19965 A value of 0 will disable the effect.
19968 @subsection Examples
19970 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.
19974 Apply a boxblur filter with the luma, chroma, and alpha radius
19975 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.
19977 -i INPUT -vf "hwupload, boxblur_opencl=luma_radius=2:luma_power=3, hwdownload" OUTPUT
19978 -i INPUT -vf "hwupload, boxblur_opencl=2:3, hwdownload" OUTPUT
19982 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.
19984 For the luma plane, a 2x2 box radius will be run once.
19986 For the chroma plane, a 4x4 box radius will be run 5 times.
19988 For the alpha plane, a 3x3 box radius will be run 7 times.
19990 -i INPUT -vf "hwupload, boxblur_opencl=2:1:4:5:3:7, hwdownload" OUTPUT
19994 @section convolution_opencl
19996 Apply convolution of 3x3, 5x5, 7x7 matrix.
19998 The filter accepts the following options:
20005 Set matrix for each plane.
20006 Matrix is sequence of 9, 25 or 49 signed numbers.
20007 Default value for each plane is @code{0 0 0 0 1 0 0 0 0}.
20013 Set multiplier for calculated value for each plane.
20014 If unset or 0, it will be sum of all matrix elements.
20015 The option value must be a float number greater or equal to @code{0.0}. Default value is @code{1.0}.
20021 Set bias for each plane. This value is added to the result of the multiplication.
20022 Useful for making the overall image brighter or darker.
20023 The option value must be a float number greater or equal to @code{0.0}. Default value is @code{0.0}.
20027 @subsection Examples
20033 -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
20039 -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
20043 Apply edge enhance:
20045 -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
20051 -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
20055 Apply laplacian edge detector which includes diagonals:
20057 -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
20063 -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
20067 @section dilation_opencl
20069 Apply dilation effect to the video.
20071 This filter replaces the pixel by the local(3x3) maximum.
20073 It accepts the following options:
20080 Limit the maximum change for each plane. Range is @code{[0, 65535]} and default value is @code{65535}.
20081 If @code{0}, plane will remain unchanged.
20084 Flag which specifies the pixel to refer to.
20085 Range is @code{[0, 255]} and default value is @code{255}, i.e. all eight pixels are used.
20087 Flags to local 3x3 coordinates region centered on @code{x}:
20096 @subsection Example
20100 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.
20102 -i INPUT -vf "hwupload, dilation_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT
20106 @section erosion_opencl
20108 Apply erosion effect to the video.
20110 This filter replaces the pixel by the local(3x3) minimum.
20112 It accepts the following options:
20119 Limit the maximum change for each plane. Range is @code{[0, 65535]} and default value is @code{65535}.
20120 If @code{0}, plane will remain unchanged.
20123 Flag which specifies the pixel to refer to.
20124 Range is @code{[0, 255]} and default value is @code{255}, i.e. all eight pixels are used.
20126 Flags to local 3x3 coordinates region centered on @code{x}:
20135 @subsection Example
20139 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.
20141 -i INPUT -vf "hwupload, erosion_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT
20145 @section colorkey_opencl
20146 RGB colorspace color keying.
20148 The filter accepts the following options:
20152 The color which will be replaced with transparency.
20155 Similarity percentage with the key color.
20157 0.01 matches only the exact key color, while 1.0 matches everything.
20162 0.0 makes pixels either fully transparent, or not transparent at all.
20164 Higher values result in semi-transparent pixels, with a higher transparency
20165 the more similar the pixels color is to the key color.
20168 @subsection Examples
20172 Make every semi-green pixel in the input transparent with some slight blending:
20174 -i INPUT -vf "hwupload, colorkey_opencl=green:0.3:0.1, hwdownload" OUTPUT
20178 @section deshake_opencl
20179 Feature-point based video stabilization filter.
20181 The filter accepts the following options:
20185 Simulates a tripod by preventing any camera movement whatsoever from the original frame. Defaults to @code{0}.
20188 Whether or not additional debug info should be displayed, both in the processed output and in the console.
20190 Note that in order to see console debug output you will also need to pass @code{-v verbose} to ffmpeg.
20192 Viewing point matches in the output video is only supported for RGB input.
20194 Defaults to @code{0}.
20196 @item adaptive_crop
20197 Whether or not to do a tiny bit of cropping at the borders to cut down on the amount of mirrored pixels.
20199 Defaults to @code{1}.
20201 @item refine_features
20202 Whether or not feature points should be refined at a sub-pixel level.
20204 This can be turned off for a slight performance gain at the cost of precision.
20206 Defaults to @code{1}.
20208 @item smooth_strength
20209 The strength of the smoothing applied to the camera path from @code{0.0} to @code{1.0}.
20211 @code{1.0} is the maximum smoothing strength while values less than that result in less smoothing.
20213 @code{0.0} causes the filter to adaptively choose a smoothing strength on a per-frame basis.
20215 Defaults to @code{0.0}.
20217 @item smooth_window_multiplier
20218 Controls the size of the smoothing window (the number of frames buffered to determine motion information from).
20220 The size of the smoothing window is determined by multiplying the framerate of the video by this number.
20222 Acceptable values range from @code{0.1} to @code{10.0}.
20224 Larger values increase the amount of motion data available for determining how to smooth the camera path,
20225 potentially improving smoothness, but also increase latency and memory usage.
20227 Defaults to @code{2.0}.
20231 @subsection Examples
20235 Stabilize a video with a fixed, medium smoothing strength:
20237 -i INPUT -vf "hwupload, deshake_opencl=smooth_strength=0.5, hwdownload" OUTPUT
20241 Stabilize a video with debugging (both in console and in rendered video):
20243 -i INPUT -filter_complex "[0:v]format=rgba, hwupload, deshake_opencl=debug=1, hwdownload, format=rgba, format=yuv420p" -v verbose OUTPUT
20247 @section nlmeans_opencl
20249 Non-local Means denoise filter through OpenCL, this filter accepts same options as @ref{nlmeans}.
20251 @section overlay_opencl
20253 Overlay one video on top of another.
20255 It takes two inputs and has one output. The first input is the "main" video on which the second input is overlaid.
20256 This filter requires same memory layout for all the inputs. So, format conversion may be needed.
20258 The filter accepts the following options:
20263 Set the x coordinate of the overlaid video on the main video.
20264 Default value is @code{0}.
20267 Set the x coordinate of the overlaid video on the main video.
20268 Default value is @code{0}.
20272 @subsection Examples
20276 Overlay an image LOGO at the top-left corner of the INPUT video. Both inputs are yuv420p format.
20278 -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuv420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT
20281 The inputs have same memory layout for color channels , the overlay has additional alpha plane, like INPUT is yuv420p, and the LOGO is yuva420p.
20283 -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuva420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT
20288 @section prewitt_opencl
20290 Apply the Prewitt operator (@url{https://en.wikipedia.org/wiki/Prewitt_operator}) to input video stream.
20292 The filter accepts the following option:
20296 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
20299 Set value which will be multiplied with filtered result.
20300 Range is @code{[0.0, 65535]} and default value is @code{1.0}.
20303 Set value which will be added to filtered result.
20304 Range is @code{[-65535, 65535]} and default value is @code{0.0}.
20307 @subsection Example
20311 Apply the Prewitt operator with scale set to 2 and delta set to 10.
20313 -i INPUT -vf "hwupload, prewitt_opencl=scale=2:delta=10, hwdownload" OUTPUT
20317 @section roberts_opencl
20318 Apply the Roberts cross operator (@url{https://en.wikipedia.org/wiki/Roberts_cross}) to input video stream.
20320 The filter accepts the following option:
20324 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
20327 Set value which will be multiplied with filtered result.
20328 Range is @code{[0.0, 65535]} and default value is @code{1.0}.
20331 Set value which will be added to filtered result.
20332 Range is @code{[-65535, 65535]} and default value is @code{0.0}.
20335 @subsection Example
20339 Apply the Roberts cross operator with scale set to 2 and delta set to 10
20341 -i INPUT -vf "hwupload, roberts_opencl=scale=2:delta=10, hwdownload" OUTPUT
20345 @section sobel_opencl
20347 Apply the Sobel operator (@url{https://en.wikipedia.org/wiki/Sobel_operator}) to input video stream.
20349 The filter accepts the following option:
20353 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
20356 Set value which will be multiplied with filtered result.
20357 Range is @code{[0.0, 65535]} and default value is @code{1.0}.
20360 Set value which will be added to filtered result.
20361 Range is @code{[-65535, 65535]} and default value is @code{0.0}.
20364 @subsection Example
20368 Apply sobel operator with scale set to 2 and delta set to 10
20370 -i INPUT -vf "hwupload, sobel_opencl=scale=2:delta=10, hwdownload" OUTPUT
20374 @section tonemap_opencl
20376 Perform HDR(PQ/HLG) to SDR conversion with tone-mapping.
20378 It accepts the following parameters:
20382 Specify the tone-mapping operator to be used. Same as tonemap option in @ref{tonemap}.
20385 Tune the tone mapping algorithm. same as param option in @ref{tonemap}.
20388 Apply desaturation for highlights that exceed this level of brightness. The
20389 higher the parameter, the more color information will be preserved. This
20390 setting helps prevent unnaturally blown-out colors for super-highlights, by
20391 (smoothly) turning into white instead. This makes images feel more natural,
20392 at the cost of reducing information about out-of-range colors.
20394 The default value is 0.5, and the algorithm here is a little different from
20395 the cpu version tonemap currently. A setting of 0.0 disables this option.
20398 The tonemapping algorithm parameters is fine-tuned per each scene. And a threshold
20399 is used to detect whether the scene has changed or not. If the distance between
20400 the current frame average brightness and the current running average exceeds
20401 a threshold value, we would re-calculate scene average and peak brightness.
20402 The default value is 0.2.
20405 Specify the output pixel format.
20407 Currently supported formats are:
20414 Set the output color range.
20416 Possible values are:
20422 Default is same as input.
20425 Set the output color primaries.
20427 Possible values are:
20433 Default is same as input.
20436 Set the output transfer characteristics.
20438 Possible values are:
20447 Set the output colorspace matrix.
20449 Possible value are:
20455 Default is same as input.
20459 @subsection Example
20463 Convert HDR(PQ/HLG) video to bt2020-transfer-characteristic p010 format using linear operator.
20465 -i INPUT -vf "format=p010,hwupload,tonemap_opencl=t=bt2020:tonemap=linear:format=p010,hwdownload,format=p010" OUTPUT
20469 @section unsharp_opencl
20471 Sharpen or blur the input video.
20473 It accepts the following parameters:
20476 @item luma_msize_x, lx
20477 Set the luma matrix horizontal size.
20478 Range is @code{[1, 23]} and default value is @code{5}.
20480 @item luma_msize_y, ly
20481 Set the luma matrix vertical size.
20482 Range is @code{[1, 23]} and default value is @code{5}.
20484 @item luma_amount, la
20485 Set the luma effect strength.
20486 Range is @code{[-10, 10]} and default value is @code{1.0}.
20488 Negative values will blur the input video, while positive values will
20489 sharpen it, a value of zero will disable the effect.
20491 @item chroma_msize_x, cx
20492 Set the chroma matrix horizontal size.
20493 Range is @code{[1, 23]} and default value is @code{5}.
20495 @item chroma_msize_y, cy
20496 Set the chroma matrix vertical size.
20497 Range is @code{[1, 23]} and default value is @code{5}.
20499 @item chroma_amount, ca
20500 Set the chroma effect strength.
20501 Range is @code{[-10, 10]} and default value is @code{0.0}.
20503 Negative values will blur the input video, while positive values will
20504 sharpen it, a value of zero will disable the effect.
20508 All parameters are optional and default to the equivalent of the
20509 string '5:5:1.0:5:5:0.0'.
20511 @subsection Examples
20515 Apply strong luma sharpen effect:
20517 -i INPUT -vf "hwupload, unsharp_opencl=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5, hwdownload" OUTPUT
20521 Apply a strong blur of both luma and chroma parameters:
20523 -i INPUT -vf "hwupload, unsharp_opencl=7:7:-2:7:7:-2, hwdownload" OUTPUT
20527 @c man end OPENCL VIDEO FILTERS
20529 @chapter Video Sources
20530 @c man begin VIDEO SOURCES
20532 Below is a description of the currently available video sources.
20536 Buffer video frames, and make them available to the filter chain.
20538 This source is mainly intended for a programmatic use, in particular
20539 through the interface defined in @file{libavfilter/vsrc_buffer.h}.
20541 It accepts the following parameters:
20546 Specify the size (width and height) of the buffered video frames. For the
20547 syntax of this option, check the
20548 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
20551 The input video width.
20554 The input video height.
20557 A string representing the pixel format of the buffered video frames.
20558 It may be a number corresponding to a pixel format, or a pixel format
20562 Specify the timebase assumed by the timestamps of the buffered frames.
20565 Specify the frame rate expected for the video stream.
20567 @item pixel_aspect, sar
20568 The sample (pixel) aspect ratio of the input video.
20571 Specify the optional parameters to be used for the scale filter which
20572 is automatically inserted when an input change is detected in the
20573 input size or format.
20575 @item hw_frames_ctx
20576 When using a hardware pixel format, this should be a reference to an
20577 AVHWFramesContext describing input frames.
20582 buffer=width=320:height=240:pix_fmt=yuv410p:time_base=1/24:sar=1
20585 will instruct the source to accept video frames with size 320x240 and
20586 with format "yuv410p", assuming 1/24 as the timestamps timebase and
20587 square pixels (1:1 sample aspect ratio).
20588 Since the pixel format with name "yuv410p" corresponds to the number 6
20589 (check the enum AVPixelFormat definition in @file{libavutil/pixfmt.h}),
20590 this example corresponds to:
20592 buffer=size=320x240:pixfmt=6:time_base=1/24:pixel_aspect=1/1
20595 Alternatively, the options can be specified as a flat string, but this
20596 syntax is deprecated:
20598 @var{width}:@var{height}:@var{pix_fmt}:@var{time_base.num}:@var{time_base.den}:@var{pixel_aspect.num}:@var{pixel_aspect.den}[:@var{sws_param}]
20602 Create a pattern generated by an elementary cellular automaton.
20604 The initial state of the cellular automaton can be defined through the
20605 @option{filename} and @option{pattern} options. If such options are
20606 not specified an initial state is created randomly.
20608 At each new frame a new row in the video is filled with the result of
20609 the cellular automaton next generation. The behavior when the whole
20610 frame is filled is defined by the @option{scroll} option.
20612 This source accepts the following options:
20616 Read the initial cellular automaton state, i.e. the starting row, from
20617 the specified file.
20618 In the file, each non-whitespace character is considered an alive
20619 cell, a newline will terminate the row, and further characters in the
20620 file will be ignored.
20623 Read the initial cellular automaton state, i.e. the starting row, from
20624 the specified string.
20626 Each non-whitespace character in the string is considered an alive
20627 cell, a newline will terminate the row, and further characters in the
20628 string will be ignored.
20631 Set the video rate, that is the number of frames generated per second.
20634 @item random_fill_ratio, ratio
20635 Set the random fill ratio for the initial cellular automaton row. It
20636 is a floating point number value ranging from 0 to 1, defaults to
20639 This option is ignored when a file or a pattern is specified.
20641 @item random_seed, seed
20642 Set the seed for filling randomly the initial row, must be an integer
20643 included between 0 and UINT32_MAX. If not specified, or if explicitly
20644 set to -1, the filter will try to use a good random seed on a best
20648 Set the cellular automaton rule, it is a number ranging from 0 to 255.
20649 Default value is 110.
20652 Set the size of the output video. For the syntax of this option, check the
20653 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
20655 If @option{filename} or @option{pattern} is specified, the size is set
20656 by default to the width of the specified initial state row, and the
20657 height is set to @var{width} * PHI.
20659 If @option{size} is set, it must contain the width of the specified
20660 pattern string, and the specified pattern will be centered in the
20663 If a filename or a pattern string is not specified, the size value
20664 defaults to "320x518" (used for a randomly generated initial state).
20667 If set to 1, scroll the output upward when all the rows in the output
20668 have been already filled. If set to 0, the new generated row will be
20669 written over the top row just after the bottom row is filled.
20672 @item start_full, full
20673 If set to 1, completely fill the output with generated rows before
20674 outputting the first frame.
20675 This is the default behavior, for disabling set the value to 0.
20678 If set to 1, stitch the left and right row edges together.
20679 This is the default behavior, for disabling set the value to 0.
20682 @subsection Examples
20686 Read the initial state from @file{pattern}, and specify an output of
20689 cellauto=f=pattern:s=200x400
20693 Generate a random initial row with a width of 200 cells, with a fill
20696 cellauto=ratio=2/3:s=200x200
20700 Create a pattern generated by rule 18 starting by a single alive cell
20701 centered on an initial row with width 100:
20703 cellauto=p=@@:s=100x400:full=0:rule=18
20707 Specify a more elaborated initial pattern:
20709 cellauto=p='@@@@ @@ @@@@':s=100x400:full=0:rule=18
20714 @anchor{coreimagesrc}
20715 @section coreimagesrc
20716 Video source generated on GPU using Apple's CoreImage API on OSX.
20718 This video source is a specialized version of the @ref{coreimage} video filter.
20719 Use a core image generator at the beginning of the applied filterchain to
20720 generate the content.
20722 The coreimagesrc video source accepts the following options:
20724 @item list_generators
20725 List all available generators along with all their respective options as well as
20726 possible minimum and maximum values along with the default values.
20728 list_generators=true
20732 Specify the size of the sourced video. For the syntax of this option, check the
20733 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
20734 The default value is @code{320x240}.
20737 Specify the frame rate of the sourced video, as the number of frames
20738 generated per second. It has to be a string in the format
20739 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
20740 number or a valid video frame rate abbreviation. The default value is
20744 Set the sample aspect ratio of the sourced video.
20747 Set the duration of the sourced video. See
20748 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
20749 for the accepted syntax.
20751 If not specified, or the expressed duration is negative, the video is
20752 supposed to be generated forever.
20755 Additionally, all options of the @ref{coreimage} video filter are accepted.
20756 A complete filterchain can be used for further processing of the
20757 generated input without CPU-HOST transfer. See @ref{coreimage} documentation
20758 and examples for details.
20760 @subsection Examples
20765 Use CIQRCodeGenerator to create a QR code for the FFmpeg homepage,
20766 given as complete and escaped command-line for Apple's standard bash shell:
20768 ffmpeg -f lavfi -i coreimagesrc=s=100x100:filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png
20770 This example is equivalent to the QRCode example of @ref{coreimage} without the
20771 need for a nullsrc video source.
20775 @section mandelbrot
20777 Generate a Mandelbrot set fractal, and progressively zoom towards the
20778 point specified with @var{start_x} and @var{start_y}.
20780 This source accepts the following options:
20785 Set the terminal pts value. Default value is 400.
20788 Set the terminal scale value.
20789 Must be a floating point value. Default value is 0.3.
20792 Set the inner coloring mode, that is the algorithm used to draw the
20793 Mandelbrot fractal internal region.
20795 It shall assume one of the following values:
20800 Show time until convergence.
20802 Set color based on point closest to the origin of the iterations.
20807 Default value is @var{mincol}.
20810 Set the bailout value. Default value is 10.0.
20813 Set the maximum of iterations performed by the rendering
20814 algorithm. Default value is 7189.
20817 Set outer coloring mode.
20818 It shall assume one of following values:
20820 @item iteration_count
20821 Set iteration count mode.
20822 @item normalized_iteration_count
20823 set normalized iteration count mode.
20825 Default value is @var{normalized_iteration_count}.
20828 Set frame rate, expressed as number of frames per second. Default
20832 Set frame size. For the syntax of this option, check the @ref{video size syntax,,"Video
20833 size" section in the ffmpeg-utils manual,ffmpeg-utils}. Default value is "640x480".
20836 Set the initial scale value. Default value is 3.0.
20839 Set the initial x position. Must be a floating point value between
20840 -100 and 100. Default value is -0.743643887037158704752191506114774.
20843 Set the initial y position. Must be a floating point value between
20844 -100 and 100. Default value is -0.131825904205311970493132056385139.
20849 Generate various test patterns, as generated by the MPlayer test filter.
20851 The size of the generated video is fixed, and is 256x256.
20852 This source is useful in particular for testing encoding features.
20854 This source accepts the following options:
20859 Specify the frame rate of the sourced video, as the number of frames
20860 generated per second. It has to be a string in the format
20861 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
20862 number or a valid video frame rate abbreviation. The default value is
20866 Set the duration of the sourced video. See
20867 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
20868 for the accepted syntax.
20870 If not specified, or the expressed duration is negative, the video is
20871 supposed to be generated forever.
20875 Set the number or the name of the test to perform. Supported tests are:
20891 Default value is "all", which will cycle through the list of all tests.
20896 mptestsrc=t=dc_luma
20899 will generate a "dc_luma" test pattern.
20901 @section frei0r_src
20903 Provide a frei0r source.
20905 To enable compilation of this filter you need to install the frei0r
20906 header and configure FFmpeg with @code{--enable-frei0r}.
20908 This source accepts the following parameters:
20913 The size of the video to generate. For the syntax of this option, check the
20914 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
20917 The framerate of the generated video. It may be a string of the form
20918 @var{num}/@var{den} or a frame rate abbreviation.
20921 The name to the frei0r source to load. For more information regarding frei0r and
20922 how to set the parameters, read the @ref{frei0r} section in the video filters
20925 @item filter_params
20926 A '|'-separated list of parameters to pass to the frei0r source.
20930 For example, to generate a frei0r partik0l source with size 200x200
20931 and frame rate 10 which is overlaid on the overlay filter main input:
20933 frei0r_src=size=200x200:framerate=10:filter_name=partik0l:filter_params=1234 [overlay]; [in][overlay] overlay
20938 Generate a life pattern.
20940 This source is based on a generalization of John Conway's life game.
20942 The sourced input represents a life grid, each pixel represents a cell
20943 which can be in one of two possible states, alive or dead. Every cell
20944 interacts with its eight neighbours, which are the cells that are
20945 horizontally, vertically, or diagonally adjacent.
20947 At each interaction the grid evolves according to the adopted rule,
20948 which specifies the number of neighbor alive cells which will make a
20949 cell stay alive or born. The @option{rule} option allows one to specify
20952 This source accepts the following options:
20956 Set the file from which to read the initial grid state. In the file,
20957 each non-whitespace character is considered an alive cell, and newline
20958 is used to delimit the end of each row.
20960 If this option is not specified, the initial grid is generated
20964 Set the video rate, that is the number of frames generated per second.
20967 @item random_fill_ratio, ratio
20968 Set the random fill ratio for the initial random grid. It is a
20969 floating point number value ranging from 0 to 1, defaults to 1/PHI.
20970 It is ignored when a file is specified.
20972 @item random_seed, seed
20973 Set the seed for filling the initial random grid, must be an integer
20974 included between 0 and UINT32_MAX. If not specified, or if explicitly
20975 set to -1, the filter will try to use a good random seed on a best
20981 A rule can be specified with a code of the kind "S@var{NS}/B@var{NB}",
20982 where @var{NS} and @var{NB} are sequences of numbers in the range 0-8,
20983 @var{NS} specifies the number of alive neighbor cells which make a
20984 live cell stay alive, and @var{NB} the number of alive neighbor cells
20985 which make a dead cell to become alive (i.e. to "born").
20986 "s" and "b" can be used in place of "S" and "B", respectively.
20988 Alternatively a rule can be specified by an 18-bits integer. The 9
20989 high order bits are used to encode the next cell state if it is alive
20990 for each number of neighbor alive cells, the low order bits specify
20991 the rule for "borning" new cells. Higher order bits encode for an
20992 higher number of neighbor cells.
20993 For example the number 6153 = @code{(12<<9)+9} specifies a stay alive
20994 rule of 12 and a born rule of 9, which corresponds to "S23/B03".
20996 Default value is "S23/B3", which is the original Conway's game of life
20997 rule, and will keep a cell alive if it has 2 or 3 neighbor alive
20998 cells, and will born a new cell if there are three alive cells around
21002 Set the size of the output video. For the syntax of this option, check the
21003 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
21005 If @option{filename} is specified, the size is set by default to the
21006 same size of the input file. If @option{size} is set, it must contain
21007 the size specified in the input file, and the initial grid defined in
21008 that file is centered in the larger resulting area.
21010 If a filename is not specified, the size value defaults to "320x240"
21011 (used for a randomly generated initial grid).
21014 If set to 1, stitch the left and right grid edges together, and the
21015 top and bottom edges also. Defaults to 1.
21018 Set cell mold speed. If set, a dead cell will go from @option{death_color} to
21019 @option{mold_color} with a step of @option{mold}. @option{mold} can have a
21020 value from 0 to 255.
21023 Set the color of living (or new born) cells.
21026 Set the color of dead cells. If @option{mold} is set, this is the first color
21027 used to represent a dead cell.
21030 Set mold color, for definitely dead and moldy cells.
21032 For the syntax of these 3 color options, check the @ref{color syntax,,"Color" section in the
21033 ffmpeg-utils manual,ffmpeg-utils}.
21036 @subsection Examples
21040 Read a grid from @file{pattern}, and center it on a grid of size
21043 life=f=pattern:s=300x300
21047 Generate a random grid of size 200x200, with a fill ratio of 2/3:
21049 life=ratio=2/3:s=200x200
21053 Specify a custom rule for evolving a randomly generated grid:
21059 Full example with slow death effect (mold) using @command{ffplay}:
21061 ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16
21068 @anchor{haldclutsrc}
21071 @anchor{pal100bars}
21072 @anchor{rgbtestsrc}
21074 @anchor{smptehdbars}
21077 @anchor{yuvtestsrc}
21078 @section allrgb, allyuv, color, haldclutsrc, nullsrc, pal75bars, pal100bars, rgbtestsrc, smptebars, smptehdbars, testsrc, testsrc2, yuvtestsrc
21080 The @code{allrgb} source returns frames of size 4096x4096 of all rgb colors.
21082 The @code{allyuv} source returns frames of size 4096x4096 of all yuv colors.
21084 The @code{color} source provides an uniformly colored input.
21086 The @code{haldclutsrc} source provides an identity Hald CLUT. See also
21087 @ref{haldclut} filter.
21089 The @code{nullsrc} source returns unprocessed video frames. It is
21090 mainly useful to be employed in analysis / debugging tools, or as the
21091 source for filters which ignore the input data.
21093 The @code{pal75bars} source generates a color bars pattern, based on
21094 EBU PAL recommendations with 75% color levels.
21096 The @code{pal100bars} source generates a color bars pattern, based on
21097 EBU PAL recommendations with 100% color levels.
21099 The @code{rgbtestsrc} source generates an RGB test pattern useful for
21100 detecting RGB vs BGR issues. You should see a red, green and blue
21101 stripe from top to bottom.
21103 The @code{smptebars} source generates a color bars pattern, based on
21104 the SMPTE Engineering Guideline EG 1-1990.
21106 The @code{smptehdbars} source generates a color bars pattern, based on
21107 the SMPTE RP 219-2002.
21109 The @code{testsrc} source generates a test video pattern, showing a
21110 color pattern, a scrolling gradient and a timestamp. This is mainly
21111 intended for testing purposes.
21113 The @code{testsrc2} source is similar to testsrc, but supports more
21114 pixel formats instead of just @code{rgb24}. This allows using it as an
21115 input for other tests without requiring a format conversion.
21117 The @code{yuvtestsrc} source generates an YUV test pattern. You should
21118 see a y, cb and cr stripe from top to bottom.
21120 The sources accept the following parameters:
21125 Specify the level of the Hald CLUT, only available in the @code{haldclutsrc}
21126 source. A level of @code{N} generates a picture of @code{N*N*N} by @code{N*N*N}
21127 pixels to be used as identity matrix for 3D lookup tables. Each component is
21128 coded on a @code{1/(N*N)} scale.
21131 Specify the color of the source, only available in the @code{color}
21132 source. For the syntax of this option, check the
21133 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
21136 Specify the size of the sourced video. For the syntax of this option, check the
21137 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
21138 The default value is @code{320x240}.
21140 This option is not available with the @code{allrgb}, @code{allyuv}, and
21141 @code{haldclutsrc} filters.
21144 Specify the frame rate of the sourced video, as the number of frames
21145 generated per second. It has to be a string in the format
21146 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
21147 number or a valid video frame rate abbreviation. The default value is
21151 Set the duration of the sourced video. See
21152 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
21153 for the accepted syntax.
21155 If not specified, or the expressed duration is negative, the video is
21156 supposed to be generated forever.
21159 Set the sample aspect ratio of the sourced video.
21162 Specify the alpha (opacity) of the background, only available in the
21163 @code{testsrc2} source. The value must be between 0 (fully transparent) and
21164 255 (fully opaque, the default).
21167 Set the number of decimals to show in the timestamp, only available in the
21168 @code{testsrc} source.
21170 The displayed timestamp value will correspond to the original
21171 timestamp value multiplied by the power of 10 of the specified
21172 value. Default value is 0.
21175 @subsection Examples
21179 Generate a video with a duration of 5.3 seconds, with size
21180 176x144 and a frame rate of 10 frames per second:
21182 testsrc=duration=5.3:size=qcif:rate=10
21186 The following graph description will generate a red source
21187 with an opacity of 0.2, with size "qcif" and a frame rate of 10
21190 color=c=red@@0.2:s=qcif:r=10
21194 If the input content is to be ignored, @code{nullsrc} can be used. The
21195 following command generates noise in the luminance plane by employing
21196 the @code{geq} filter:
21198 nullsrc=s=256x256, geq=random(1)*255:128:128
21202 @subsection Commands
21204 The @code{color} source supports the following commands:
21208 Set the color of the created image. Accepts the same syntax of the
21209 corresponding @option{color} option.
21214 Generate video using an OpenCL program.
21219 OpenCL program source file.
21222 Kernel name in program.
21225 Size of frames to generate. This must be set.
21228 Pixel format to use for the generated frames. This must be set.
21231 Number of frames generated every second. Default value is '25'.
21235 For details of how the program loading works, see the @ref{program_opencl}
21242 Generate a colour ramp by setting pixel values from the position of the pixel
21243 in the output image. (Note that this will work with all pixel formats, but
21244 the generated output will not be the same.)
21246 __kernel void ramp(__write_only image2d_t dst,
21247 unsigned int index)
21249 int2 loc = (int2)(get_global_id(0), get_global_id(1));
21252 val.xy = val.zw = convert_float2(loc) / convert_float2(get_image_dim(dst));
21254 write_imagef(dst, loc, val);
21259 Generate a Sierpinski carpet pattern, panning by a single pixel each frame.
21261 __kernel void sierpinski_carpet(__write_only image2d_t dst,
21262 unsigned int index)
21264 int2 loc = (int2)(get_global_id(0), get_global_id(1));
21266 float4 value = 0.0f;
21267 int x = loc.x + index;
21268 int y = loc.y + index;
21269 while (x > 0 || y > 0) {
21270 if (x % 3 == 1 && y % 3 == 1) {
21278 write_imagef(dst, loc, value);
21284 @section sierpinski
21286 Generate a Sierpinski carpet/triangle fractal, and randomly pan around.
21288 This source accepts the following options:
21292 Set frame size. For the syntax of this option, check the @ref{video size syntax,,"Video
21293 size" section in the ffmpeg-utils manual,ffmpeg-utils}. Default value is "640x480".
21296 Set frame rate, expressed as number of frames per second. Default
21300 Set seed which is used for random panning.
21303 Set max jump for single pan destination. Allowed range is from 1 to 10000.
21306 Set fractal type, can be default @code{carpet} or @code{triangle}.
21309 @c man end VIDEO SOURCES
21311 @chapter Video Sinks
21312 @c man begin VIDEO SINKS
21314 Below is a description of the currently available video sinks.
21316 @section buffersink
21318 Buffer video frames, and make them available to the end of the filter
21321 This sink is mainly intended for programmatic use, in particular
21322 through the interface defined in @file{libavfilter/buffersink.h}
21323 or the options system.
21325 It accepts a pointer to an AVBufferSinkContext structure, which
21326 defines the incoming buffers' formats, to be passed as the opaque
21327 parameter to @code{avfilter_init_filter} for initialization.
21331 Null video sink: do absolutely nothing with the input video. It is
21332 mainly useful as a template and for use in analysis / debugging
21335 @c man end VIDEO SINKS
21337 @chapter Multimedia Filters
21338 @c man begin MULTIMEDIA FILTERS
21340 Below is a description of the currently available multimedia filters.
21344 Convert input audio to a video output, displaying the audio bit scope.
21346 The filter accepts the following options:
21350 Set frame rate, expressed as number of frames per second. Default
21354 Specify the video size for the output. For the syntax of this option, check the
21355 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
21356 Default value is @code{1024x256}.
21359 Specify list of colors separated by space or by '|' which will be used to
21360 draw channels. Unrecognized or missing colors will be replaced
21364 @section ahistogram
21366 Convert input audio to a video output, displaying the volume histogram.
21368 The filter accepts the following options:
21372 Specify how histogram is calculated.
21374 It accepts the following values:
21377 Use single histogram for all channels.
21379 Use separate histogram for each channel.
21381 Default is @code{single}.
21384 Set frame rate, expressed as number of frames per second. Default
21388 Specify the video size for the output. For the syntax of this option, check the
21389 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
21390 Default value is @code{hd720}.
21395 It accepts the following values:
21406 reverse logarithmic
21408 Default is @code{log}.
21411 Set amplitude scale.
21413 It accepts the following values:
21420 Default is @code{log}.
21423 Set how much frames to accumulate in histogram.
21424 Default is 1. Setting this to -1 accumulates all frames.
21427 Set histogram ratio of window height.
21430 Set sonogram sliding.
21432 It accepts the following values:
21435 replace old rows with new ones.
21437 scroll from top to bottom.
21439 Default is @code{replace}.
21442 @section aphasemeter
21444 Measures phase of input audio, which is exported as metadata @code{lavfi.aphasemeter.phase},
21445 representing mean phase of current audio frame. A video output can also be produced and is
21446 enabled by default. The audio is passed through as first output.
21448 Audio will be rematrixed to stereo if it has a different channel layout. Phase value is in
21449 range @code{[-1, 1]} where @code{-1} means left and right channels are completely out of phase
21450 and @code{1} means channels are in phase.
21452 The filter accepts the following options, all related to its video output:
21456 Set the output frame rate. Default value is @code{25}.
21459 Set the video size for the output. For the syntax of this option, check the
21460 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
21461 Default value is @code{800x400}.
21466 Specify the red, green, blue contrast. Default values are @code{2},
21467 @code{7} and @code{1}.
21468 Allowed range is @code{[0, 255]}.
21471 Set color which will be used for drawing median phase. If color is
21472 @code{none} which is default, no median phase value will be drawn.
21475 Enable video output. Default is enabled.
21478 @section avectorscope
21480 Convert input audio to a video output, representing the audio vector
21483 The filter is used to measure the difference between channels of stereo
21484 audio stream. A monaural signal, consisting of identical left and right
21485 signal, results in straight vertical line. Any stereo separation is visible
21486 as a deviation from this line, creating a Lissajous figure.
21487 If the straight (or deviation from it) but horizontal line appears this
21488 indicates that the left and right channels are out of phase.
21490 The filter accepts the following options:
21494 Set the vectorscope mode.
21496 Available values are:
21499 Lissajous rotated by 45 degrees.
21502 Same as above but not rotated.
21505 Shape resembling half of circle.
21508 Default value is @samp{lissajous}.
21511 Set the video size for the output. For the syntax of this option, check the
21512 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
21513 Default value is @code{400x400}.
21516 Set the output frame rate. Default value is @code{25}.
21522 Specify the red, green, blue and alpha contrast. Default values are @code{40},
21523 @code{160}, @code{80} and @code{255}.
21524 Allowed range is @code{[0, 255]}.
21530 Specify the red, green, blue and alpha fade. Default values are @code{15},
21531 @code{10}, @code{5} and @code{5}.
21532 Allowed range is @code{[0, 255]}.
21535 Set the zoom factor. Default value is @code{1}. Allowed range is @code{[0, 10]}.
21536 Values lower than @var{1} will auto adjust zoom factor to maximal possible value.
21539 Set the vectorscope drawing mode.
21541 Available values are:
21544 Draw dot for each sample.
21547 Draw line between previous and current sample.
21550 Default value is @samp{dot}.
21553 Specify amplitude scale of audio samples.
21555 Available values are:
21571 Swap left channel axis with right channel axis.
21581 Mirror only x axis.
21584 Mirror only y axis.
21592 @subsection Examples
21596 Complete example using @command{ffplay}:
21598 ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
21599 [a] avectorscope=zoom=1.3:rc=2:gc=200:bc=10:rf=1:gf=8:bf=7 [out0]'
21603 @section bench, abench
21605 Benchmark part of a filtergraph.
21607 The filter accepts the following options:
21611 Start or stop a timer.
21613 Available values are:
21616 Get the current time, set it as frame metadata (using the key
21617 @code{lavfi.bench.start_time}), and forward the frame to the next filter.
21620 Get the current time and fetch the @code{lavfi.bench.start_time} metadata from
21621 the input frame metadata to get the time difference. Time difference, average,
21622 maximum and minimum time (respectively @code{t}, @code{avg}, @code{max} and
21623 @code{min}) are then printed. The timestamps are expressed in seconds.
21627 @subsection Examples
21631 Benchmark @ref{selectivecolor} filter:
21633 bench=start,selectivecolor=reds=-.2 .12 -.49,bench=stop
21639 Concatenate audio and video streams, joining them together one after the
21642 The filter works on segments of synchronized video and audio streams. All
21643 segments must have the same number of streams of each type, and that will
21644 also be the number of streams at output.
21646 The filter accepts the following options:
21651 Set the number of segments. Default is 2.
21654 Set the number of output video streams, that is also the number of video
21655 streams in each segment. Default is 1.
21658 Set the number of output audio streams, that is also the number of audio
21659 streams in each segment. Default is 0.
21662 Activate unsafe mode: do not fail if segments have a different format.
21666 The filter has @var{v}+@var{a} outputs: first @var{v} video outputs, then
21667 @var{a} audio outputs.
21669 There are @var{n}x(@var{v}+@var{a}) inputs: first the inputs for the first
21670 segment, in the same order as the outputs, then the inputs for the second
21673 Related streams do not always have exactly the same duration, for various
21674 reasons including codec frame size or sloppy authoring. For that reason,
21675 related synchronized streams (e.g. a video and its audio track) should be
21676 concatenated at once. The concat filter will use the duration of the longest
21677 stream in each segment (except the last one), and if necessary pad shorter
21678 audio streams with silence.
21680 For this filter to work correctly, all segments must start at timestamp 0.
21682 All corresponding streams must have the same parameters in all segments; the
21683 filtering system will automatically select a common pixel format for video
21684 streams, and a common sample format, sample rate and channel layout for
21685 audio streams, but other settings, such as resolution, must be converted
21686 explicitly by the user.
21688 Different frame rates are acceptable but will result in variable frame rate
21689 at output; be sure to configure the output file to handle it.
21691 @subsection Examples
21695 Concatenate an opening, an episode and an ending, all in bilingual version
21696 (video in stream 0, audio in streams 1 and 2):
21698 ffmpeg -i opening.mkv -i episode.mkv -i ending.mkv -filter_complex \
21699 '[0:0] [0:1] [0:2] [1:0] [1:1] [1:2] [2:0] [2:1] [2:2]
21700 concat=n=3:v=1:a=2 [v] [a1] [a2]' \
21701 -map '[v]' -map '[a1]' -map '[a2]' output.mkv
21705 Concatenate two parts, handling audio and video separately, using the
21706 (a)movie sources, and adjusting the resolution:
21708 movie=part1.mp4, scale=512:288 [v1] ; amovie=part1.mp4 [a1] ;
21709 movie=part2.mp4, scale=512:288 [v2] ; amovie=part2.mp4 [a2] ;
21710 [v1] [v2] concat [outv] ; [a1] [a2] concat=v=0:a=1 [outa]
21712 Note that a desync will happen at the stitch if the audio and video streams
21713 do not have exactly the same duration in the first file.
21717 @subsection Commands
21719 This filter supports the following commands:
21722 Close the current segment and step to the next one
21725 @section drawgraph, adrawgraph
21727 Draw a graph using input video or audio metadata.
21729 It accepts the following parameters:
21733 Set 1st frame metadata key from which metadata values will be used to draw a graph.
21736 Set 1st foreground color expression.
21739 Set 2nd frame metadata key from which metadata values will be used to draw a graph.
21742 Set 2nd foreground color expression.
21745 Set 3rd frame metadata key from which metadata values will be used to draw a graph.
21748 Set 3rd foreground color expression.
21751 Set 4th frame metadata key from which metadata values will be used to draw a graph.
21754 Set 4th foreground color expression.
21757 Set minimal value of metadata value.
21760 Set maximal value of metadata value.
21763 Set graph background color. Default is white.
21768 Available values for mode is:
21775 Default is @code{line}.
21780 Available values for slide is:
21783 Draw new frame when right border is reached.
21786 Replace old columns with new ones.
21789 Scroll from right to left.
21792 Scroll from left to right.
21795 Draw single picture.
21798 Default is @code{frame}.
21801 Set size of graph video. For the syntax of this option, check the
21802 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
21803 The default value is @code{900x256}.
21805 The foreground color expressions can use the following variables:
21808 Minimal value of metadata value.
21811 Maximal value of metadata value.
21814 Current metadata key value.
21817 The color is defined as 0xAABBGGRR.
21820 Example using metadata from @ref{signalstats} filter:
21822 signalstats,drawgraph=lavfi.signalstats.YAVG:min=0:max=255
21825 Example using metadata from @ref{ebur128} filter:
21827 ebur128=metadata=1,adrawgraph=lavfi.r128.M:min=-120:max=5
21833 EBU R128 scanner filter. This filter takes an audio stream and analyzes its loudness
21834 level. By default, it logs a message at a frequency of 10Hz with the
21835 Momentary loudness (identified by @code{M}), Short-term loudness (@code{S}),
21836 Integrated loudness (@code{I}) and Loudness Range (@code{LRA}).
21838 The filter can only analyze streams which have a sampling rate of 48000 Hz and whose
21839 sample format is double-precision floating point. The input stream will be converted to
21840 this specification, if needed. Users may need to insert aformat and/or aresample filters
21841 after this filter to obtain the original parameters.
21843 The filter also has a video output (see the @var{video} option) with a real
21844 time graph to observe the loudness evolution. The graphic contains the logged
21845 message mentioned above, so it is not printed anymore when this option is set,
21846 unless the verbose logging is set. The main graphing area contains the
21847 short-term loudness (3 seconds of analysis), and the gauge on the right is for
21848 the momentary loudness (400 milliseconds), but can optionally be configured
21849 to instead display short-term loudness (see @var{gauge}).
21851 The green area marks a +/- 1LU target range around the target loudness
21852 (-23LUFS by default, unless modified through @var{target}).
21854 More information about the Loudness Recommendation EBU R128 on
21855 @url{http://tech.ebu.ch/loudness}.
21857 The filter accepts the following options:
21862 Activate the video output. The audio stream is passed unchanged whether this
21863 option is set or no. The video stream will be the first output stream if
21864 activated. Default is @code{0}.
21867 Set the video size. This option is for video only. For the syntax of this
21869 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
21870 Default and minimum resolution is @code{640x480}.
21873 Set the EBU scale meter. Default is @code{9}. Common values are @code{9} and
21874 @code{18}, respectively for EBU scale meter +9 and EBU scale meter +18. Any
21875 other integer value between this range is allowed.
21878 Set metadata injection. If set to @code{1}, the audio input will be segmented
21879 into 100ms output frames, each of them containing various loudness information
21880 in metadata. All the metadata keys are prefixed with @code{lavfi.r128.}.
21882 Default is @code{0}.
21885 Force the frame logging level.
21887 Available values are:
21890 information logging level
21892 verbose logging level
21895 By default, the logging level is set to @var{info}. If the @option{video} or
21896 the @option{metadata} options are set, it switches to @var{verbose}.
21901 Available modes can be cumulated (the option is a @code{flag} type). Possible
21905 Disable any peak mode (default).
21907 Enable sample-peak mode.
21909 Simple peak mode looking for the higher sample value. It logs a message
21910 for sample-peak (identified by @code{SPK}).
21912 Enable true-peak mode.
21914 If enabled, the peak lookup is done on an over-sampled version of the input
21915 stream for better peak accuracy. It logs a message for true-peak.
21916 (identified by @code{TPK}) and true-peak per frame (identified by @code{FTPK}).
21917 This mode requires a build with @code{libswresample}.
21921 Treat mono input files as "dual mono". If a mono file is intended for playback
21922 on a stereo system, its EBU R128 measurement will be perceptually incorrect.
21923 If set to @code{true}, this option will compensate for this effect.
21924 Multi-channel input files are not affected by this option.
21927 Set a specific pan law to be used for the measurement of dual mono files.
21928 This parameter is optional, and has a default value of -3.01dB.
21931 Set a specific target level (in LUFS) used as relative zero in the visualization.
21932 This parameter is optional and has a default value of -23LUFS as specified
21933 by EBU R128. However, material published online may prefer a level of -16LUFS
21934 (e.g. for use with podcasts or video platforms).
21937 Set the value displayed by the gauge. Valid values are @code{momentary} and s
21938 @code{shortterm}. By default the momentary value will be used, but in certain
21939 scenarios it may be more useful to observe the short term value instead (e.g.
21943 Sets the display scale for the loudness. Valid parameters are @code{absolute}
21944 (in LUFS) or @code{relative} (LU) relative to the target. This only affects the
21945 video output, not the summary or continuous log output.
21948 @subsection Examples
21952 Real-time graph using @command{ffplay}, with a EBU scale meter +18:
21954 ffplay -f lavfi -i "amovie=input.mp3,ebur128=video=1:meter=18 [out0][out1]"
21958 Run an analysis with @command{ffmpeg}:
21960 ffmpeg -nostats -i input.mp3 -filter_complex ebur128 -f null -
21964 @section interleave, ainterleave
21966 Temporally interleave frames from several inputs.
21968 @code{interleave} works with video inputs, @code{ainterleave} with audio.
21970 These filters read frames from several inputs and send the oldest
21971 queued frame to the output.
21973 Input streams must have well defined, monotonically increasing frame
21976 In order to submit one frame to output, these filters need to enqueue
21977 at least one frame for each input, so they cannot work in case one
21978 input is not yet terminated and will not receive incoming frames.
21980 For example consider the case when one input is a @code{select} filter
21981 which always drops input frames. The @code{interleave} filter will keep
21982 reading from that input, but it will never be able to send new frames
21983 to output until the input sends an end-of-stream signal.
21985 Also, depending on inputs synchronization, the filters will drop
21986 frames in case one input receives more frames than the other ones, and
21987 the queue is already filled.
21989 These filters accept the following options:
21993 Set the number of different inputs, it is 2 by default.
21996 @subsection Examples
22000 Interleave frames belonging to different streams using @command{ffmpeg}:
22002 ffmpeg -i bambi.avi -i pr0n.mkv -filter_complex "[0:v][1:v] interleave" out.avi
22006 Add flickering blur effect:
22008 select='if(gt(random(0), 0.2), 1, 2)':n=2 [tmp], boxblur=2:2, [tmp] interleave
22012 @section metadata, ametadata
22014 Manipulate frame metadata.
22016 This filter accepts the following options:
22020 Set mode of operation of the filter.
22022 Can be one of the following:
22026 If both @code{value} and @code{key} is set, select frames
22027 which have such metadata. If only @code{key} is set, select
22028 every frame that has such key in metadata.
22031 Add new metadata @code{key} and @code{value}. If key is already available
22035 Modify value of already present key.
22038 If @code{value} is set, delete only keys that have such value.
22039 Otherwise, delete key. If @code{key} is not set, delete all metadata values in
22043 Print key and its value if metadata was found. If @code{key} is not set print all
22044 metadata values available in frame.
22048 Set key used with all modes. Must be set for all modes except @code{print} and @code{delete}.
22051 Set metadata value which will be used. This option is mandatory for
22052 @code{modify} and @code{add} mode.
22055 Which function to use when comparing metadata value and @code{value}.
22057 Can be one of following:
22061 Values are interpreted as strings, returns true if metadata value is same as @code{value}.
22064 Values are interpreted as strings, returns true if metadata value starts with
22065 the @code{value} option string.
22068 Values are interpreted as floats, returns true if metadata value is less than @code{value}.
22071 Values are interpreted as floats, returns true if @code{value} is equal with metadata value.
22074 Values are interpreted as floats, returns true if metadata value is greater than @code{value}.
22077 Values are interpreted as floats, returns true if expression from option @code{expr}
22081 Values are interpreted as strings, returns true if metadata value ends with
22082 the @code{value} option string.
22086 Set expression which is used when @code{function} is set to @code{expr}.
22087 The expression is evaluated through the eval API and can contain the following
22092 Float representation of @code{value} from metadata key.
22095 Float representation of @code{value} as supplied by user in @code{value} option.
22099 If specified in @code{print} mode, output is written to the named file. Instead of
22100 plain filename any writable url can be specified. Filename ``-'' is a shorthand
22101 for standard output. If @code{file} option is not set, output is written to the log
22102 with AV_LOG_INFO loglevel.
22106 @subsection Examples
22110 Print all metadata values for frames with key @code{lavfi.signalstats.YDIF} with values
22113 signalstats,metadata=print:key=lavfi.signalstats.YDIF:value=0:function=expr:expr='between(VALUE1,0,1)'
22116 Print silencedetect output to file @file{metadata.txt}.
22118 silencedetect,ametadata=mode=print:file=metadata.txt
22121 Direct all metadata to a pipe with file descriptor 4.
22123 metadata=mode=print:file='pipe\:4'
22127 @section perms, aperms
22129 Set read/write permissions for the output frames.
22131 These filters are mainly aimed at developers to test direct path in the
22132 following filter in the filtergraph.
22134 The filters accept the following options:
22138 Select the permissions mode.
22140 It accepts the following values:
22143 Do nothing. This is the default.
22145 Set all the output frames read-only.
22147 Set all the output frames directly writable.
22149 Make the frame read-only if writable, and writable if read-only.
22151 Set each output frame read-only or writable randomly.
22155 Set the seed for the @var{random} mode, must be an integer included between
22156 @code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to
22157 @code{-1}, the filter will try to use a good random seed on a best effort
22161 Note: in case of auto-inserted filter between the permission filter and the
22162 following one, the permission might not be received as expected in that
22163 following filter. Inserting a @ref{format} or @ref{aformat} filter before the
22164 perms/aperms filter can avoid this problem.
22166 @section realtime, arealtime
22168 Slow down filtering to match real time approximately.
22170 These filters will pause the filtering for a variable amount of time to
22171 match the output rate with the input timestamps.
22172 They are similar to the @option{re} option to @code{ffmpeg}.
22174 They accept the following options:
22178 Time limit for the pauses. Any pause longer than that will be considered
22179 a timestamp discontinuity and reset the timer. Default is 2 seconds.
22181 Speed factor for processing. The value must be a float larger than zero.
22182 Values larger than 1.0 will result in faster than realtime processing,
22183 smaller will slow processing down. The @var{limit} is automatically adapted
22184 accordingly. Default is 1.0.
22186 A processing speed faster than what is possible without these filters cannot
22191 @section select, aselect
22193 Select frames to pass in output.
22195 This filter accepts the following options:
22200 Set expression, which is evaluated for each input frame.
22202 If the expression is evaluated to zero, the frame is discarded.
22204 If the evaluation result is negative or NaN, the frame is sent to the
22205 first output; otherwise it is sent to the output with index
22206 @code{ceil(val)-1}, assuming that the input index starts from 0.
22208 For example a value of @code{1.2} corresponds to the output with index
22209 @code{ceil(1.2)-1 = 2-1 = 1}, that is the second output.
22212 Set the number of outputs. The output to which to send the selected
22213 frame is based on the result of the evaluation. Default value is 1.
22216 The expression can contain the following constants:
22220 The (sequential) number of the filtered frame, starting from 0.
22223 The (sequential) number of the selected frame, starting from 0.
22225 @item prev_selected_n
22226 The sequential number of the last selected frame. It's NAN if undefined.
22229 The timebase of the input timestamps.
22232 The PTS (Presentation TimeStamp) of the filtered video frame,
22233 expressed in @var{TB} units. It's NAN if undefined.
22236 The PTS of the filtered video frame,
22237 expressed in seconds. It's NAN if undefined.
22240 The PTS of the previously filtered video frame. It's NAN if undefined.
22242 @item prev_selected_pts
22243 The PTS of the last previously filtered video frame. It's NAN if undefined.
22245 @item prev_selected_t
22246 The PTS of the last previously selected video frame, expressed in seconds. It's NAN if undefined.
22249 The PTS of the first video frame in the video. It's NAN if undefined.
22252 The time of the first video frame in the video. It's NAN if undefined.
22254 @item pict_type @emph{(video only)}
22255 The type of the filtered frame. It can assume one of the following
22267 @item interlace_type @emph{(video only)}
22268 The frame interlace type. It can assume one of the following values:
22271 The frame is progressive (not interlaced).
22273 The frame is top-field-first.
22275 The frame is bottom-field-first.
22278 @item consumed_sample_n @emph{(audio only)}
22279 the number of selected samples before the current frame
22281 @item samples_n @emph{(audio only)}
22282 the number of samples in the current frame
22284 @item sample_rate @emph{(audio only)}
22285 the input sample rate
22288 This is 1 if the filtered frame is a key-frame, 0 otherwise.
22291 the position in the file of the filtered frame, -1 if the information
22292 is not available (e.g. for synthetic video)
22294 @item scene @emph{(video only)}
22295 value between 0 and 1 to indicate a new scene; a low value reflects a low
22296 probability for the current frame to introduce a new scene, while a higher
22297 value means the current frame is more likely to be one (see the example below)
22299 @item concatdec_select
22300 The concat demuxer can select only part of a concat input file by setting an
22301 inpoint and an outpoint, but the output packets may not be entirely contained
22302 in the selected interval. By using this variable, it is possible to skip frames
22303 generated by the concat demuxer which are not exactly contained in the selected
22306 This works by comparing the frame pts against the @var{lavf.concat.start_time}
22307 and the @var{lavf.concat.duration} packet metadata values which are also
22308 present in the decoded frames.
22310 The @var{concatdec_select} variable is -1 if the frame pts is at least
22311 start_time and either the duration metadata is missing or the frame pts is less
22312 than start_time + duration, 0 otherwise, and NaN if the start_time metadata is
22315 That basically means that an input frame is selected if its pts is within the
22316 interval set by the concat demuxer.
22320 The default value of the select expression is "1".
22322 @subsection Examples
22326 Select all frames in input:
22331 The example above is the same as:
22343 Select only I-frames:
22345 select='eq(pict_type\,I)'
22349 Select one frame every 100:
22351 select='not(mod(n\,100))'
22355 Select only frames contained in the 10-20 time interval:
22357 select=between(t\,10\,20)
22361 Select only I-frames contained in the 10-20 time interval:
22363 select=between(t\,10\,20)*eq(pict_type\,I)
22367 Select frames with a minimum distance of 10 seconds:
22369 select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)'
22373 Use aselect to select only audio frames with samples number > 100:
22375 aselect='gt(samples_n\,100)'
22379 Create a mosaic of the first scenes:
22381 ffmpeg -i video.avi -vf select='gt(scene\,0.4)',scale=160:120,tile -frames:v 1 preview.png
22384 Comparing @var{scene} against a value between 0.3 and 0.5 is generally a sane
22388 Send even and odd frames to separate outputs, and compose them:
22390 select=n=2:e='mod(n, 2)+1' [odd][even]; [odd] pad=h=2*ih [tmp]; [tmp][even] overlay=y=h
22394 Select useful frames from an ffconcat file which is using inpoints and
22395 outpoints but where the source files are not intra frame only.
22397 ffmpeg -copyts -vsync 0 -segment_time_metadata 1 -i input.ffconcat -vf select=concatdec_select -af aselect=concatdec_select output.avi
22401 @section sendcmd, asendcmd
22403 Send commands to filters in the filtergraph.
22405 These filters read commands to be sent to other filters in the
22408 @code{sendcmd} must be inserted between two video filters,
22409 @code{asendcmd} must be inserted between two audio filters, but apart
22410 from that they act the same way.
22412 The specification of commands can be provided in the filter arguments
22413 with the @var{commands} option, or in a file specified by the
22414 @var{filename} option.
22416 These filters accept the following options:
22419 Set the commands to be read and sent to the other filters.
22421 Set the filename of the commands to be read and sent to the other
22425 @subsection Commands syntax
22427 A commands description consists of a sequence of interval
22428 specifications, comprising a list of commands to be executed when a
22429 particular event related to that interval occurs. The occurring event
22430 is typically the current frame time entering or leaving a given time
22433 An interval is specified by the following syntax:
22435 @var{START}[-@var{END}] @var{COMMANDS};
22438 The time interval is specified by the @var{START} and @var{END} times.
22439 @var{END} is optional and defaults to the maximum time.
22441 The current frame time is considered within the specified interval if
22442 it is included in the interval [@var{START}, @var{END}), that is when
22443 the time is greater or equal to @var{START} and is lesser than
22446 @var{COMMANDS} consists of a sequence of one or more command
22447 specifications, separated by ",", relating to that interval. The
22448 syntax of a command specification is given by:
22450 [@var{FLAGS}] @var{TARGET} @var{COMMAND} @var{ARG}
22453 @var{FLAGS} is optional and specifies the type of events relating to
22454 the time interval which enable sending the specified command, and must
22455 be a non-null sequence of identifier flags separated by "+" or "|" and
22456 enclosed between "[" and "]".
22458 The following flags are recognized:
22461 The command is sent when the current frame timestamp enters the
22462 specified interval. In other words, the command is sent when the
22463 previous frame timestamp was not in the given interval, and the
22467 The command is sent when the current frame timestamp leaves the
22468 specified interval. In other words, the command is sent when the
22469 previous frame timestamp was in the given interval, and the
22473 If @var{FLAGS} is not specified, a default value of @code{[enter]} is
22476 @var{TARGET} specifies the target of the command, usually the name of
22477 the filter class or a specific filter instance name.
22479 @var{COMMAND} specifies the name of the command for the target filter.
22481 @var{ARG} is optional and specifies the optional list of argument for
22482 the given @var{COMMAND}.
22484 Between one interval specification and another, whitespaces, or
22485 sequences of characters starting with @code{#} until the end of line,
22486 are ignored and can be used to annotate comments.
22488 A simplified BNF description of the commands specification syntax
22491 @var{COMMAND_FLAG} ::= "enter" | "leave"
22492 @var{COMMAND_FLAGS} ::= @var{COMMAND_FLAG} [(+|"|")@var{COMMAND_FLAG}]
22493 @var{COMMAND} ::= ["[" @var{COMMAND_FLAGS} "]"] @var{TARGET} @var{COMMAND} [@var{ARG}]
22494 @var{COMMANDS} ::= @var{COMMAND} [,@var{COMMANDS}]
22495 @var{INTERVAL} ::= @var{START}[-@var{END}] @var{COMMANDS}
22496 @var{INTERVALS} ::= @var{INTERVAL}[;@var{INTERVALS}]
22499 @subsection Examples
22503 Specify audio tempo change at second 4:
22505 asendcmd=c='4.0 atempo tempo 1.5',atempo
22509 Target a specific filter instance:
22511 asendcmd=c='4.0 atempo@@my tempo 1.5',atempo@@my
22515 Specify a list of drawtext and hue commands in a file.
22517 # show text in the interval 5-10
22518 5.0-10.0 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=hello world',
22519 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=';
22521 # desaturate the image in the interval 15-20
22522 15.0-20.0 [enter] hue s 0,
22523 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=nocolor',
22525 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=color';
22527 # apply an exponential saturation fade-out effect, starting from time 25
22528 25 [enter] hue s exp(25-t)
22531 A filtergraph allowing to read and process the above command list
22532 stored in a file @file{test.cmd}, can be specified with:
22534 sendcmd=f=test.cmd,drawtext=fontfile=FreeSerif.ttf:text='',hue
22539 @section setpts, asetpts
22541 Change the PTS (presentation timestamp) of the input frames.
22543 @code{setpts} works on video frames, @code{asetpts} on audio frames.
22545 This filter accepts the following options:
22550 The expression which is evaluated for each frame to construct its timestamp.
22554 The expression is evaluated through the eval API and can contain the following
22558 @item FRAME_RATE, FR
22559 frame rate, only defined for constant frame-rate video
22562 The presentation timestamp in input
22565 The count of the input frame for video or the number of consumed samples,
22566 not including the current frame for audio, starting from 0.
22568 @item NB_CONSUMED_SAMPLES
22569 The number of consumed samples, not including the current frame (only
22572 @item NB_SAMPLES, S
22573 The number of samples in the current frame (only audio)
22575 @item SAMPLE_RATE, SR
22576 The audio sample rate.
22579 The PTS of the first frame.
22582 the time in seconds of the first frame
22585 State whether the current frame is interlaced.
22588 the time in seconds of the current frame
22591 original position in the file of the frame, or undefined if undefined
22592 for the current frame
22595 The previous input PTS.
22598 previous input time in seconds
22601 The previous output PTS.
22604 previous output time in seconds
22607 The wallclock (RTC) time in microseconds. This is deprecated, use time(0)
22611 The wallclock (RTC) time at the start of the movie in microseconds.
22614 The timebase of the input timestamps.
22618 @subsection Examples
22622 Start counting PTS from zero
22624 setpts=PTS-STARTPTS
22628 Apply fast motion effect:
22634 Apply slow motion effect:
22640 Set fixed rate of 25 frames per second:
22646 Set fixed rate 25 fps with some jitter:
22648 setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
22652 Apply an offset of 10 seconds to the input PTS:
22658 Generate timestamps from a "live source" and rebase onto the current timebase:
22660 setpts='(RTCTIME - RTCSTART) / (TB * 1000000)'
22664 Generate timestamps by counting samples:
22673 Force color range for the output video frame.
22675 The @code{setrange} filter marks the color range property for the
22676 output frames. It does not change the input frame, but only sets the
22677 corresponding property, which affects how the frame is treated by
22680 The filter accepts the following options:
22685 Available values are:
22689 Keep the same color range property.
22691 @item unspecified, unknown
22692 Set the color range as unspecified.
22694 @item limited, tv, mpeg
22695 Set the color range as limited.
22697 @item full, pc, jpeg
22698 Set the color range as full.
22702 @section settb, asettb
22704 Set the timebase to use for the output frames timestamps.
22705 It is mainly useful for testing timebase configuration.
22707 It accepts the following parameters:
22712 The expression which is evaluated into the output timebase.
22716 The value for @option{tb} is an arithmetic expression representing a
22717 rational. The expression can contain the constants "AVTB" (the default
22718 timebase), "intb" (the input timebase) and "sr" (the sample rate,
22719 audio only). Default value is "intb".
22721 @subsection Examples
22725 Set the timebase to 1/25:
22731 Set the timebase to 1/10:
22737 Set the timebase to 1001/1000:
22743 Set the timebase to 2*intb:
22749 Set the default timebase value:
22756 Convert input audio to a video output representing frequency spectrum
22757 logarithmically using Brown-Puckette constant Q transform algorithm with
22758 direct frequency domain coefficient calculation (but the transform itself
22759 is not really constant Q, instead the Q factor is actually variable/clamped),
22760 with musical tone scale, from E0 to D#10.
22762 The filter accepts the following options:
22766 Specify the video size for the output. It must be even. For the syntax of this option,
22767 check the @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
22768 Default value is @code{1920x1080}.
22771 Set the output frame rate. Default value is @code{25}.
22774 Set the bargraph height. It must be even. Default value is @code{-1} which
22775 computes the bargraph height automatically.
22778 Set the axis height. It must be even. Default value is @code{-1} which computes
22779 the axis height automatically.
22782 Set the sonogram height. It must be even. Default value is @code{-1} which
22783 computes the sonogram height automatically.
22786 Set the fullhd resolution. This option is deprecated, use @var{size}, @var{s}
22787 instead. Default value is @code{1}.
22789 @item sono_v, volume
22790 Specify the sonogram volume expression. It can contain variables:
22793 the @var{bar_v} evaluated expression
22794 @item frequency, freq, f
22795 the frequency where it is evaluated
22796 @item timeclamp, tc
22797 the value of @var{timeclamp} option
22801 @item a_weighting(f)
22802 A-weighting of equal loudness
22803 @item b_weighting(f)
22804 B-weighting of equal loudness
22805 @item c_weighting(f)
22806 C-weighting of equal loudness.
22808 Default value is @code{16}.
22810 @item bar_v, volume2
22811 Specify the bargraph volume expression. It can contain variables:
22814 the @var{sono_v} evaluated expression
22815 @item frequency, freq, f
22816 the frequency where it is evaluated
22817 @item timeclamp, tc
22818 the value of @var{timeclamp} option
22822 @item a_weighting(f)
22823 A-weighting of equal loudness
22824 @item b_weighting(f)
22825 B-weighting of equal loudness
22826 @item c_weighting(f)
22827 C-weighting of equal loudness.
22829 Default value is @code{sono_v}.
22831 @item sono_g, gamma
22832 Specify the sonogram gamma. Lower gamma makes the spectrum more contrast,
22833 higher gamma makes the spectrum having more range. Default value is @code{3}.
22834 Acceptable range is @code{[1, 7]}.
22836 @item bar_g, gamma2
22837 Specify the bargraph gamma. Default value is @code{1}. Acceptable range is
22841 Specify the bargraph transparency level. Lower value makes the bargraph sharper.
22842 Default value is @code{1}. Acceptable range is @code{[0, 1]}.
22844 @item timeclamp, tc
22845 Specify the transform timeclamp. At low frequency, there is trade-off between
22846 accuracy in time domain and frequency domain. If timeclamp is lower,
22847 event in time domain is represented more accurately (such as fast bass drum),
22848 otherwise event in frequency domain is represented more accurately
22849 (such as bass guitar). Acceptable range is @code{[0.002, 1]}. Default value is @code{0.17}.
22852 Set attack time in seconds. The default is @code{0} (disabled). Otherwise, it
22853 limits future samples by applying asymmetric windowing in time domain, useful
22854 when low latency is required. Accepted range is @code{[0, 1]}.
22857 Specify the transform base frequency. Default value is @code{20.01523126408007475},
22858 which is frequency 50 cents below E0. Acceptable range is @code{[10, 100000]}.
22861 Specify the transform end frequency. Default value is @code{20495.59681441799654},
22862 which is frequency 50 cents above D#10. Acceptable range is @code{[10, 100000]}.
22865 This option is deprecated and ignored.
22868 Specify the transform length in time domain. Use this option to control accuracy
22869 trade-off between time domain and frequency domain at every frequency sample.
22870 It can contain variables:
22872 @item frequency, freq, f
22873 the frequency where it is evaluated
22874 @item timeclamp, tc
22875 the value of @var{timeclamp} option.
22877 Default value is @code{384*tc/(384+tc*f)}.
22880 Specify the transform count for every video frame. Default value is @code{6}.
22881 Acceptable range is @code{[1, 30]}.
22884 Specify the transform count for every single pixel. Default value is @code{0},
22885 which makes it computed automatically. Acceptable range is @code{[0, 10]}.
22888 Specify font file for use with freetype to draw the axis. If not specified,
22889 use embedded font. Note that drawing with font file or embedded font is not
22890 implemented with custom @var{basefreq} and @var{endfreq}, use @var{axisfile}
22894 Specify fontconfig pattern. This has lower priority than @var{fontfile}. The
22895 @code{:} in the pattern may be replaced by @code{|} to avoid unnecessary
22899 Specify font color expression. This is arithmetic expression that should return
22900 integer value 0xRRGGBB. It can contain variables:
22902 @item frequency, freq, f
22903 the frequency where it is evaluated
22904 @item timeclamp, tc
22905 the value of @var{timeclamp} option
22910 midi number of frequency f, some midi numbers: E0(16), C1(24), C2(36), A4(69)
22911 @item r(x), g(x), b(x)
22912 red, green, and blue value of intensity x.
22914 Default value is @code{st(0, (midi(f)-59.5)/12);
22915 st(1, if(between(ld(0),0,1), 0.5-0.5*cos(2*PI*ld(0)), 0));
22916 r(1-ld(1)) + b(ld(1))}.
22919 Specify image file to draw the axis. This option override @var{fontfile} and
22920 @var{fontcolor} option.
22923 Enable/disable drawing text to the axis. If it is set to @code{0}, drawing to
22924 the axis is disabled, ignoring @var{fontfile} and @var{axisfile} option.
22925 Default value is @code{1}.
22928 Set colorspace. The accepted values are:
22931 Unspecified (default)
22940 BT.470BG or BT.601-6 625
22943 SMPTE-170M or BT.601-6 525
22949 BT.2020 with non-constant luminance
22954 Set spectrogram color scheme. This is list of floating point values with format
22955 @code{left_r|left_g|left_b|right_r|right_g|right_b}.
22956 The default is @code{1|0.5|0|0|0.5|1}.
22960 @subsection Examples
22964 Playing audio while showing the spectrum:
22966 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt [out0]'
22970 Same as above, but with frame rate 30 fps:
22972 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fps=30:count=5 [out0]'
22976 Playing at 1280x720:
22978 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=s=1280x720:count=4 [out0]'
22982 Disable sonogram display:
22988 A1 and its harmonics: A1, A2, (near)E3, A3:
22990 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),
22991 asplit[a][out1]; [a] showcqt [out0]'
22995 Same as above, but with more accuracy in frequency domain:
22997 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),
22998 asplit[a][out1]; [a] showcqt=timeclamp=0.5 [out0]'
23004 bar_v=10:sono_v=bar_v*a_weighting(f)
23008 Custom gamma, now spectrum is linear to the amplitude.
23014 Custom tlength equation:
23016 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)))'
23020 Custom fontcolor and fontfile, C-note is colored green, others are colored blue:
23022 fontcolor='if(mod(floor(midi(f)+0.5),12), 0x0000FF, g(1))':fontfile=myfont.ttf
23026 Custom font using fontconfig:
23028 font='Courier New,Monospace,mono|bold'
23032 Custom frequency range with custom axis using image file:
23034 axisfile=myaxis.png:basefreq=40:endfreq=10000
23040 Convert input audio to video output representing the audio power spectrum.
23041 Audio amplitude is on Y-axis while frequency is on X-axis.
23043 The filter accepts the following options:
23047 Specify size of video. For the syntax of this option, check the
23048 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23049 Default is @code{1024x512}.
23053 This set how each frequency bin will be represented.
23055 It accepts the following values:
23061 Default is @code{bar}.
23064 Set amplitude scale.
23066 It accepts the following values:
23080 Default is @code{log}.
23083 Set frequency scale.
23085 It accepts the following values:
23094 Reverse logarithmic scale.
23096 Default is @code{lin}.
23099 Set window size. Allowed range is from 16 to 65536.
23101 Default is @code{2048}
23104 Set windowing function.
23106 It accepts the following values:
23129 Default is @code{hanning}.
23132 Set window overlap. In range @code{[0, 1]}. Default is @code{1},
23133 which means optimal overlap for selected window function will be picked.
23136 Set time averaging. Setting this to 0 will display current maximal peaks.
23137 Default is @code{1}, which means time averaging is disabled.
23140 Specify list of colors separated by space or by '|' which will be used to
23141 draw channel frequencies. Unrecognized or missing colors will be replaced
23145 Set channel display mode.
23147 It accepts the following values:
23152 Default is @code{combined}.
23155 Set minimum amplitude used in @code{log} amplitude scaler.
23159 @section showspatial
23161 Convert stereo input audio to a video output, representing the spatial relationship
23162 between two channels.
23164 The filter accepts the following options:
23168 Specify the video size for the output. For the syntax of this option, check the
23169 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23170 Default value is @code{512x512}.
23173 Set window size. Allowed range is from @var{1024} to @var{65536}. Default size is @var{4096}.
23176 Set window function.
23178 It accepts the following values:
23203 Default value is @code{hann}.
23206 Set ratio of overlap window. Default value is @code{0.5}.
23207 When value is @code{1} overlap is set to recommended size for specific
23208 window function currently used.
23211 @anchor{showspectrum}
23212 @section showspectrum
23214 Convert input audio to a video output, representing the audio frequency
23217 The filter accepts the following options:
23221 Specify the video size for the output. For the syntax of this option, check the
23222 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23223 Default value is @code{640x512}.
23226 Specify how the spectrum should slide along the window.
23228 It accepts the following values:
23231 the samples start again on the left when they reach the right
23233 the samples scroll from right to left
23235 frames are only produced when the samples reach the right
23237 the samples scroll from left to right
23240 Default value is @code{replace}.
23243 Specify display mode.
23245 It accepts the following values:
23248 all channels are displayed in the same row
23250 all channels are displayed in separate rows
23253 Default value is @samp{combined}.
23256 Specify display color mode.
23258 It accepts the following values:
23261 each channel is displayed in a separate color
23263 each channel is displayed using the same color scheme
23265 each channel is displayed using the rainbow color scheme
23267 each channel is displayed using the moreland color scheme
23269 each channel is displayed using the nebulae color scheme
23271 each channel is displayed using the fire color scheme
23273 each channel is displayed using the fiery color scheme
23275 each channel is displayed using the fruit color scheme
23277 each channel is displayed using the cool color scheme
23279 each channel is displayed using the magma color scheme
23281 each channel is displayed using the green color scheme
23283 each channel is displayed using the viridis color scheme
23285 each channel is displayed using the plasma color scheme
23287 each channel is displayed using the cividis color scheme
23289 each channel is displayed using the terrain color scheme
23292 Default value is @samp{channel}.
23295 Specify scale used for calculating intensity color values.
23297 It accepts the following values:
23302 square root, default
23313 Default value is @samp{sqrt}.
23316 Specify frequency scale.
23318 It accepts the following values:
23326 Default value is @samp{lin}.
23329 Set saturation modifier for displayed colors. Negative values provide
23330 alternative color scheme. @code{0} is no saturation at all.
23331 Saturation must be in [-10.0, 10.0] range.
23332 Default value is @code{1}.
23335 Set window function.
23337 It accepts the following values:
23362 Default value is @code{hann}.
23365 Set orientation of time vs frequency axis. Can be @code{vertical} or
23366 @code{horizontal}. Default is @code{vertical}.
23369 Set ratio of overlap window. Default value is @code{0}.
23370 When value is @code{1} overlap is set to recommended size for specific
23371 window function currently used.
23374 Set scale gain for calculating intensity color values.
23375 Default value is @code{1}.
23378 Set which data to display. Can be @code{magnitude}, default or @code{phase}.
23381 Set color rotation, must be in [-1.0, 1.0] range.
23382 Default value is @code{0}.
23385 Set start frequency from which to display spectrogram. Default is @code{0}.
23388 Set stop frequency to which to display spectrogram. Default is @code{0}.
23391 Set upper frame rate limit. Default is @code{auto}, unlimited.
23394 Draw time and frequency axes and legends. Default is disabled.
23397 The usage is very similar to the showwaves filter; see the examples in that
23400 @subsection Examples
23404 Large window with logarithmic color scaling:
23406 showspectrum=s=1280x480:scale=log
23410 Complete example for a colored and sliding spectrum per channel using @command{ffplay}:
23412 ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
23413 [a] showspectrum=mode=separate:color=intensity:slide=1:scale=cbrt [out0]'
23417 @section showspectrumpic
23419 Convert input audio to a single video frame, representing the audio frequency
23422 The filter accepts the following options:
23426 Specify the video size for the output. For the syntax of this option, check the
23427 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23428 Default value is @code{4096x2048}.
23431 Specify display mode.
23433 It accepts the following values:
23436 all channels are displayed in the same row
23438 all channels are displayed in separate rows
23440 Default value is @samp{combined}.
23443 Specify display color mode.
23445 It accepts the following values:
23448 each channel is displayed in a separate color
23450 each channel is displayed using the same color scheme
23452 each channel is displayed using the rainbow color scheme
23454 each channel is displayed using the moreland color scheme
23456 each channel is displayed using the nebulae color scheme
23458 each channel is displayed using the fire color scheme
23460 each channel is displayed using the fiery color scheme
23462 each channel is displayed using the fruit color scheme
23464 each channel is displayed using the cool color scheme
23466 each channel is displayed using the magma color scheme
23468 each channel is displayed using the green color scheme
23470 each channel is displayed using the viridis color scheme
23472 each channel is displayed using the plasma color scheme
23474 each channel is displayed using the cividis color scheme
23476 each channel is displayed using the terrain color scheme
23478 Default value is @samp{intensity}.
23481 Specify scale used for calculating intensity color values.
23483 It accepts the following values:
23488 square root, default
23498 Default value is @samp{log}.
23501 Specify frequency scale.
23503 It accepts the following values:
23511 Default value is @samp{lin}.
23514 Set saturation modifier for displayed colors. Negative values provide
23515 alternative color scheme. @code{0} is no saturation at all.
23516 Saturation must be in [-10.0, 10.0] range.
23517 Default value is @code{1}.
23520 Set window function.
23522 It accepts the following values:
23546 Default value is @code{hann}.
23549 Set orientation of time vs frequency axis. Can be @code{vertical} or
23550 @code{horizontal}. Default is @code{vertical}.
23553 Set scale gain for calculating intensity color values.
23554 Default value is @code{1}.
23557 Draw time and frequency axes and legends. Default is enabled.
23560 Set color rotation, must be in [-1.0, 1.0] range.
23561 Default value is @code{0}.
23564 Set start frequency from which to display spectrogram. Default is @code{0}.
23567 Set stop frequency to which to display spectrogram. Default is @code{0}.
23570 @subsection Examples
23574 Extract an audio spectrogram of a whole audio track
23575 in a 1024x1024 picture using @command{ffmpeg}:
23577 ffmpeg -i audio.flac -lavfi showspectrumpic=s=1024x1024 spectrogram.png
23581 @section showvolume
23583 Convert input audio volume to a video output.
23585 The filter accepts the following options:
23592 Set border width, allowed range is [0, 5]. Default is 1.
23595 Set channel width, allowed range is [80, 8192]. Default is 400.
23598 Set channel height, allowed range is [1, 900]. Default is 20.
23601 Set fade, allowed range is [0, 1]. Default is 0.95.
23604 Set volume color expression.
23606 The expression can use the following variables:
23610 Current max volume of channel in dB.
23616 Current channel number, starting from 0.
23620 If set, displays channel names. Default is enabled.
23623 If set, displays volume values. Default is enabled.
23626 Set orientation, can be horizontal: @code{h} or vertical: @code{v},
23627 default is @code{h}.
23630 Set step size, allowed range is [0, 5]. Default is 0, which means
23634 Set background opacity, allowed range is [0, 1]. Default is 0.
23637 Set metering mode, can be peak: @code{p} or rms: @code{r},
23638 default is @code{p}.
23641 Set display scale, can be linear: @code{lin} or log: @code{log},
23642 default is @code{lin}.
23646 If set to > 0., display a line for the max level
23647 in the previous seconds.
23648 default is disabled: @code{0.}
23651 The color of the max line. Use when @code{dm} option is set to > 0.
23652 default is: @code{orange}
23657 Convert input audio to a video output, representing the samples waves.
23659 The filter accepts the following options:
23663 Specify the video size for the output. For the syntax of this option, check the
23664 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23665 Default value is @code{600x240}.
23670 Available values are:
23673 Draw a point for each sample.
23676 Draw a vertical line for each sample.
23679 Draw a point for each sample and a line between them.
23682 Draw a centered vertical line for each sample.
23685 Default value is @code{point}.
23688 Set the number of samples which are printed on the same column. A
23689 larger value will decrease the frame rate. Must be a positive
23690 integer. This option can be set only if the value for @var{rate}
23691 is not explicitly specified.
23694 Set the (approximate) output frame rate. This is done by setting the
23695 option @var{n}. Default value is "25".
23697 @item split_channels
23698 Set if channels should be drawn separately or overlap. Default value is 0.
23701 Set colors separated by '|' which are going to be used for drawing of each channel.
23704 Set amplitude scale.
23706 Available values are:
23724 Set the draw mode. This is mostly useful to set for high @var{n}.
23726 Available values are:
23729 Scale pixel values for each drawn sample.
23732 Draw every sample directly.
23735 Default value is @code{scale}.
23738 @subsection Examples
23742 Output the input file audio and the corresponding video representation
23745 amovie=a.mp3,asplit[out0],showwaves[out1]
23749 Create a synthetic signal and show it with showwaves, forcing a
23750 frame rate of 30 frames per second:
23752 aevalsrc=sin(1*2*PI*t)*sin(880*2*PI*t):cos(2*PI*200*t),asplit[out0],showwaves=r=30[out1]
23756 @section showwavespic
23758 Convert input audio to a single video frame, representing the samples waves.
23760 The filter accepts the following options:
23764 Specify the video size for the output. For the syntax of this option, check the
23765 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23766 Default value is @code{600x240}.
23768 @item split_channels
23769 Set if channels should be drawn separately or overlap. Default value is 0.
23772 Set colors separated by '|' which are going to be used for drawing of each channel.
23775 Set amplitude scale.
23777 Available values are:
23797 Available values are:
23800 Scale pixel values for each drawn sample.
23803 Draw every sample directly.
23806 Default value is @code{scale}.
23809 @subsection Examples
23813 Extract a channel split representation of the wave form of a whole audio track
23814 in a 1024x800 picture using @command{ffmpeg}:
23816 ffmpeg -i audio.flac -lavfi showwavespic=split_channels=1:s=1024x800 waveform.png
23820 @section sidedata, asidedata
23822 Delete frame side data, or select frames based on it.
23824 This filter accepts the following options:
23828 Set mode of operation of the filter.
23830 Can be one of the following:
23834 Select every frame with side data of @code{type}.
23837 Delete side data of @code{type}. If @code{type} is not set, delete all side
23843 Set side data type used with all modes. Must be set for @code{select} mode. For
23844 the list of frame side data types, refer to the @code{AVFrameSideDataType} enum
23845 in @file{libavutil/frame.h}. For example, to choose
23846 @code{AV_FRAME_DATA_PANSCAN} side data, you must specify @code{PANSCAN}.
23850 @section spectrumsynth
23852 Synthesize audio from 2 input video spectrums, first input stream represents
23853 magnitude across time and second represents phase across time.
23854 The filter will transform from frequency domain as displayed in videos back
23855 to time domain as presented in audio output.
23857 This filter is primarily created for reversing processed @ref{showspectrum}
23858 filter outputs, but can synthesize sound from other spectrograms too.
23859 But in such case results are going to be poor if the phase data is not
23860 available, because in such cases phase data need to be recreated, usually
23861 it's just recreated from random noise.
23862 For best results use gray only output (@code{channel} color mode in
23863 @ref{showspectrum} filter) and @code{log} scale for magnitude video and
23864 @code{lin} scale for phase video. To produce phase, for 2nd video, use
23865 @code{data} option. Inputs videos should generally use @code{fullframe}
23866 slide mode as that saves resources needed for decoding video.
23868 The filter accepts the following options:
23872 Specify sample rate of output audio, the sample rate of audio from which
23873 spectrum was generated may differ.
23876 Set number of channels represented in input video spectrums.
23879 Set scale which was used when generating magnitude input spectrum.
23880 Can be @code{lin} or @code{log}. Default is @code{log}.
23883 Set slide which was used when generating inputs spectrums.
23884 Can be @code{replace}, @code{scroll}, @code{fullframe} or @code{rscroll}.
23885 Default is @code{fullframe}.
23888 Set window function used for resynthesis.
23891 Set window overlap. In range @code{[0, 1]}. Default is @code{1},
23892 which means optimal overlap for selected window function will be picked.
23895 Set orientation of input videos. Can be @code{vertical} or @code{horizontal}.
23896 Default is @code{vertical}.
23899 @subsection Examples
23903 First create magnitude and phase videos from audio, assuming audio is stereo with 44100 sample rate,
23904 then resynthesize videos back to audio with spectrumsynth:
23906 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
23907 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
23908 ffmpeg -i magnitude.nut -i phase.nut -lavfi spectrumsynth=channels=2:sample_rate=44100:win_func=hann:overlap=0.875:slide=fullframe output.flac
23912 @section split, asplit
23914 Split input into several identical outputs.
23916 @code{asplit} works with audio input, @code{split} with video.
23918 The filter accepts a single parameter which specifies the number of outputs. If
23919 unspecified, it defaults to 2.
23921 @subsection Examples
23925 Create two separate outputs from the same input:
23927 [in] split [out0][out1]
23931 To create 3 or more outputs, you need to specify the number of
23934 [in] asplit=3 [out0][out1][out2]
23938 Create two separate outputs from the same input, one cropped and
23941 [in] split [splitout1][splitout2];
23942 [splitout1] crop=100:100:0:0 [cropout];
23943 [splitout2] pad=200:200:100:100 [padout];
23947 Create 5 copies of the input audio with @command{ffmpeg}:
23949 ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT
23955 Receive commands sent through a libzmq client, and forward them to
23956 filters in the filtergraph.
23958 @code{zmq} and @code{azmq} work as a pass-through filters. @code{zmq}
23959 must be inserted between two video filters, @code{azmq} between two
23960 audio filters. Both are capable to send messages to any filter type.
23962 To enable these filters you need to install the libzmq library and
23963 headers and configure FFmpeg with @code{--enable-libzmq}.
23965 For more information about libzmq see:
23966 @url{http://www.zeromq.org/}
23968 The @code{zmq} and @code{azmq} filters work as a libzmq server, which
23969 receives messages sent through a network interface defined by the
23970 @option{bind_address} (or the abbreviation "@option{b}") option.
23971 Default value of this option is @file{tcp://localhost:5555}. You may
23972 want to alter this value to your needs, but do not forget to escape any
23973 ':' signs (see @ref{filtergraph escaping}).
23975 The received message must be in the form:
23977 @var{TARGET} @var{COMMAND} [@var{ARG}]
23980 @var{TARGET} specifies the target of the command, usually the name of
23981 the filter class or a specific filter instance name. The default
23982 filter instance name uses the pattern @samp{Parsed_<filter_name>_<index>},
23983 but you can override this by using the @samp{filter_name@@id} syntax
23984 (see @ref{Filtergraph syntax}).
23986 @var{COMMAND} specifies the name of the command for the target filter.
23988 @var{ARG} is optional and specifies the optional argument list for the
23989 given @var{COMMAND}.
23991 Upon reception, the message is processed and the corresponding command
23992 is injected into the filtergraph. Depending on the result, the filter
23993 will send a reply to the client, adopting the format:
23995 @var{ERROR_CODE} @var{ERROR_REASON}
23999 @var{MESSAGE} is optional.
24001 @subsection Examples
24003 Look at @file{tools/zmqsend} for an example of a zmq client which can
24004 be used to send commands processed by these filters.
24006 Consider the following filtergraph generated by @command{ffplay}.
24007 In this example the last overlay filter has an instance name. All other
24008 filters will have default instance names.
24011 ffplay -dumpgraph 1 -f lavfi "
24012 color=s=100x100:c=red [l];
24013 color=s=100x100:c=blue [r];
24014 nullsrc=s=200x100, zmq [bg];
24015 [bg][l] overlay [bg+l];
24016 [bg+l][r] overlay@@my=x=100 "
24019 To change the color of the left side of the video, the following
24020 command can be used:
24022 echo Parsed_color_0 c yellow | tools/zmqsend
24025 To change the right side:
24027 echo Parsed_color_1 c pink | tools/zmqsend
24030 To change the position of the right side:
24032 echo overlay@@my x 150 | tools/zmqsend
24036 @c man end MULTIMEDIA FILTERS
24038 @chapter Multimedia Sources
24039 @c man begin MULTIMEDIA SOURCES
24041 Below is a description of the currently available multimedia sources.
24045 This is the same as @ref{movie} source, except it selects an audio
24051 Read audio and/or video stream(s) from a movie container.
24053 It accepts the following parameters:
24057 The name of the resource to read (not necessarily a file; it can also be a
24058 device or a stream accessed through some protocol).
24060 @item format_name, f
24061 Specifies the format assumed for the movie to read, and can be either
24062 the name of a container or an input device. If not specified, the
24063 format is guessed from @var{movie_name} or by probing.
24065 @item seek_point, sp
24066 Specifies the seek point in seconds. The frames will be output
24067 starting from this seek point. The parameter is evaluated with
24068 @code{av_strtod}, so the numerical value may be suffixed by an IS
24069 postfix. The default value is "0".
24072 Specifies the streams to read. Several streams can be specified,
24073 separated by "+". The source will then have as many outputs, in the
24074 same order. The syntax is explained in the @ref{Stream specifiers,,"Stream specifiers"
24075 section in the ffmpeg manual,ffmpeg}. Two special names, "dv" and "da" specify
24076 respectively the default (best suited) video and audio stream. Default
24077 is "dv", or "da" if the filter is called as "amovie".
24079 @item stream_index, si
24080 Specifies the index of the video stream to read. If the value is -1,
24081 the most suitable video stream will be automatically selected. The default
24082 value is "-1". Deprecated. If the filter is called "amovie", it will select
24083 audio instead of video.
24086 Specifies how many times to read the stream in sequence.
24087 If the value is 0, the stream will be looped infinitely.
24088 Default value is "1".
24090 Note that when the movie is looped the source timestamps are not
24091 changed, so it will generate non monotonically increasing timestamps.
24093 @item discontinuity
24094 Specifies the time difference between frames above which the point is
24095 considered a timestamp discontinuity which is removed by adjusting the later
24099 It allows overlaying a second video on top of the main input of
24100 a filtergraph, as shown in this graph:
24102 input -----------> deltapts0 --> overlay --> output
24105 movie --> scale--> deltapts1 -------+
24107 @subsection Examples
24111 Skip 3.2 seconds from the start of the AVI file in.avi, and overlay it
24112 on top of the input labelled "in":
24114 movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [over];
24115 [in] setpts=PTS-STARTPTS [main];
24116 [main][over] overlay=16:16 [out]
24120 Read from a video4linux2 device, and overlay it on top of the input
24123 movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [over];
24124 [in] setpts=PTS-STARTPTS [main];
24125 [main][over] overlay=16:16 [out]
24129 Read the first video stream and the audio stream with id 0x81 from
24130 dvd.vob; the video is connected to the pad named "video" and the audio is
24131 connected to the pad named "audio":
24133 movie=dvd.vob:s=v:0+#0x81 [video] [audio]
24137 @subsection Commands
24139 Both movie and amovie support the following commands:
24142 Perform seek using "av_seek_frame".
24143 The syntax is: seek @var{stream_index}|@var{timestamp}|@var{flags}
24146 @var{stream_index}: If stream_index is -1, a default
24147 stream is selected, and @var{timestamp} is automatically converted
24148 from AV_TIME_BASE units to the stream specific time_base.
24150 @var{timestamp}: Timestamp in AVStream.time_base units
24151 or, if no stream is specified, in AV_TIME_BASE units.
24153 @var{flags}: Flags which select direction and seeking mode.
24157 Get movie duration in AV_TIME_BASE units.
24161 @c man end MULTIMEDIA SOURCES