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.
6188 Same as the @ref{subtitles} filter, except that it doesn't require libavcodec
6189 and libavformat to work. On the other hand, it is limited to ASS (Advanced
6190 Substation Alpha) subtitles files.
6192 This filter accepts the following option in addition to the common options from
6193 the @ref{subtitles} filter:
6197 Set the shaping engine
6199 Available values are:
6202 The default libass shaping engine, which is the best available.
6204 Fast, font-agnostic shaper that can do only substitutions
6206 Slower shaper using OpenType for substitutions and positioning
6209 The default is @code{auto}.
6213 Apply an Adaptive Temporal Averaging Denoiser to the video input.
6215 The filter accepts the following options:
6219 Set threshold A for 1st plane. Default is 0.02.
6220 Valid range is 0 to 0.3.
6223 Set threshold B for 1st plane. Default is 0.04.
6224 Valid range is 0 to 5.
6227 Set threshold A for 2nd plane. Default is 0.02.
6228 Valid range is 0 to 0.3.
6231 Set threshold B for 2nd plane. Default is 0.04.
6232 Valid range is 0 to 5.
6235 Set threshold A for 3rd plane. Default is 0.02.
6236 Valid range is 0 to 0.3.
6239 Set threshold B for 3rd plane. Default is 0.04.
6240 Valid range is 0 to 5.
6242 Threshold A is designed to react on abrupt changes in the input signal and
6243 threshold B is designed to react on continuous changes in the input signal.
6246 Set number of frames filter will use for averaging. Default is 9. Must be odd
6247 number in range [5, 129].
6250 Set what planes of frame filter will use for averaging. Default is all.
6255 Apply average blur filter.
6257 The filter accepts the following options:
6261 Set horizontal radius size.
6264 Set which planes to filter. By default all planes are filtered.
6267 Set vertical radius size, if zero it will be same as @code{sizeX}.
6268 Default is @code{0}.
6271 @subsection Commands
6272 This filter supports same commands as options.
6273 The command accepts the same syntax of the corresponding option.
6275 If the specified expression is not valid, it is kept at its current
6280 Compute the bounding box for the non-black pixels in the input frame
6283 This filter computes the bounding box containing all the pixels with a
6284 luminance value greater than the minimum allowed value.
6285 The parameters describing the bounding box are printed on the filter
6288 The filter accepts the following option:
6292 Set the minimal luminance value. Default is @code{16}.
6295 @section bitplanenoise
6297 Show and measure bit plane noise.
6299 The filter accepts the following options:
6303 Set which plane to analyze. Default is @code{1}.
6306 Filter out noisy pixels from @code{bitplane} set above.
6307 Default is disabled.
6310 @section blackdetect
6312 Detect video intervals that are (almost) completely black. Can be
6313 useful to detect chapter transitions, commercials, or invalid
6314 recordings. Output lines contains the time for the start, end and
6315 duration of the detected black interval expressed in seconds.
6317 In order to display the output lines, you need to set the loglevel at
6318 least to the AV_LOG_INFO value.
6320 The filter accepts the following options:
6323 @item black_min_duration, d
6324 Set the minimum detected black duration expressed in seconds. It must
6325 be a non-negative floating point number.
6327 Default value is 2.0.
6329 @item picture_black_ratio_th, pic_th
6330 Set the threshold for considering a picture "black".
6331 Express the minimum value for the ratio:
6333 @var{nb_black_pixels} / @var{nb_pixels}
6336 for which a picture is considered black.
6337 Default value is 0.98.
6339 @item pixel_black_th, pix_th
6340 Set the threshold for considering a pixel "black".
6342 The threshold expresses the maximum pixel luminance value for which a
6343 pixel is considered "black". The provided value is scaled according to
6344 the following equation:
6346 @var{absolute_threshold} = @var{luminance_minimum_value} + @var{pixel_black_th} * @var{luminance_range_size}
6349 @var{luminance_range_size} and @var{luminance_minimum_value} depend on
6350 the input video format, the range is [0-255] for YUV full-range
6351 formats and [16-235] for YUV non full-range formats.
6353 Default value is 0.10.
6356 The following example sets the maximum pixel threshold to the minimum
6357 value, and detects only black intervals of 2 or more seconds:
6359 blackdetect=d=2:pix_th=0.00
6364 Detect frames that are (almost) completely black. Can be useful to
6365 detect chapter transitions or commercials. Output lines consist of
6366 the frame number of the detected frame, the percentage of blackness,
6367 the position in the file if known or -1 and the timestamp in seconds.
6369 In order to display the output lines, you need to set the loglevel at
6370 least to the AV_LOG_INFO value.
6372 This filter exports frame metadata @code{lavfi.blackframe.pblack}.
6373 The value represents the percentage of pixels in the picture that
6374 are below the threshold value.
6376 It accepts the following parameters:
6381 The percentage of the pixels that have to be below the threshold; it defaults to
6384 @item threshold, thresh
6385 The threshold below which a pixel value is considered black; it defaults to
6390 @section blend, tblend
6392 Blend two video frames into each other.
6394 The @code{blend} filter takes two input streams and outputs one
6395 stream, the first input is the "top" layer and second input is
6396 "bottom" layer. By default, the output terminates when the longest input terminates.
6398 The @code{tblend} (time blend) filter takes two consecutive frames
6399 from one single stream, and outputs the result obtained by blending
6400 the new frame on top of the old frame.
6402 A description of the accepted options follows.
6410 Set blend mode for specific pixel component or all pixel components in case
6411 of @var{all_mode}. Default value is @code{normal}.
6413 Available values for component modes are:
6455 Set blend opacity for specific pixel component or all pixel components in case
6456 of @var{all_opacity}. Only used in combination with pixel component blend modes.
6463 Set blend expression for specific pixel component or all pixel components in case
6464 of @var{all_expr}. Note that related mode options will be ignored if those are set.
6466 The expressions can use the following variables:
6470 The sequential number of the filtered frame, starting from @code{0}.
6474 the coordinates of the current sample
6478 the width and height of currently filtered plane
6482 Width and height scale for the plane being filtered. It is the
6483 ratio between the dimensions of the current plane to the luma plane,
6484 e.g. for a @code{yuv420p} frame, the values are @code{1,1} for
6485 the luma plane and @code{0.5,0.5} for the chroma planes.
6488 Time of the current frame, expressed in seconds.
6491 Value of pixel component at current location for first video frame (top layer).
6494 Value of pixel component at current location for second video frame (bottom layer).
6498 The @code{blend} filter also supports the @ref{framesync} options.
6500 @subsection Examples
6504 Apply transition from bottom layer to top layer in first 10 seconds:
6506 blend=all_expr='A*(if(gte(T,10),1,T/10))+B*(1-(if(gte(T,10),1,T/10)))'
6510 Apply linear horizontal transition from top layer to bottom layer:
6512 blend=all_expr='A*(X/W)+B*(1-X/W)'
6516 Apply 1x1 checkerboard effect:
6518 blend=all_expr='if(eq(mod(X,2),mod(Y,2)),A,B)'
6522 Apply uncover left effect:
6524 blend=all_expr='if(gte(N*SW+X,W),A,B)'
6528 Apply uncover down effect:
6530 blend=all_expr='if(gte(Y-N*SH,0),A,B)'
6534 Apply uncover up-left effect:
6536 blend=all_expr='if(gte(T*SH*40+Y,H)*gte((T*40*SW+X)*W/H,W),A,B)'
6540 Split diagonally video and shows top and bottom layer on each side:
6542 blend=all_expr='if(gt(X,Y*(W/H)),A,B)'
6546 Display differences between the current and the previous frame:
6548 tblend=all_mode=grainextract
6554 Denoise frames using Block-Matching 3D algorithm.
6556 The filter accepts the following options.
6560 Set denoising strength. Default value is 1.
6561 Allowed range is from 0 to 999.9.
6562 The denoising algorithm is very sensitive to sigma, so adjust it
6563 according to the source.
6566 Set local patch size. This sets dimensions in 2D.
6569 Set sliding step for processing blocks. Default value is 4.
6570 Allowed range is from 1 to 64.
6571 Smaller values allows processing more reference blocks and is slower.
6574 Set maximal number of similar blocks for 3rd dimension. Default value is 1.
6575 When set to 1, no block matching is done. Larger values allows more blocks
6577 Allowed range is from 1 to 256.
6580 Set radius for search block matching. Default is 9.
6581 Allowed range is from 1 to INT32_MAX.
6584 Set step between two search locations for block matching. Default is 1.
6585 Allowed range is from 1 to 64. Smaller is slower.
6588 Set threshold of mean square error for block matching. Valid range is 0 to
6592 Set thresholding parameter for hard thresholding in 3D transformed domain.
6593 Larger values results in stronger hard-thresholding filtering in frequency
6597 Set filtering estimation mode. Can be @code{basic} or @code{final}.
6598 Default is @code{basic}.
6601 If enabled, filter will use 2nd stream for block matching.
6602 Default is disabled for @code{basic} value of @var{estim} option,
6603 and always enabled if value of @var{estim} is @code{final}.
6606 Set planes to filter. Default is all available except alpha.
6609 @subsection Examples
6613 Basic filtering with bm3d:
6615 bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic
6619 Same as above, but filtering only luma:
6621 bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic:planes=1
6625 Same as above, but with both estimation modes:
6627 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
6631 Same as above, but prefilter with @ref{nlmeans} filter instead:
6633 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
6639 Apply a boxblur algorithm to the input video.
6641 It accepts the following parameters:
6645 @item luma_radius, lr
6646 @item luma_power, lp
6647 @item chroma_radius, cr
6648 @item chroma_power, cp
6649 @item alpha_radius, ar
6650 @item alpha_power, ap
6654 A description of the accepted options follows.
6657 @item luma_radius, lr
6658 @item chroma_radius, cr
6659 @item alpha_radius, ar
6660 Set an expression for the box radius in pixels used for blurring the
6661 corresponding input plane.
6663 The radius value must be a non-negative number, and must not be
6664 greater than the value of the expression @code{min(w,h)/2} for the
6665 luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma
6668 Default value for @option{luma_radius} is "2". If not specified,
6669 @option{chroma_radius} and @option{alpha_radius} default to the
6670 corresponding value set for @option{luma_radius}.
6672 The expressions can contain the following constants:
6676 The input width and height in pixels.
6680 The input chroma image width and height in pixels.
6684 The horizontal and vertical chroma subsample values. For example, for the
6685 pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1.
6688 @item luma_power, lp
6689 @item chroma_power, cp
6690 @item alpha_power, ap
6691 Specify how many times the boxblur filter is applied to the
6692 corresponding plane.
6694 Default value for @option{luma_power} is 2. If not specified,
6695 @option{chroma_power} and @option{alpha_power} default to the
6696 corresponding value set for @option{luma_power}.
6698 A value of 0 will disable the effect.
6701 @subsection Examples
6705 Apply a boxblur filter with the luma, chroma, and alpha radii
6708 boxblur=luma_radius=2:luma_power=1
6713 Set the luma radius to 2, and alpha and chroma radius to 0:
6715 boxblur=2:1:cr=0:ar=0
6719 Set the luma and chroma radii to a fraction of the video dimension:
6721 boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1
6727 Deinterlace the input video ("bwdif" stands for "Bob Weaver
6728 Deinterlacing Filter").
6730 Motion adaptive deinterlacing based on yadif with the use of w3fdif and cubic
6731 interpolation algorithms.
6732 It accepts the following parameters:
6736 The interlacing mode to adopt. It accepts one of the following values:
6740 Output one frame for each frame.
6742 Output one frame for each field.
6745 The default value is @code{send_field}.
6748 The picture field parity assumed for the input interlaced video. It accepts one
6749 of the following values:
6753 Assume the top field is first.
6755 Assume the bottom field is first.
6757 Enable automatic detection of field parity.
6760 The default value is @code{auto}.
6761 If the interlacing is unknown or the decoder does not export this information,
6762 top field first will be assumed.
6765 Specify which frames to deinterlace. Accepts one of the following
6770 Deinterlace all frames.
6772 Only deinterlace frames marked as interlaced.
6775 The default value is @code{all}.
6779 Remove all color information for all colors except for certain one.
6781 The filter accepts the following options:
6785 The color which will not be replaced with neutral chroma.
6788 Similarity percentage with the above color.
6789 0.01 matches only the exact key color, while 1.0 matches everything.
6793 0.0 makes pixels either fully gray, or not gray at all.
6794 Higher values result in more preserved color.
6797 Signals that the color passed is already in YUV instead of RGB.
6799 Literal colors like "green" or "red" don't make sense with this enabled anymore.
6800 This can be used to pass exact YUV values as hexadecimal numbers.
6804 YUV colorspace color/chroma keying.
6806 The filter accepts the following options:
6810 The color which will be replaced with transparency.
6813 Similarity percentage with the key color.
6815 0.01 matches only the exact key color, while 1.0 matches everything.
6820 0.0 makes pixels either fully transparent, or not transparent at all.
6822 Higher values result in semi-transparent pixels, with a higher transparency
6823 the more similar the pixels color is to the key color.
6826 Signals that the color passed is already in YUV instead of RGB.
6828 Literal colors like "green" or "red" don't make sense with this enabled anymore.
6829 This can be used to pass exact YUV values as hexadecimal numbers.
6832 @subsection Examples
6836 Make every green pixel in the input image transparent:
6838 ffmpeg -i input.png -vf chromakey=green out.png
6842 Overlay a greenscreen-video on top of a static black background.
6844 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
6848 @section chromashift
6849 Shift chroma pixels horizontally and/or vertically.
6851 The filter accepts the following options:
6854 Set amount to shift chroma-blue horizontally.
6856 Set amount to shift chroma-blue vertically.
6858 Set amount to shift chroma-red horizontally.
6860 Set amount to shift chroma-red vertically.
6862 Set edge mode, can be @var{smear}, default, or @var{warp}.
6867 Display CIE color diagram with pixels overlaid onto it.
6869 The filter accepts the following options:
6884 @item uhdtv, rec2020
6898 Set what gamuts to draw.
6900 See @code{system} option for available values.
6903 Set ciescope size, by default set to 512.
6906 Set intensity used to map input pixel values to CIE diagram.
6909 Set contrast used to draw tongue colors that are out of active color system gamut.
6912 Correct gamma displayed on scope, by default enabled.
6915 Show white point on CIE diagram, by default disabled.
6918 Set input gamma. Used only with XYZ input color space.
6923 Visualize information exported by some codecs.
6925 Some codecs can export information through frames using side-data or other
6926 means. For example, some MPEG based codecs export motion vectors through the
6927 @var{export_mvs} flag in the codec @option{flags2} option.
6929 The filter accepts the following option:
6933 Set motion vectors to visualize.
6935 Available flags for @var{mv} are:
6939 forward predicted MVs of P-frames
6941 forward predicted MVs of B-frames
6943 backward predicted MVs of B-frames
6947 Display quantization parameters using the chroma planes.
6950 Set motion vectors type to visualize. Includes MVs from all frames unless specified by @var{frame_type} option.
6952 Available flags for @var{mv_type} are:
6956 forward predicted MVs
6958 backward predicted MVs
6961 @item frame_type, ft
6962 Set frame type to visualize motion vectors of.
6964 Available flags for @var{frame_type} are:
6968 intra-coded frames (I-frames)
6970 predicted frames (P-frames)
6972 bi-directionally predicted frames (B-frames)
6976 @subsection Examples
6980 Visualize forward predicted MVs of all frames using @command{ffplay}:
6982 ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv_type=fp
6986 Visualize multi-directionals MVs of P and B-Frames using @command{ffplay}:
6988 ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv=pf+bf+bb
6992 @section colorbalance
6993 Modify intensity of primary colors (red, green and blue) of input frames.
6995 The filter allows an input frame to be adjusted in the shadows, midtones or highlights
6996 regions for the red-cyan, green-magenta or blue-yellow balance.
6998 A positive adjustment value shifts the balance towards the primary color, a negative
6999 value towards the complementary color.
7001 The filter accepts the following options:
7007 Adjust red, green and blue shadows (darkest pixels).
7012 Adjust red, green and blue midtones (medium pixels).
7017 Adjust red, green and blue highlights (brightest pixels).
7019 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
7022 @subsection Examples
7026 Add red color cast to shadows:
7032 @section colorchannelmixer
7034 Adjust video input frames by re-mixing color channels.
7036 This filter modifies a color channel by adding the values associated to
7037 the other channels of the same pixels. For example if the value to
7038 modify is red, the output value will be:
7040 @var{red}=@var{red}*@var{rr} + @var{blue}*@var{rb} + @var{green}*@var{rg} + @var{alpha}*@var{ra}
7043 The filter accepts the following options:
7050 Adjust contribution of input red, green, blue and alpha channels for output red channel.
7051 Default is @code{1} for @var{rr}, and @code{0} for @var{rg}, @var{rb} and @var{ra}.
7057 Adjust contribution of input red, green, blue and alpha channels for output green channel.
7058 Default is @code{1} for @var{gg}, and @code{0} for @var{gr}, @var{gb} and @var{ga}.
7064 Adjust contribution of input red, green, blue and alpha channels for output blue channel.
7065 Default is @code{1} for @var{bb}, and @code{0} for @var{br}, @var{bg} and @var{ba}.
7071 Adjust contribution of input red, green, blue and alpha channels for output alpha channel.
7072 Default is @code{1} for @var{aa}, and @code{0} for @var{ar}, @var{ag} and @var{ab}.
7074 Allowed ranges for options are @code{[-2.0, 2.0]}.
7077 @subsection Examples
7081 Convert source to grayscale:
7083 colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3
7086 Simulate sepia tones:
7088 colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131
7093 RGB colorspace color keying.
7095 The filter accepts the following options:
7099 The color which will be replaced with transparency.
7102 Similarity percentage with the key color.
7104 0.01 matches only the exact key color, while 1.0 matches everything.
7109 0.0 makes pixels either fully transparent, or not transparent at all.
7111 Higher values result in semi-transparent pixels, with a higher transparency
7112 the more similar the pixels color is to the key color.
7115 @subsection Examples
7119 Make every green pixel in the input image transparent:
7121 ffmpeg -i input.png -vf colorkey=green out.png
7125 Overlay a greenscreen-video on top of a static background image.
7127 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
7132 Remove all color information for all RGB colors except for certain one.
7134 The filter accepts the following options:
7138 The color which will not be replaced with neutral gray.
7141 Similarity percentage with the above color.
7142 0.01 matches only the exact key color, while 1.0 matches everything.
7145 Blend percentage. 0.0 makes pixels fully gray.
7146 Higher values result in more preserved color.
7149 @section colorlevels
7151 Adjust video input frames using levels.
7153 The filter accepts the following options:
7160 Adjust red, green, blue and alpha input black point.
7161 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
7167 Adjust red, green, blue and alpha input white point.
7168 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{1}.
7170 Input levels are used to lighten highlights (bright tones), darken shadows
7171 (dark tones), change the balance of bright and dark tones.
7177 Adjust red, green, blue and alpha output black point.
7178 Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{0}.
7184 Adjust red, green, blue and alpha output white point.
7185 Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{1}.
7187 Output levels allows manual selection of a constrained output level range.
7190 @subsection Examples
7194 Make video output darker:
7196 colorlevels=rimin=0.058:gimin=0.058:bimin=0.058
7202 colorlevels=rimin=0.039:gimin=0.039:bimin=0.039:rimax=0.96:gimax=0.96:bimax=0.96
7206 Make video output lighter:
7208 colorlevels=rimax=0.902:gimax=0.902:bimax=0.902
7212 Increase brightness:
7214 colorlevels=romin=0.5:gomin=0.5:bomin=0.5
7218 @section colormatrix
7220 Convert color matrix.
7222 The filter accepts the following options:
7227 Specify the source and destination color matrix. Both values must be
7230 The accepted values are:
7258 For example to convert from BT.601 to SMPTE-240M, use the command:
7260 colormatrix=bt601:smpte240m
7265 Convert colorspace, transfer characteristics or color primaries.
7266 Input video needs to have an even size.
7268 The filter accepts the following options:
7273 Specify all color properties at once.
7275 The accepted values are:
7305 Specify output colorspace.
7307 The accepted values are:
7316 BT.470BG or BT.601-6 625
7319 SMPTE-170M or BT.601-6 525
7328 BT.2020 with non-constant luminance
7334 Specify output transfer characteristics.
7336 The accepted values are:
7348 Constant gamma of 2.2
7351 Constant gamma of 2.8
7354 SMPTE-170M, BT.601-6 625 or BT.601-6 525
7372 BT.2020 for 10-bits content
7375 BT.2020 for 12-bits content
7381 Specify output color primaries.
7383 The accepted values are:
7392 BT.470BG or BT.601-6 625
7395 SMPTE-170M or BT.601-6 525
7419 Specify output color range.
7421 The accepted values are:
7424 TV (restricted) range
7427 MPEG (restricted) range
7438 Specify output color format.
7440 The accepted values are:
7443 YUV 4:2:0 planar 8-bits
7446 YUV 4:2:0 planar 10-bits
7449 YUV 4:2:0 planar 12-bits
7452 YUV 4:2:2 planar 8-bits
7455 YUV 4:2:2 planar 10-bits
7458 YUV 4:2:2 planar 12-bits
7461 YUV 4:4:4 planar 8-bits
7464 YUV 4:4:4 planar 10-bits
7467 YUV 4:4:4 planar 12-bits
7472 Do a fast conversion, which skips gamma/primary correction. This will take
7473 significantly less CPU, but will be mathematically incorrect. To get output
7474 compatible with that produced by the colormatrix filter, use fast=1.
7477 Specify dithering mode.
7479 The accepted values are:
7485 Floyd-Steinberg dithering
7489 Whitepoint adaptation mode.
7491 The accepted values are:
7494 Bradford whitepoint adaptation
7497 von Kries whitepoint adaptation
7500 identity whitepoint adaptation (i.e. no whitepoint adaptation)
7504 Override all input properties at once. Same accepted values as @ref{all}.
7507 Override input colorspace. Same accepted values as @ref{space}.
7510 Override input color primaries. Same accepted values as @ref{primaries}.
7513 Override input transfer characteristics. Same accepted values as @ref{trc}.
7516 Override input color range. Same accepted values as @ref{range}.
7520 The filter converts the transfer characteristics, color space and color
7521 primaries to the specified user values. The output value, if not specified,
7522 is set to a default value based on the "all" property. If that property is
7523 also not specified, the filter will log an error. The output color range and
7524 format default to the same value as the input color range and format. The
7525 input transfer characteristics, color space, color primaries and color range
7526 should be set on the input data. If any of these are missing, the filter will
7527 log an error and no conversion will take place.
7529 For example to convert the input to SMPTE-240M, use the command:
7531 colorspace=smpte240m
7534 @section convolution
7536 Apply convolution of 3x3, 5x5, 7x7 or horizontal/vertical up to 49 elements.
7538 The filter accepts the following options:
7545 Set matrix for each plane.
7546 Matrix is sequence of 9, 25 or 49 signed integers in @var{square} mode,
7547 and from 1 to 49 odd number of signed integers in @var{row} mode.
7553 Set multiplier for calculated value for each plane.
7554 If unset or 0, it will be sum of all matrix elements.
7560 Set bias for each plane. This value is added to the result of the multiplication.
7561 Useful for making the overall image brighter or darker. Default is 0.0.
7567 Set matrix mode for each plane. Can be @var{square}, @var{row} or @var{column}.
7568 Default is @var{square}.
7571 @subsection Examples
7577 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"
7583 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"
7589 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"
7595 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"
7599 Apply laplacian edge detector which includes diagonals:
7601 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"
7607 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"
7613 Apply 2D convolution of video stream in frequency domain using second stream
7616 The filter accepts the following options:
7620 Set which planes to process.
7623 Set which impulse video frames will be processed, can be @var{first}
7624 or @var{all}. Default is @var{all}.
7627 The @code{convolve} filter also supports the @ref{framesync} options.
7631 Copy the input video source unchanged to the output. This is mainly useful for
7636 Video filtering on GPU using Apple's CoreImage API on OSX.
7638 Hardware acceleration is based on an OpenGL context. Usually, this means it is
7639 processed by video hardware. However, software-based OpenGL implementations
7640 exist which means there is no guarantee for hardware processing. It depends on
7643 There are many filters and image generators provided by Apple that come with a
7644 large variety of options. The filter has to be referenced by its name along
7647 The coreimage filter accepts the following options:
7650 List all available filters and generators along with all their respective
7651 options as well as possible minimum and maximum values along with the default
7658 Specify all filters by their respective name and options.
7659 Use @var{list_filters} to determine all valid filter names and options.
7660 Numerical options are specified by a float value and are automatically clamped
7661 to their respective value range. Vector and color options have to be specified
7662 by a list of space separated float values. Character escaping has to be done.
7663 A special option name @code{default} is available to use default options for a
7666 It is required to specify either @code{default} or at least one of the filter options.
7667 All omitted options are used with their default values.
7668 The syntax of the filter string is as follows:
7670 filter=<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...][#<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...]][#...]
7674 Specify a rectangle where the output of the filter chain is copied into the
7675 input image. It is given by a list of space separated float values:
7677 output_rect=x\ y\ width\ height
7679 If not given, the output rectangle equals the dimensions of the input image.
7680 The output rectangle is automatically cropped at the borders of the input
7681 image. Negative values are valid for each component.
7683 output_rect=25\ 25\ 100\ 100
7687 Several filters can be chained for successive processing without GPU-HOST
7688 transfers allowing for fast processing of complex filter chains.
7689 Currently, only filters with zero (generators) or exactly one (filters) input
7690 image and one output image are supported. Also, transition filters are not yet
7693 Some filters generate output images with additional padding depending on the
7694 respective filter kernel. The padding is automatically removed to ensure the
7695 filter output has the same size as the input image.
7697 For image generators, the size of the output image is determined by the
7698 previous output image of the filter chain or the input image of the whole
7699 filterchain, respectively. The generators do not use the pixel information of
7700 this image to generate their output. However, the generated output is
7701 blended onto this image, resulting in partial or complete coverage of the
7704 The @ref{coreimagesrc} video source can be used for generating input images
7705 which are directly fed into the filter chain. By using it, providing input
7706 images by another video source or an input video is not required.
7708 @subsection Examples
7713 List all filters available:
7715 coreimage=list_filters=true
7719 Use the CIBoxBlur filter with default options to blur an image:
7721 coreimage=filter=CIBoxBlur@@default
7725 Use a filter chain with CISepiaTone at default values and CIVignetteEffect with
7726 its center at 100x100 and a radius of 50 pixels:
7728 coreimage=filter=CIBoxBlur@@default#CIVignetteEffect@@inputCenter=100\ 100@@inputRadius=50
7732 Use nullsrc and CIQRCodeGenerator to create a QR code for the FFmpeg homepage,
7733 given as complete and escaped command-line for Apple's standard bash shell:
7735 ffmpeg -f lavfi -i nullsrc=s=100x100,coreimage=filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png
7741 Cover a rectangular object
7743 It accepts the following options:
7747 Filepath of the optional cover image, needs to be in yuv420.
7752 It accepts the following values:
7755 cover it by the supplied image
7757 cover it by interpolating the surrounding pixels
7760 Default value is @var{blur}.
7763 @subsection Examples
7767 Cover a rectangular object by the supplied image of a given video using @command{ffmpeg}:
7769 ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
7775 Crop the input video to given dimensions.
7777 It accepts the following parameters:
7781 The width of the output video. It defaults to @code{iw}.
7782 This expression is evaluated only once during the filter
7783 configuration, or when the @samp{w} or @samp{out_w} command is sent.
7786 The height of the output video. It defaults to @code{ih}.
7787 This expression is evaluated only once during the filter
7788 configuration, or when the @samp{h} or @samp{out_h} command is sent.
7791 The horizontal position, in the input video, of the left edge of the output
7792 video. It defaults to @code{(in_w-out_w)/2}.
7793 This expression is evaluated per-frame.
7796 The vertical position, in the input video, of the top edge of the output video.
7797 It defaults to @code{(in_h-out_h)/2}.
7798 This expression is evaluated per-frame.
7801 If set to 1 will force the output display aspect ratio
7802 to be the same of the input, by changing the output sample aspect
7803 ratio. It defaults to 0.
7806 Enable exact cropping. If enabled, subsampled videos will be cropped at exact
7807 width/height/x/y as specified and will not be rounded to nearest smaller value.
7811 The @var{out_w}, @var{out_h}, @var{x}, @var{y} parameters are
7812 expressions containing the following constants:
7817 The computed values for @var{x} and @var{y}. They are evaluated for
7822 The input width and height.
7826 These are the same as @var{in_w} and @var{in_h}.
7830 The output (cropped) width and height.
7834 These are the same as @var{out_w} and @var{out_h}.
7837 same as @var{iw} / @var{ih}
7840 input sample aspect ratio
7843 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
7847 horizontal and vertical chroma subsample values. For example for the
7848 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
7851 The number of the input frame, starting from 0.
7854 the position in the file of the input frame, NAN if unknown
7857 The timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
7861 The expression for @var{out_w} may depend on the value of @var{out_h},
7862 and the expression for @var{out_h} may depend on @var{out_w}, but they
7863 cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are
7864 evaluated after @var{out_w} and @var{out_h}.
7866 The @var{x} and @var{y} parameters specify the expressions for the
7867 position of the top-left corner of the output (non-cropped) area. They
7868 are evaluated for each frame. If the evaluated value is not valid, it
7869 is approximated to the nearest valid value.
7871 The expression for @var{x} may depend on @var{y}, and the expression
7872 for @var{y} may depend on @var{x}.
7874 @subsection Examples
7878 Crop area with size 100x100 at position (12,34).
7883 Using named options, the example above becomes:
7885 crop=w=100:h=100:x=12:y=34
7889 Crop the central input area with size 100x100:
7895 Crop the central input area with size 2/3 of the input video:
7897 crop=2/3*in_w:2/3*in_h
7901 Crop the input video central square:
7908 Delimit the rectangle with the top-left corner placed at position
7909 100:100 and the right-bottom corner corresponding to the right-bottom
7910 corner of the input image.
7912 crop=in_w-100:in_h-100:100:100
7916 Crop 10 pixels from the left and right borders, and 20 pixels from
7917 the top and bottom borders
7919 crop=in_w-2*10:in_h-2*20
7923 Keep only the bottom right quarter of the input image:
7925 crop=in_w/2:in_h/2:in_w/2:in_h/2
7929 Crop height for getting Greek harmony:
7931 crop=in_w:1/PHI*in_w
7935 Apply trembling effect:
7937 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)
7941 Apply erratic camera effect depending on timestamp:
7943 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)"
7947 Set x depending on the value of y:
7949 crop=in_w/2:in_h/2:y:10+10*sin(n/10)
7953 @subsection Commands
7955 This filter supports the following commands:
7961 Set width/height of the output video and the horizontal/vertical position
7963 The command accepts the same syntax of the corresponding option.
7965 If the specified expression is not valid, it is kept at its current
7971 Auto-detect the crop size.
7973 It calculates the necessary cropping parameters and prints the
7974 recommended parameters via the logging system. The detected dimensions
7975 correspond to the non-black area of the input video.
7977 It accepts the following parameters:
7982 Set higher black value threshold, which can be optionally specified
7983 from nothing (0) to everything (255 for 8-bit based formats). An intensity
7984 value greater to the set value is considered non-black. It defaults to 24.
7985 You can also specify a value between 0.0 and 1.0 which will be scaled depending
7986 on the bitdepth of the pixel format.
7989 The value which the width/height should be divisible by. It defaults to
7990 16. The offset is automatically adjusted to center the video. Use 2 to
7991 get only even dimensions (needed for 4:2:2 video). 16 is best when
7992 encoding to most video codecs.
7994 @item reset_count, reset
7995 Set the counter that determines after how many frames cropdetect will
7996 reset the previously detected largest video area and start over to
7997 detect the current optimal crop area. Default value is 0.
7999 This can be useful when channel logos distort the video area. 0
8000 indicates 'never reset', and returns the largest area encountered during
8007 Delay video filtering until a given wallclock timestamp. The filter first
8008 passes on @option{preroll} amount of frames, then it buffers at most
8009 @option{buffer} amount of frames and waits for the cue. After reaching the cue
8010 it forwards the buffered frames and also any subsequent frames coming in its
8013 The filter can be used synchronize the output of multiple ffmpeg processes for
8014 realtime output devices like decklink. By putting the delay in the filtering
8015 chain and pre-buffering frames the process can pass on data to output almost
8016 immediately after the target wallclock timestamp is reached.
8018 Perfect frame accuracy cannot be guaranteed, but the result is good enough for
8024 The cue timestamp expressed in a UNIX timestamp in microseconds. Default is 0.
8027 The duration of content to pass on as preroll expressed in seconds. Default is 0.
8030 The maximum duration of content to buffer before waiting for the cue expressed
8031 in seconds. Default is 0.
8038 Apply color adjustments using curves.
8040 This filter is similar to the Adobe Photoshop and GIMP curves tools. Each
8041 component (red, green and blue) has its values defined by @var{N} key points
8042 tied from each other using a smooth curve. The x-axis represents the pixel
8043 values from the input frame, and the y-axis the new pixel values to be set for
8046 By default, a component curve is defined by the two points @var{(0;0)} and
8047 @var{(1;1)}. This creates a straight line where each original pixel value is
8048 "adjusted" to its own value, which means no change to the image.
8050 The filter allows you to redefine these two points and add some more. A new
8051 curve (using a natural cubic spline interpolation) will be define to pass
8052 smoothly through all these new coordinates. The new defined points needs to be
8053 strictly increasing over the x-axis, and their @var{x} and @var{y} values must
8054 be in the @var{[0;1]} interval. If the computed curves happened to go outside
8055 the vector spaces, the values will be clipped accordingly.
8057 The filter accepts the following options:
8061 Select one of the available color presets. This option can be used in addition
8062 to the @option{r}, @option{g}, @option{b} parameters; in this case, the later
8063 options takes priority on the preset values.
8064 Available presets are:
8067 @item color_negative
8070 @item increase_contrast
8072 @item linear_contrast
8073 @item medium_contrast
8075 @item strong_contrast
8078 Default is @code{none}.
8080 Set the master key points. These points will define a second pass mapping. It
8081 is sometimes called a "luminance" or "value" mapping. It can be used with
8082 @option{r}, @option{g}, @option{b} or @option{all} since it acts like a
8083 post-processing LUT.
8085 Set the key points for the red component.
8087 Set the key points for the green component.
8089 Set the key points for the blue component.
8091 Set the key points for all components (not including master).
8092 Can be used in addition to the other key points component
8093 options. In this case, the unset component(s) will fallback on this
8094 @option{all} setting.
8096 Specify a Photoshop curves file (@code{.acv}) to import the settings from.
8098 Save Gnuplot script of the curves in specified file.
8101 To avoid some filtergraph syntax conflicts, each key points list need to be
8102 defined using the following syntax: @code{x0/y0 x1/y1 x2/y2 ...}.
8104 @subsection Examples
8108 Increase slightly the middle level of blue:
8110 curves=blue='0/0 0.5/0.58 1/1'
8116 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'
8118 Here we obtain the following coordinates for each components:
8121 @code{(0;0.11) (0.42;0.51) (1;0.95)}
8123 @code{(0;0) (0.50;0.48) (1;1)}
8125 @code{(0;0.22) (0.49;0.44) (1;0.80)}
8129 The previous example can also be achieved with the associated built-in preset:
8131 curves=preset=vintage
8141 Use a Photoshop preset and redefine the points of the green component:
8143 curves=psfile='MyCurvesPresets/purple.acv':green='0/0 0.45/0.53 1/1'
8147 Check out the curves of the @code{cross_process} profile using @command{ffmpeg}
8148 and @command{gnuplot}:
8150 ffmpeg -f lavfi -i color -vf curves=cross_process:plot=/tmp/curves.plt -frames:v 1 -f null -
8151 gnuplot -p /tmp/curves.plt
8157 Video data analysis filter.
8159 This filter shows hexadecimal pixel values of part of video.
8161 The filter accepts the following options:
8165 Set output video size.
8168 Set x offset from where to pick pixels.
8171 Set y offset from where to pick pixels.
8174 Set scope mode, can be one of the following:
8177 Draw hexadecimal pixel values with white color on black background.
8180 Draw hexadecimal pixel values with input video pixel color on black
8184 Draw hexadecimal pixel values on color background picked from input video,
8185 the text color is picked in such way so its always visible.
8189 Draw rows and columns numbers on left and top of video.
8192 Set background opacity.
8197 Denoise frames using 2D DCT (frequency domain filtering).
8199 This filter is not designed for real time.
8201 The filter accepts the following options:
8205 Set the noise sigma constant.
8207 This @var{sigma} defines a hard threshold of @code{3 * sigma}; every DCT
8208 coefficient (absolute value) below this threshold with be dropped.
8210 If you need a more advanced filtering, see @option{expr}.
8212 Default is @code{0}.
8215 Set number overlapping pixels for each block. Since the filter can be slow, you
8216 may want to reduce this value, at the cost of a less effective filter and the
8217 risk of various artefacts.
8219 If the overlapping value doesn't permit processing the whole input width or
8220 height, a warning will be displayed and according borders won't be denoised.
8222 Default value is @var{blocksize}-1, which is the best possible setting.
8225 Set the coefficient factor expression.
8227 For each coefficient of a DCT block, this expression will be evaluated as a
8228 multiplier value for the coefficient.
8230 If this is option is set, the @option{sigma} option will be ignored.
8232 The absolute value of the coefficient can be accessed through the @var{c}
8236 Set the @var{blocksize} using the number of bits. @code{1<<@var{n}} defines the
8237 @var{blocksize}, which is the width and height of the processed blocks.
8239 The default value is @var{3} (8x8) and can be raised to @var{4} for a
8240 @var{blocksize} of 16x16. Note that changing this setting has huge consequences
8241 on the speed processing. Also, a larger block size does not necessarily means a
8245 @subsection Examples
8247 Apply a denoise with a @option{sigma} of @code{4.5}:
8252 The same operation can be achieved using the expression system:
8254 dctdnoiz=e='gte(c, 4.5*3)'
8257 Violent denoise using a block size of @code{16x16}:
8264 Remove banding artifacts from input video.
8265 It works by replacing banded pixels with average value of referenced pixels.
8267 The filter accepts the following options:
8274 Set banding detection threshold for each plane. Default is 0.02.
8275 Valid range is 0.00003 to 0.5.
8276 If difference between current pixel and reference pixel is less than threshold,
8277 it will be considered as banded.
8280 Banding detection range in pixels. Default is 16. If positive, random number
8281 in range 0 to set value will be used. If negative, exact absolute value
8283 The range defines square of four pixels around current pixel.
8286 Set direction in radians from which four pixel will be compared. If positive,
8287 random direction from 0 to set direction will be picked. If negative, exact of
8288 absolute value will be picked. For example direction 0, -PI or -2*PI radians
8289 will pick only pixels on same row and -PI/2 will pick only pixels on same
8293 If enabled, current pixel is compared with average value of all four
8294 surrounding pixels. The default is enabled. If disabled current pixel is
8295 compared with all four surrounding pixels. The pixel is considered banded
8296 if only all four differences with surrounding pixels are less than threshold.
8299 If enabled, current pixel is changed if and only if all pixel components are banded,
8300 e.g. banding detection threshold is triggered for all color components.
8301 The default is disabled.
8306 Remove blocking artifacts from input video.
8308 The filter accepts the following options:
8312 Set filter type, can be @var{weak} or @var{strong}. Default is @var{strong}.
8313 This controls what kind of deblocking is applied.
8316 Set size of block, allowed range is from 4 to 512. Default is @var{8}.
8322 Set blocking detection thresholds. Allowed range is 0 to 1.
8323 Defaults are: @var{0.098} for @var{alpha} and @var{0.05} for the rest.
8324 Using higher threshold gives more deblocking strength.
8325 Setting @var{alpha} controls threshold detection at exact edge of block.
8326 Remaining options controls threshold detection near the edge. Each one for
8327 below/above or left/right. Setting any of those to @var{0} disables
8331 Set planes to filter. Default is to filter all available planes.
8334 @subsection Examples
8338 Deblock using weak filter and block size of 4 pixels.
8340 deblock=filter=weak:block=4
8344 Deblock using strong filter, block size of 4 pixels and custom thresholds for
8345 deblocking more edges.
8347 deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05
8351 Similar as above, but filter only first plane.
8353 deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=1
8357 Similar as above, but filter only second and third plane.
8359 deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=6
8366 Drop duplicated frames at regular intervals.
8368 The filter accepts the following options:
8372 Set the number of frames from which one will be dropped. Setting this to
8373 @var{N} means one frame in every batch of @var{N} frames will be dropped.
8374 Default is @code{5}.
8377 Set the threshold for duplicate detection. If the difference metric for a frame
8378 is less than or equal to this value, then it is declared as duplicate. Default
8382 Set scene change threshold. Default is @code{15}.
8386 Set the size of the x and y-axis blocks used during metric calculations.
8387 Larger blocks give better noise suppression, but also give worse detection of
8388 small movements. Must be a power of two. Default is @code{32}.
8391 Mark main input as a pre-processed input and activate clean source input
8392 stream. This allows the input to be pre-processed with various filters to help
8393 the metrics calculation while keeping the frame selection lossless. When set to
8394 @code{1}, the first stream is for the pre-processed input, and the second
8395 stream is the clean source from where the kept frames are chosen. Default is
8399 Set whether or not chroma is considered in the metric calculations. Default is
8405 Apply 2D deconvolution of video stream in frequency domain using second stream
8408 The filter accepts the following options:
8412 Set which planes to process.
8415 Set which impulse video frames will be processed, can be @var{first}
8416 or @var{all}. Default is @var{all}.
8419 Set noise when doing divisions. Default is @var{0.0000001}. Useful when width
8420 and height are not same and not power of 2 or if stream prior to convolving
8424 The @code{deconvolve} filter also supports the @ref{framesync} options.
8428 Reduce cross-luminance (dot-crawl) and cross-color (rainbows) from video.
8430 It accepts the following options:
8434 Set mode of operation. Can be combination of @var{dotcrawl} for cross-luminance reduction and/or
8435 @var{rainbows} for cross-color reduction.
8438 Set spatial luma threshold. Lower values increases reduction of cross-luminance.
8441 Set tolerance for temporal luma. Higher values increases reduction of cross-luminance.
8444 Set tolerance for chroma temporal variation. Higher values increases reduction of cross-color.
8447 Set temporal chroma threshold. Lower values increases reduction of cross-color.
8452 Apply deflate effect to the video.
8454 This filter replaces the pixel by the local(3x3) average by taking into account
8455 only values lower than the pixel.
8457 It accepts the following options:
8464 Limit the maximum change for each plane, default is 65535.
8465 If 0, plane will remain unchanged.
8470 Remove temporal frame luminance variations.
8472 It accepts the following options:
8476 Set moving-average filter size in frames. Default is 5. Allowed range is 2 - 129.
8479 Set averaging mode to smooth temporal luminance variations.
8481 Available values are:
8506 Do not actually modify frame. Useful when one only wants metadata.
8511 Remove judder produced by partially interlaced telecined content.
8513 Judder can be introduced, for instance, by @ref{pullup} filter. If the original
8514 source was partially telecined content then the output of @code{pullup,dejudder}
8515 will have a variable frame rate. May change the recorded frame rate of the
8516 container. Aside from that change, this filter will not affect constant frame
8519 The option available in this filter is:
8523 Specify the length of the window over which the judder repeats.
8525 Accepts any integer greater than 1. Useful values are:
8529 If the original was telecined from 24 to 30 fps (Film to NTSC).
8532 If the original was telecined from 25 to 30 fps (PAL to NTSC).
8535 If a mixture of the two.
8538 The default is @samp{4}.
8543 Suppress a TV station logo by a simple interpolation of the surrounding
8544 pixels. Just set a rectangle covering the logo and watch it disappear
8545 (and sometimes something even uglier appear - your mileage may vary).
8547 It accepts the following parameters:
8552 Specify the top left corner coordinates of the logo. They must be
8557 Specify the width and height of the logo to clear. They must be
8561 Specify the thickness of the fuzzy edge of the rectangle (added to
8562 @var{w} and @var{h}). The default value is 1. This option is
8563 deprecated, setting higher values should no longer be necessary and
8567 When set to 1, a green rectangle is drawn on the screen to simplify
8568 finding the right @var{x}, @var{y}, @var{w}, and @var{h} parameters.
8569 The default value is 0.
8571 The rectangle is drawn on the outermost pixels which will be (partly)
8572 replaced with interpolated values. The values of the next pixels
8573 immediately outside this rectangle in each direction will be used to
8574 compute the interpolated pixel values inside the rectangle.
8578 @subsection Examples
8582 Set a rectangle covering the area with top left corner coordinates 0,0
8583 and size 100x77, and a band of size 10:
8585 delogo=x=0:y=0:w=100:h=77:band=10
8592 Remove the rain in the input image/video by applying the derain methods based on
8593 convolutional neural networks. Supported models:
8597 Recurrent Squeeze-and-Excitation Context Aggregation Net (RESCAN).
8598 See @url{http://openaccess.thecvf.com/content_ECCV_2018/papers/Xia_Li_Recurrent_Squeeze-and-Excitation_Context_ECCV_2018_paper.pdf}.
8601 Training as well as model generation scripts are provided in
8602 the repository at @url{https://github.com/XueweiMeng/derain_filter.git}.
8604 Native model files (.model) can be generated from TensorFlow model
8605 files (.pb) by using tools/python/convert.py
8607 The filter accepts the following options:
8611 Specify which filter to use. This option accepts the following values:
8615 Derain filter. To conduct derain filter, you need to use a derain model.
8618 Dehaze filter. To conduct dehaze filter, you need to use a dehaze model.
8620 Default value is @samp{derain}.
8623 Specify which DNN backend to use for model loading and execution. This option accepts
8624 the following values:
8628 Native implementation of DNN loading and execution.
8631 TensorFlow backend. To enable this backend you
8632 need to install the TensorFlow for C library (see
8633 @url{https://www.tensorflow.org/install/install_c}) and configure FFmpeg with
8634 @code{--enable-libtensorflow}
8636 Default value is @samp{native}.
8639 Set path to model file specifying network architecture and its parameters.
8640 Note that different backends use different file formats. TensorFlow and native
8641 backend can load files for only its format.
8646 Attempt to fix small changes in horizontal and/or vertical shift. This
8647 filter helps remove camera shake from hand-holding a camera, bumping a
8648 tripod, moving on a vehicle, etc.
8650 The filter accepts the following options:
8658 Specify a rectangular area where to limit the search for motion
8660 If desired the search for motion vectors can be limited to a
8661 rectangular area of the frame defined by its top left corner, width
8662 and height. These parameters have the same meaning as the drawbox
8663 filter which can be used to visualise the position of the bounding
8666 This is useful when simultaneous movement of subjects within the frame
8667 might be confused for camera motion by the motion vector search.
8669 If any or all of @var{x}, @var{y}, @var{w} and @var{h} are set to -1
8670 then the full frame is used. This allows later options to be set
8671 without specifying the bounding box for the motion vector search.
8673 Default - search the whole frame.
8677 Specify the maximum extent of movement in x and y directions in the
8678 range 0-64 pixels. Default 16.
8681 Specify how to generate pixels to fill blanks at the edge of the
8682 frame. Available values are:
8685 Fill zeroes at blank locations
8687 Original image at blank locations
8689 Extruded edge value at blank locations
8691 Mirrored edge at blank locations
8693 Default value is @samp{mirror}.
8696 Specify the blocksize to use for motion search. Range 4-128 pixels,
8700 Specify the contrast threshold for blocks. Only blocks with more than
8701 the specified contrast (difference between darkest and lightest
8702 pixels) will be considered. Range 1-255, default 125.
8705 Specify the search strategy. Available values are:
8708 Set exhaustive search
8710 Set less exhaustive search.
8712 Default value is @samp{exhaustive}.
8715 If set then a detailed log of the motion search is written to the
8722 Remove unwanted contamination of foreground colors, caused by reflected color of
8723 greenscreen or bluescreen.
8725 This filter accepts the following options:
8729 Set what type of despill to use.
8732 Set how spillmap will be generated.
8735 Set how much to get rid of still remaining spill.
8738 Controls amount of red in spill area.
8741 Controls amount of green in spill area.
8742 Should be -1 for greenscreen.
8745 Controls amount of blue in spill area.
8746 Should be -1 for bluescreen.
8749 Controls brightness of spill area, preserving colors.
8752 Modify alpha from generated spillmap.
8757 Apply an exact inverse of the telecine operation. It requires a predefined
8758 pattern specified using the pattern option which must be the same as that passed
8759 to the telecine filter.
8761 This filter accepts the following options:
8770 The default value is @code{top}.
8774 A string of numbers representing the pulldown pattern you wish to apply.
8775 The default value is @code{23}.
8778 A number representing position of the first frame with respect to the telecine
8779 pattern. This is to be used if the stream is cut. The default value is @code{0}.
8784 Apply dilation effect to the video.
8786 This filter replaces the pixel by the local(3x3) maximum.
8788 It accepts the following options:
8795 Limit the maximum change for each plane, default is 65535.
8796 If 0, plane will remain unchanged.
8799 Flag which specifies the pixel to refer to. Default is 255 i.e. all eight
8802 Flags to local 3x3 coordinates maps like this:
8811 Displace pixels as indicated by second and third input stream.
8813 It takes three input streams and outputs one stream, the first input is the
8814 source, and second and third input are displacement maps.
8816 The second input specifies how much to displace pixels along the
8817 x-axis, while the third input specifies how much to displace pixels
8819 If one of displacement map streams terminates, last frame from that
8820 displacement map will be used.
8822 Note that once generated, displacements maps can be reused over and over again.
8824 A description of the accepted options follows.
8828 Set displace behavior for pixels that are out of range.
8830 Available values are:
8833 Missing pixels are replaced by black pixels.
8836 Adjacent pixels will spread out to replace missing pixels.
8839 Out of range pixels are wrapped so they point to pixels of other side.
8842 Out of range pixels will be replaced with mirrored pixels.
8844 Default is @samp{smear}.
8848 @subsection Examples
8852 Add ripple effect to rgb input of video size hd720:
8854 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
8858 Add wave effect to rgb input of video size hd720:
8860 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
8866 Draw a colored box on the input image.
8868 It accepts the following parameters:
8873 The expressions which specify the top left corner coordinates of the box. It defaults to 0.
8877 The expressions which specify the width and height of the box; if 0 they are interpreted as
8878 the input width and height. It defaults to 0.
8881 Specify the color of the box to write. For the general syntax of this option,
8882 check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. If the special
8883 value @code{invert} is used, the box edge color is the same as the
8884 video with inverted luma.
8887 The expression which sets the thickness of the box edge.
8888 A value of @code{fill} will create a filled box. Default value is @code{3}.
8890 See below for the list of accepted constants.
8893 Applicable if the input has alpha. With value @code{1}, the pixels of the painted box
8894 will overwrite the video's color and alpha pixels.
8895 Default is @code{0}, which composites the box onto the input, leaving the video's alpha intact.
8898 The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
8899 following constants:
8903 The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
8907 horizontal and vertical chroma subsample values. For example for the
8908 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
8912 The input width and height.
8915 The input sample aspect ratio.
8919 The x and y offset coordinates where the box is drawn.
8923 The width and height of the drawn box.
8926 The thickness of the drawn box.
8928 These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
8929 each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
8933 @subsection Examples
8937 Draw a black box around the edge of the input image:
8943 Draw a box with color red and an opacity of 50%:
8945 drawbox=10:20:200:60:red@@0.5
8948 The previous example can be specified as:
8950 drawbox=x=10:y=20:w=200:h=60:color=red@@0.5
8954 Fill the box with pink color:
8956 drawbox=x=10:y=10:w=100:h=100:color=pink@@0.5:t=fill
8960 Draw a 2-pixel red 2.40:1 mask:
8962 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
8966 @subsection Commands
8967 This filter supports same commands as options.
8968 The command accepts the same syntax of the corresponding option.
8970 If the specified expression is not valid, it is kept at its current
8975 Draw a grid on the input image.
8977 It accepts the following parameters:
8982 The expressions which specify the coordinates of some point of grid intersection (meant to configure offset). Both default to 0.
8986 The expressions which specify the width and height of the grid cell, if 0 they are interpreted as the
8987 input width and height, respectively, minus @code{thickness}, so image gets
8988 framed. Default to 0.
8991 Specify the color of the grid. For the general syntax of this option,
8992 check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. If the special
8993 value @code{invert} is used, the grid color is the same as the
8994 video with inverted luma.
8997 The expression which sets the thickness of the grid line. Default value is @code{1}.
8999 See below for the list of accepted constants.
9002 Applicable if the input has alpha. With @code{1} the pixels of the painted grid
9003 will overwrite the video's color and alpha pixels.
9004 Default is @code{0}, which composites the grid onto the input, leaving the video's alpha intact.
9007 The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
9008 following constants:
9012 The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
9016 horizontal and vertical chroma subsample values. For example for the
9017 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
9021 The input grid cell width and height.
9024 The input sample aspect ratio.
9028 The x and y coordinates of some point of grid intersection (meant to configure offset).
9032 The width and height of the drawn cell.
9035 The thickness of the drawn cell.
9037 These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
9038 each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
9042 @subsection Examples
9046 Draw a grid with cell 100x100 pixels, thickness 2 pixels, with color red and an opacity of 50%:
9048 drawgrid=width=100:height=100:thickness=2:color=red@@0.5
9052 Draw a white 3x3 grid with an opacity of 50%:
9054 drawgrid=w=iw/3:h=ih/3:t=2:c=white@@0.5
9058 @subsection Commands
9059 This filter supports same commands as options.
9060 The command accepts the same syntax of the corresponding option.
9062 If the specified expression is not valid, it is kept at its current
9068 Draw a text string or text from a specified file on top of a video, using the
9069 libfreetype library.
9071 To enable compilation of this filter, you need to configure FFmpeg with
9072 @code{--enable-libfreetype}.
9073 To enable default font fallback and the @var{font} option you need to
9074 configure FFmpeg with @code{--enable-libfontconfig}.
9075 To enable the @var{text_shaping} option, you need to configure FFmpeg with
9076 @code{--enable-libfribidi}.
9080 It accepts the following parameters:
9085 Used to draw a box around text using the background color.
9086 The value must be either 1 (enable) or 0 (disable).
9087 The default value of @var{box} is 0.
9090 Set the width of the border to be drawn around the box using @var{boxcolor}.
9091 The default value of @var{boxborderw} is 0.
9094 The color to be used for drawing box around text. For the syntax of this
9095 option, check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
9097 The default value of @var{boxcolor} is "white".
9100 Set the line spacing in pixels of the border to be drawn around the box using @var{box}.
9101 The default value of @var{line_spacing} is 0.
9104 Set the width of the border to be drawn around the text using @var{bordercolor}.
9105 The default value of @var{borderw} is 0.
9108 Set the color to be used for drawing border around text. For the syntax of this
9109 option, check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
9111 The default value of @var{bordercolor} is "black".
9114 Select how the @var{text} is expanded. Can be either @code{none},
9115 @code{strftime} (deprecated) or
9116 @code{normal} (default). See the @ref{drawtext_expansion, Text expansion} section
9120 Set a start time for the count. Value is in microseconds. Only applied
9121 in the deprecated strftime expansion mode. To emulate in normal expansion
9122 mode use the @code{pts} function, supplying the start time (in seconds)
9123 as the second argument.
9126 If true, check and fix text coords to avoid clipping.
9129 The color to be used for drawing fonts. For the syntax of this option, check
9130 the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
9132 The default value of @var{fontcolor} is "black".
9134 @item fontcolor_expr
9135 String which is expanded the same way as @var{text} to obtain dynamic
9136 @var{fontcolor} value. By default this option has empty value and is not
9137 processed. When this option is set, it overrides @var{fontcolor} option.
9140 The font family to be used for drawing text. By default Sans.
9143 The font file to be used for drawing text. The path must be included.
9144 This parameter is mandatory if the fontconfig support is disabled.
9147 Draw the text applying alpha blending. The value can
9148 be a number between 0.0 and 1.0.
9149 The expression accepts the same variables @var{x, y} as well.
9150 The default value is 1.
9151 Please see @var{fontcolor_expr}.
9154 The font size to be used for drawing text.
9155 The default value of @var{fontsize} is 16.
9158 If set to 1, attempt to shape the text (for example, reverse the order of
9159 right-to-left text and join Arabic characters) before drawing it.
9160 Otherwise, just draw the text exactly as given.
9161 By default 1 (if supported).
9164 The flags to be used for loading the fonts.
9166 The flags map the corresponding flags supported by libfreetype, and are
9167 a combination of the following values:
9174 @item vertical_layout
9175 @item force_autohint
9178 @item ignore_global_advance_width
9180 @item ignore_transform
9186 Default value is "default".
9188 For more information consult the documentation for the FT_LOAD_*
9192 The color to be used for drawing a shadow behind the drawn text. For the
9193 syntax of this option, check the @ref{color syntax,,"Color" section in the
9194 ffmpeg-utils manual,ffmpeg-utils}.
9196 The default value of @var{shadowcolor} is "black".
9200 The x and y offsets for the text shadow position with respect to the
9201 position of the text. They can be either positive or negative
9202 values. The default value for both is "0".
9205 The starting frame number for the n/frame_num variable. The default value
9209 The size in number of spaces to use for rendering the tab.
9213 Set the initial timecode representation in "hh:mm:ss[:;.]ff"
9214 format. It can be used with or without text parameter. @var{timecode_rate}
9215 option must be specified.
9217 @item timecode_rate, rate, r
9218 Set the timecode frame rate (timecode only). Value will be rounded to nearest
9219 integer. Minimum value is "1".
9220 Drop-frame timecode is supported for frame rates 30 & 60.
9223 If set to 1, the output of the timecode option will wrap around at 24 hours.
9224 Default is 0 (disabled).
9227 The text string to be drawn. The text must be a sequence of UTF-8
9229 This parameter is mandatory if no file is specified with the parameter
9233 A text file containing text to be drawn. The text must be a sequence
9234 of UTF-8 encoded characters.
9236 This parameter is mandatory if no text string is specified with the
9237 parameter @var{text}.
9239 If both @var{text} and @var{textfile} are specified, an error is thrown.
9242 If set to 1, the @var{textfile} will be reloaded before each frame.
9243 Be sure to update it atomically, or it may be read partially, or even fail.
9247 The expressions which specify the offsets where text will be drawn
9248 within the video frame. They are relative to the top/left border of the
9251 The default value of @var{x} and @var{y} is "0".
9253 See below for the list of accepted constants and functions.
9256 The parameters for @var{x} and @var{y} are expressions containing the
9257 following constants and functions:
9261 input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
9265 horizontal and vertical chroma subsample values. For example for the
9266 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
9269 the height of each text line
9277 @item max_glyph_a, ascent
9278 the maximum distance from the baseline to the highest/upper grid
9279 coordinate used to place a glyph outline point, for all the rendered
9281 It is a positive value, due to the grid's orientation with the Y axis
9284 @item max_glyph_d, descent
9285 the maximum distance from the baseline to the lowest grid coordinate
9286 used to place a glyph outline point, for all the rendered glyphs.
9287 This is a negative value, due to the grid's orientation, with the Y axis
9291 maximum glyph height, that is the maximum height for all the glyphs
9292 contained in the rendered text, it is equivalent to @var{ascent} -
9296 maximum glyph width, that is the maximum width for all the glyphs
9297 contained in the rendered text
9300 the number of input frame, starting from 0
9302 @item rand(min, max)
9303 return a random number included between @var{min} and @var{max}
9306 The input sample aspect ratio.
9309 timestamp expressed in seconds, NAN if the input timestamp is unknown
9312 the height of the rendered text
9315 the width of the rendered text
9319 the x and y offset coordinates where the text is drawn.
9321 These parameters allow the @var{x} and @var{y} expressions to refer
9322 to each other, so you can for example specify @code{y=x/dar}.
9325 A one character description of the current frame's picture type.
9328 The current packet's position in the input file or stream
9329 (in bytes, from the start of the input). A value of -1 indicates
9330 this info is not available.
9333 The current packet's duration, in seconds.
9336 The current packet's size (in bytes).
9339 @anchor{drawtext_expansion}
9340 @subsection Text expansion
9342 If @option{expansion} is set to @code{strftime},
9343 the filter recognizes strftime() sequences in the provided text and
9344 expands them accordingly. Check the documentation of strftime(). This
9345 feature is deprecated.
9347 If @option{expansion} is set to @code{none}, the text is printed verbatim.
9349 If @option{expansion} is set to @code{normal} (which is the default),
9350 the following expansion mechanism is used.
9352 The backslash character @samp{\}, followed by any character, always expands to
9353 the second character.
9355 Sequences of the form @code{%@{...@}} are expanded. The text between the
9356 braces is a function name, possibly followed by arguments separated by ':'.
9357 If the arguments contain special characters or delimiters (':' or '@}'),
9358 they should be escaped.
9360 Note that they probably must also be escaped as the value for the
9361 @option{text} option in the filter argument string and as the filter
9362 argument in the filtergraph description, and possibly also for the shell,
9363 that makes up to four levels of escaping; using a text file avoids these
9366 The following functions are available:
9371 The expression evaluation result.
9373 It must take one argument specifying the expression to be evaluated,
9374 which accepts the same constants and functions as the @var{x} and
9375 @var{y} values. Note that not all constants should be used, for
9376 example the text size is not known when evaluating the expression, so
9377 the constants @var{text_w} and @var{text_h} will have an undefined
9380 @item expr_int_format, eif
9381 Evaluate the expression's value and output as formatted integer.
9383 The first argument is the expression to be evaluated, just as for the @var{expr} function.
9384 The second argument specifies the output format. Allowed values are @samp{x},
9385 @samp{X}, @samp{d} and @samp{u}. They are treated exactly as in the
9386 @code{printf} function.
9387 The third parameter is optional and sets the number of positions taken by the output.
9388 It can be used to add padding with zeros from the left.
9391 The time at which the filter is running, expressed in UTC.
9392 It can accept an argument: a strftime() format string.
9395 The time at which the filter is running, expressed in the local time zone.
9396 It can accept an argument: a strftime() format string.
9399 Frame metadata. Takes one or two arguments.
9401 The first argument is mandatory and specifies the metadata key.
9403 The second argument is optional and specifies a default value, used when the
9404 metadata key is not found or empty.
9406 Available metadata can be identified by inspecting entries
9407 starting with TAG included within each frame section
9408 printed by running @code{ffprobe -show_frames}.
9410 String metadata generated in filters leading to
9411 the drawtext filter are also available.
9414 The frame number, starting from 0.
9417 A one character description of the current picture type.
9420 The timestamp of the current frame.
9421 It can take up to three arguments.
9423 The first argument is the format of the timestamp; it defaults to @code{flt}
9424 for seconds as a decimal number with microsecond accuracy; @code{hms} stands
9425 for a formatted @var{[-]HH:MM:SS.mmm} timestamp with millisecond accuracy.
9426 @code{gmtime} stands for the timestamp of the frame formatted as UTC time;
9427 @code{localtime} stands for the timestamp of the frame formatted as
9428 local time zone time.
9430 The second argument is an offset added to the timestamp.
9432 If the format is set to @code{hms}, a third argument @code{24HH} may be
9433 supplied to present the hour part of the formatted timestamp in 24h format
9436 If the format is set to @code{localtime} or @code{gmtime},
9437 a third argument may be supplied: a strftime() format string.
9438 By default, @var{YYYY-MM-DD HH:MM:SS} format will be used.
9441 @subsection Commands
9443 This filter supports altering parameters via commands:
9446 Alter existing filter parameters.
9448 Syntax for the argument is the same as for filter invocation, e.g.
9451 fontsize=56:fontcolor=green:text='Hello World'
9454 Full filter invocation with sendcmd would look like this:
9457 sendcmd=c='56.0 drawtext reinit fontsize=56\:fontcolor=green\:text=Hello\\ World'
9461 If the entire argument can't be parsed or applied as valid values then the filter will
9462 continue with its existing parameters.
9464 @subsection Examples
9468 Draw "Test Text" with font FreeSerif, using the default values for the
9469 optional parameters.
9472 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"
9476 Draw 'Test Text' with font FreeSerif of size 24 at position x=100
9477 and y=50 (counting from the top-left corner of the screen), text is
9478 yellow with a red box around it. Both the text and the box have an
9482 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
9483 x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2"
9486 Note that the double quotes are not necessary if spaces are not used
9487 within the parameter list.
9490 Show the text at the center of the video frame:
9492 drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h)/2"
9496 Show the text at a random position, switching to a new position every 30 seconds:
9498 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)"
9502 Show a text line sliding from right to left in the last row of the video
9503 frame. The file @file{LONG_LINE} is assumed to contain a single line
9506 drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t"
9510 Show the content of file @file{CREDITS} off the bottom of the frame and scroll up.
9512 drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t"
9516 Draw a single green letter "g", at the center of the input video.
9517 The glyph baseline is placed at half screen height.
9519 drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent"
9523 Show text for 1 second every 3 seconds:
9525 drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:enable=lt(mod(t\,3)\,1):text='blink'"
9529 Use fontconfig to set the font. Note that the colons need to be escaped.
9531 drawtext='fontfile=Linux Libertine O-40\:style=Semibold:text=FFmpeg'
9535 Print the date of a real-time encoding (see strftime(3)):
9537 drawtext='fontfile=FreeSans.ttf:text=%@{localtime\:%a %b %d %Y@}'
9541 Show text fading in and out (appearing/disappearing):
9544 DS=1.0 # display start
9545 DE=10.0 # display end
9546 FID=1.5 # fade in duration
9547 FOD=5 # fade out duration
9548 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 @}"
9552 Horizontally align multiple separate texts. Note that @option{max_glyph_a}
9553 and the @option{fontsize} value are included in the @option{y} offset.
9555 drawtext=fontfile=FreeSans.ttf:text=DOG:fontsize=24:x=10:y=20+24-max_glyph_a,
9556 drawtext=fontfile=FreeSans.ttf:text=cow:fontsize=24:x=80:y=20+24-max_glyph_a
9561 For more information about libfreetype, check:
9562 @url{http://www.freetype.org/}.
9564 For more information about fontconfig, check:
9565 @url{http://freedesktop.org/software/fontconfig/fontconfig-user.html}.
9567 For more information about libfribidi, check:
9568 @url{http://fribidi.org/}.
9572 Detect and draw edges. The filter uses the Canny Edge Detection algorithm.
9574 The filter accepts the following options:
9579 Set low and high threshold values used by the Canny thresholding
9582 The high threshold selects the "strong" edge pixels, which are then
9583 connected through 8-connectivity with the "weak" edge pixels selected
9584 by the low threshold.
9586 @var{low} and @var{high} threshold values must be chosen in the range
9587 [0,1], and @var{low} should be lesser or equal to @var{high}.
9589 Default value for @var{low} is @code{20/255}, and default value for @var{high}
9593 Define the drawing mode.
9597 Draw white/gray wires on black background.
9600 Mix the colors to create a paint/cartoon effect.
9603 Apply Canny edge detector on all selected planes.
9605 Default value is @var{wires}.
9608 Select planes for filtering. By default all available planes are filtered.
9611 @subsection Examples
9615 Standard edge detection with custom values for the hysteresis thresholding:
9617 edgedetect=low=0.1:high=0.4
9621 Painting effect without thresholding:
9623 edgedetect=mode=colormix:high=0
9629 Apply a posterize effect using the ELBG (Enhanced LBG) algorithm.
9631 For each input image, the filter will compute the optimal mapping from
9632 the input to the output given the codebook length, that is the number
9633 of distinct output colors.
9635 This filter accepts the following options.
9638 @item codebook_length, l
9639 Set codebook length. The value must be a positive integer, and
9640 represents the number of distinct output colors. Default value is 256.
9643 Set the maximum number of iterations to apply for computing the optimal
9644 mapping. The higher the value the better the result and the higher the
9645 computation time. Default value is 1.
9648 Set a random seed, must be an integer included between 0 and
9649 UINT32_MAX. If not specified, or if explicitly set to -1, the filter
9650 will try to use a good random seed on a best effort basis.
9653 Set pal8 output pixel format. This option does not work with codebook
9654 length greater than 256.
9659 Measure graylevel entropy in histogram of color channels of video frames.
9661 It accepts the following parameters:
9665 Can be either @var{normal} or @var{diff}. Default is @var{normal}.
9667 @var{diff} mode measures entropy of histogram delta values, absolute differences
9668 between neighbour histogram values.
9672 Set brightness, contrast, saturation and approximate gamma adjustment.
9674 The filter accepts the following options:
9678 Set the contrast expression. The value must be a float value in range
9679 @code{-1000.0} to @code{1000.0}. The default value is "1".
9682 Set the brightness expression. The value must be a float value in
9683 range @code{-1.0} to @code{1.0}. The default value is "0".
9686 Set the saturation expression. The value must be a float in
9687 range @code{0.0} to @code{3.0}. The default value is "1".
9690 Set the gamma expression. The value must be a float in range
9691 @code{0.1} to @code{10.0}. The default value is "1".
9694 Set the gamma expression for red. The value must be a float in
9695 range @code{0.1} to @code{10.0}. The default value is "1".
9698 Set the gamma expression for green. The value must be a float in range
9699 @code{0.1} to @code{10.0}. The default value is "1".
9702 Set the gamma expression for blue. The value must be a float in range
9703 @code{0.1} to @code{10.0}. The default value is "1".
9706 Set the gamma weight expression. It can be used to reduce the effect
9707 of a high gamma value on bright image areas, e.g. keep them from
9708 getting overamplified and just plain white. The value must be a float
9709 in range @code{0.0} to @code{1.0}. A value of @code{0.0} turns the
9710 gamma correction all the way down while @code{1.0} leaves it at its
9711 full strength. Default is "1".
9714 Set when the expressions for brightness, contrast, saturation and
9715 gamma expressions are evaluated.
9717 It accepts the following values:
9720 only evaluate expressions once during the filter initialization or
9721 when a command is processed
9724 evaluate expressions for each incoming frame
9727 Default value is @samp{init}.
9730 The expressions accept the following parameters:
9733 frame count of the input frame starting from 0
9736 byte position of the corresponding packet in the input file, NAN if
9740 frame rate of the input video, NAN if the input frame rate is unknown
9743 timestamp expressed in seconds, NAN if the input timestamp is unknown
9746 @subsection Commands
9747 The filter supports the following commands:
9751 Set the contrast expression.
9754 Set the brightness expression.
9757 Set the saturation expression.
9760 Set the gamma expression.
9763 Set the gamma_r expression.
9766 Set gamma_g expression.
9769 Set gamma_b expression.
9772 Set gamma_weight expression.
9774 The command accepts the same syntax of the corresponding option.
9776 If the specified expression is not valid, it is kept at its current
9783 Apply erosion effect to the video.
9785 This filter replaces the pixel by the local(3x3) minimum.
9787 It accepts the following options:
9794 Limit the maximum change for each plane, default is 65535.
9795 If 0, plane will remain unchanged.
9798 Flag which specifies the pixel to refer to. Default is 255 i.e. all eight
9801 Flags to local 3x3 coordinates maps like this:
9808 @section extractplanes
9810 Extract color channel components from input video stream into
9811 separate grayscale video streams.
9813 The filter accepts the following option:
9817 Set plane(s) to extract.
9819 Available values for planes are:
9830 Choosing planes not available in the input will result in an error.
9831 That means you cannot select @code{r}, @code{g}, @code{b} planes
9832 with @code{y}, @code{u}, @code{v} planes at same time.
9835 @subsection Examples
9839 Extract luma, u and v color channel component from input video frame
9840 into 3 grayscale outputs:
9842 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
9848 Apply a fade-in/out effect to the input video.
9850 It accepts the following parameters:
9854 The effect type can be either "in" for a fade-in, or "out" for a fade-out
9856 Default is @code{in}.
9858 @item start_frame, s
9859 Specify the number of the frame to start applying the fade
9860 effect at. Default is 0.
9863 The number of frames that the fade effect lasts. At the end of the
9864 fade-in effect, the output video will have the same intensity as the input video.
9865 At the end of the fade-out transition, the output video will be filled with the
9866 selected @option{color}.
9870 If set to 1, fade only alpha channel, if one exists on the input.
9873 @item start_time, st
9874 Specify the timestamp (in seconds) of the frame to start to apply the fade
9875 effect. If both start_frame and start_time are specified, the fade will start at
9876 whichever comes last. Default is 0.
9879 The number of seconds for which the fade effect has to last. 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}.
9883 If both duration and nb_frames are specified, duration is used. Default is 0
9884 (nb_frames is used by default).
9887 Specify the color of the fade. Default is "black".
9890 @subsection Examples
9894 Fade in the first 30 frames of video:
9899 The command above is equivalent to:
9905 Fade out the last 45 frames of a 200-frame video:
9908 fade=type=out:start_frame=155:nb_frames=45
9912 Fade in the first 25 frames and fade out the last 25 frames of a 1000-frame video:
9914 fade=in:0:25, fade=out:975:25
9918 Make the first 5 frames yellow, then fade in from frame 5-24:
9920 fade=in:5:20:color=yellow
9924 Fade in alpha over first 25 frames of video:
9926 fade=in:0:25:alpha=1
9930 Make the first 5.5 seconds black, then fade in for 0.5 seconds:
9932 fade=t=in:st=5.5:d=0.5
9938 Denoise frames using 3D FFT (frequency domain filtering).
9940 The filter accepts the following options:
9944 Set the noise sigma constant. This sets denoising strength.
9945 Default value is 1. Allowed range is from 0 to 30.
9946 Using very high sigma with low overlap may give blocking artifacts.
9949 Set amount of denoising. By default all detected noise is reduced.
9950 Default value is 1. Allowed range is from 0 to 1.
9953 Set size of block, Default is 4, can be 3, 4, 5 or 6.
9954 Actual size of block in pixels is 2 to power of @var{block}, so by default
9955 block size in pixels is 2^4 which is 16.
9958 Set block overlap. Default is 0.5. Allowed range is from 0.2 to 0.8.
9961 Set number of previous frames to use for denoising. By default is set to 0.
9964 Set number of next frames to to use for denoising. By default is set to 0.
9967 Set planes which will be filtered, by default are all available filtered
9972 Apply arbitrary expressions to samples in frequency domain
9976 Adjust the dc value (gain) of the luma plane of the image. The filter
9977 accepts an integer value in range @code{0} to @code{1000}. The default
9978 value is set to @code{0}.
9981 Adjust the dc value (gain) of the 1st chroma plane of the image. The
9982 filter accepts an integer value in range @code{0} to @code{1000}. The
9983 default value is set to @code{0}.
9986 Adjust the dc value (gain) of the 2nd chroma plane of the image. The
9987 filter accepts an integer value in range @code{0} to @code{1000}. The
9988 default value is set to @code{0}.
9991 Set the frequency domain weight expression for the luma plane.
9994 Set the frequency domain weight expression for the 1st chroma plane.
9997 Set the frequency domain weight expression for the 2nd chroma plane.
10000 Set when the expressions are evaluated.
10002 It accepts the following values:
10005 Only evaluate expressions once during the filter initialization.
10008 Evaluate expressions for each incoming frame.
10011 Default value is @samp{init}.
10013 The filter accepts the following variables:
10016 The coordinates of the current sample.
10020 The width and height of the image.
10023 The number of input frame, starting from 0.
10026 @subsection Examples
10032 fftfilt=dc_Y=128:weight_Y='squish(1-(Y+X)/100)'
10038 fftfilt=dc_Y=0:weight_Y='squish((Y+X)/100-1)'
10044 fftfilt=dc_Y=0:weight_Y='1+squish(1-(Y+X)/100)'
10050 fftfilt=dc_Y=0:weight_Y='exp(-4 * ((Y+X)/(W+H)))'
10057 Extract a single field from an interlaced image using stride
10058 arithmetic to avoid wasting CPU time. The output frames are marked as
10061 The filter accepts the following options:
10065 Specify whether to extract the top (if the value is @code{0} or
10066 @code{top}) or the bottom field (if the value is @code{1} or
10072 Create new frames by copying the top and bottom fields from surrounding frames
10073 supplied as numbers by the hint file.
10077 Set file containing hints: absolute/relative frame numbers.
10079 There must be one line for each frame in a clip. Each line must contain two
10080 numbers separated by the comma, optionally followed by @code{-} or @code{+}.
10081 Numbers supplied on each line of file can not be out of [N-1,N+1] where N
10082 is current frame number for @code{absolute} mode or out of [-1, 1] range
10083 for @code{relative} mode. First number tells from which frame to pick up top
10084 field and second number tells from which frame to pick up bottom field.
10086 If optionally followed by @code{+} output frame will be marked as interlaced,
10087 else if followed by @code{-} output frame will be marked as progressive, else
10088 it will be marked same as input frame.
10089 If line starts with @code{#} or @code{;} that line is skipped.
10092 Can be item @code{absolute} or @code{relative}. Default is @code{absolute}.
10095 Example of first several lines of @code{hint} file for @code{relative} mode:
10097 0,0 - # first frame
10098 1,0 - # second frame, use third's frame top field and second's frame bottom field
10099 1,0 - # third frame, use fourth's frame top field and third's frame bottom field
10114 @section fieldmatch
10116 Field matching filter for inverse telecine. It is meant to reconstruct the
10117 progressive frames from a telecined stream. The filter does not drop duplicated
10118 frames, so to achieve a complete inverse telecine @code{fieldmatch} needs to be
10119 followed by a decimation filter such as @ref{decimate} in the filtergraph.
10121 The separation of the field matching and the decimation is notably motivated by
10122 the possibility of inserting a de-interlacing filter fallback between the two.
10123 If the source has mixed telecined and real interlaced content,
10124 @code{fieldmatch} will not be able to match fields for the interlaced parts.
10125 But these remaining combed frames will be marked as interlaced, and thus can be
10126 de-interlaced by a later filter such as @ref{yadif} before decimation.
10128 In addition to the various configuration options, @code{fieldmatch} can take an
10129 optional second stream, activated through the @option{ppsrc} option. If
10130 enabled, the frames reconstruction will be based on the fields and frames from
10131 this second stream. This allows the first input to be pre-processed in order to
10132 help the various algorithms of the filter, while keeping the output lossless
10133 (assuming the fields are matched properly). Typically, a field-aware denoiser,
10134 or brightness/contrast adjustments can help.
10136 Note that this filter uses the same algorithms as TIVTC/TFM (AviSynth project)
10137 and VIVTC/VFM (VapourSynth project). The later is a light clone of TFM from
10138 which @code{fieldmatch} is based on. While the semantic and usage are very
10139 close, some behaviour and options names can differ.
10141 The @ref{decimate} filter currently only works for constant frame rate input.
10142 If your input has mixed telecined (30fps) and progressive content with a lower
10143 framerate like 24fps use the following filterchain to produce the necessary cfr
10144 stream: @code{dejudder,fps=30000/1001,fieldmatch,decimate}.
10146 The filter accepts the following options:
10150 Specify the assumed field order of the input stream. Available values are:
10154 Auto detect parity (use FFmpeg's internal parity value).
10156 Assume bottom field first.
10158 Assume top field first.
10161 Note that it is sometimes recommended not to trust the parity announced by the
10164 Default value is @var{auto}.
10167 Set the matching mode or strategy to use. @option{pc} mode is the safest in the
10168 sense that it won't risk creating jerkiness due to duplicate frames when
10169 possible, but if there are bad edits or blended fields it will end up
10170 outputting combed frames when a good match might actually exist. On the other
10171 hand, @option{pcn_ub} mode is the most risky in terms of creating jerkiness,
10172 but will almost always find a good frame if there is one. The other values are
10173 all somewhere in between @option{pc} and @option{pcn_ub} in terms of risking
10174 jerkiness and creating duplicate frames versus finding good matches in sections
10175 with bad edits, orphaned fields, blended fields, etc.
10177 More details about p/c/n/u/b are available in @ref{p/c/n/u/b meaning} section.
10179 Available values are:
10183 2-way matching (p/c)
10185 2-way matching, and trying 3rd match if still combed (p/c + n)
10187 2-way matching, and trying 3rd match (same order) if still combed (p/c + u)
10189 2-way matching, trying 3rd match if still combed, and trying 4th/5th matches if
10190 still combed (p/c + n + u/b)
10192 3-way matching (p/c/n)
10194 3-way matching, and trying 4th/5th matches if all 3 of the original matches are
10195 detected as combed (p/c/n + u/b)
10198 The parenthesis at the end indicate the matches that would be used for that
10199 mode assuming @option{order}=@var{tff} (and @option{field} on @var{auto} or
10202 In terms of speed @option{pc} mode is by far the fastest and @option{pcn_ub} is
10205 Default value is @var{pc_n}.
10208 Mark the main input stream as a pre-processed input, and enable the secondary
10209 input stream as the clean source to pick the fields from. See the filter
10210 introduction for more details. It is similar to the @option{clip2} feature from
10213 Default value is @code{0} (disabled).
10216 Set the field to match from. It is recommended to set this to the same value as
10217 @option{order} unless you experience matching failures with that setting. In
10218 certain circumstances changing the field that is used to match from can have a
10219 large impact on matching performance. Available values are:
10223 Automatic (same value as @option{order}).
10225 Match from the bottom field.
10227 Match from the top field.
10230 Default value is @var{auto}.
10233 Set whether or not chroma is included during the match comparisons. In most
10234 cases it is recommended to leave this enabled. You should set this to @code{0}
10235 only if your clip has bad chroma problems such as heavy rainbowing or other
10236 artifacts. Setting this to @code{0} could also be used to speed things up at
10237 the cost of some accuracy.
10239 Default value is @code{1}.
10243 These define an exclusion band which excludes the lines between @option{y0} and
10244 @option{y1} from being included in the field matching decision. An exclusion
10245 band can be used to ignore subtitles, a logo, or other things that may
10246 interfere with the matching. @option{y0} sets the starting scan line and
10247 @option{y1} sets the ending line; all lines in between @option{y0} and
10248 @option{y1} (including @option{y0} and @option{y1}) will be ignored. Setting
10249 @option{y0} and @option{y1} to the same value will disable the feature.
10250 @option{y0} and @option{y1} defaults to @code{0}.
10253 Set the scene change detection threshold as a percentage of maximum change on
10254 the luma plane. Good values are in the @code{[8.0, 14.0]} range. Scene change
10255 detection is only relevant in case @option{combmatch}=@var{sc}. The range for
10256 @option{scthresh} is @code{[0.0, 100.0]}.
10258 Default value is @code{12.0}.
10261 When @option{combatch} is not @var{none}, @code{fieldmatch} will take into
10262 account the combed scores of matches when deciding what match to use as the
10263 final match. Available values are:
10267 No final matching based on combed scores.
10269 Combed scores are only used when a scene change is detected.
10271 Use combed scores all the time.
10274 Default is @var{sc}.
10277 Force @code{fieldmatch} to calculate the combed metrics for certain matches and
10278 print them. This setting is known as @option{micout} in TFM/VFM vocabulary.
10279 Available values are:
10283 No forced calculation.
10285 Force p/c/n calculations.
10287 Force p/c/n/u/b calculations.
10290 Default value is @var{none}.
10293 This is the area combing threshold used for combed frame detection. This
10294 essentially controls how "strong" or "visible" combing must be to be detected.
10295 Larger values mean combing must be more visible and smaller values mean combing
10296 can be less visible or strong and still be detected. Valid settings are from
10297 @code{-1} (every pixel will be detected as combed) to @code{255} (no pixel will
10298 be detected as combed). This is basically a pixel difference value. A good
10299 range is @code{[8, 12]}.
10301 Default value is @code{9}.
10304 Sets whether or not chroma is considered in the combed frame decision. Only
10305 disable this if your source has chroma problems (rainbowing, etc.) that are
10306 causing problems for the combed frame detection with chroma enabled. Actually,
10307 using @option{chroma}=@var{0} is usually more reliable, except for the case
10308 where there is chroma only combing in the source.
10310 Default value is @code{0}.
10314 Respectively set the x-axis and y-axis size of the window used during combed
10315 frame detection. This has to do with the size of the area in which
10316 @option{combpel} pixels are required to be detected as combed for a frame to be
10317 declared combed. See the @option{combpel} parameter description for more info.
10318 Possible values are any number that is a power of 2 starting at 4 and going up
10321 Default value is @code{16}.
10324 The number of combed pixels inside any of the @option{blocky} by
10325 @option{blockx} size blocks on the frame for the frame to be detected as
10326 combed. While @option{cthresh} controls how "visible" the combing must be, this
10327 setting controls "how much" combing there must be in any localized area (a
10328 window defined by the @option{blockx} and @option{blocky} settings) on the
10329 frame. Minimum value is @code{0} and maximum is @code{blocky x blockx} (at
10330 which point no frames will ever be detected as combed). This setting is known
10331 as @option{MI} in TFM/VFM vocabulary.
10333 Default value is @code{80}.
10336 @anchor{p/c/n/u/b meaning}
10337 @subsection p/c/n/u/b meaning
10339 @subsubsection p/c/n
10341 We assume the following telecined stream:
10344 Top fields: 1 2 2 3 4
10345 Bottom fields: 1 2 3 4 4
10348 The numbers correspond to the progressive frame the fields relate to. Here, the
10349 first two frames are progressive, the 3rd and 4th are combed, and so on.
10351 When @code{fieldmatch} is configured to run a matching from bottom
10352 (@option{field}=@var{bottom}) this is how this input stream get transformed:
10357 B 1 2 3 4 4 <-- matching reference
10366 As a result of the field matching, we can see that some frames get duplicated.
10367 To perform a complete inverse telecine, you need to rely on a decimation filter
10368 after this operation. See for instance the @ref{decimate} filter.
10370 The same operation now matching from top fields (@option{field}=@var{top})
10375 T 1 2 2 3 4 <-- matching reference
10385 In these examples, we can see what @var{p}, @var{c} and @var{n} mean;
10386 basically, they refer to the frame and field of the opposite parity:
10389 @item @var{p} matches the field of the opposite parity in the previous frame
10390 @item @var{c} matches the field of the opposite parity in the current frame
10391 @item @var{n} matches the field of the opposite parity in the next frame
10396 The @var{u} and @var{b} matching are a bit special in the sense that they match
10397 from the opposite parity flag. In the following examples, we assume that we are
10398 currently matching the 2nd frame (Top:2, bottom:2). According to the match, a
10399 'x' is placed above and below each matched fields.
10401 With bottom matching (@option{field}=@var{bottom}):
10406 Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2
10407 Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3
10415 With top matching (@option{field}=@var{top}):
10420 Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2
10421 Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3
10429 @subsection Examples
10431 Simple IVTC of a top field first telecined stream:
10433 fieldmatch=order=tff:combmatch=none, decimate
10436 Advanced IVTC, with fallback on @ref{yadif} for still combed frames:
10438 fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate
10441 @section fieldorder
10443 Transform the field order of the input video.
10445 It accepts the following parameters:
10450 The output field order. Valid values are @var{tff} for top field first or @var{bff}
10451 for bottom field first.
10454 The default value is @samp{tff}.
10456 The transformation is done by shifting the picture content up or down
10457 by one line, and filling the remaining line with appropriate picture content.
10458 This method is consistent with most broadcast field order converters.
10460 If the input video is not flagged as being interlaced, or it is already
10461 flagged as being of the required output field order, then this filter does
10462 not alter the incoming video.
10464 It is very useful when converting to or from PAL DV material,
10465 which is bottom field first.
10469 ffmpeg -i in.vob -vf "fieldorder=bff" out.dv
10472 @section fifo, afifo
10474 Buffer input images and send them when they are requested.
10476 It is mainly useful when auto-inserted by the libavfilter
10479 It does not take parameters.
10481 @section fillborders
10483 Fill borders of the input video, without changing video stream dimensions.
10484 Sometimes video can have garbage at the four edges and you may not want to
10485 crop video input to keep size multiple of some number.
10487 This filter accepts the following options:
10491 Number of pixels to fill from left border.
10494 Number of pixels to fill from right border.
10497 Number of pixels to fill from top border.
10500 Number of pixels to fill from bottom border.
10505 It accepts the following values:
10508 fill pixels using outermost pixels
10511 fill pixels using mirroring
10514 fill pixels with constant value
10517 Default is @var{smear}.
10520 Set color for pixels in fixed mode. Default is @var{black}.
10525 Find a rectangular object
10527 It accepts the following options:
10531 Filepath of the object image, needs to be in gray8.
10534 Detection threshold, default is 0.5.
10537 Number of mipmaps, default is 3.
10539 @item xmin, ymin, xmax, ymax
10540 Specifies the rectangle in which to search.
10543 @subsection Examples
10547 Cover a rectangular object by the supplied image of a given video using @command{ffmpeg}:
10549 ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
10555 Flood area with values of same pixel components with another values.
10557 It accepts the following options:
10560 Set pixel x coordinate.
10563 Set pixel y coordinate.
10566 Set source #0 component value.
10569 Set source #1 component value.
10572 Set source #2 component value.
10575 Set source #3 component value.
10578 Set destination #0 component value.
10581 Set destination #1 component value.
10584 Set destination #2 component value.
10587 Set destination #3 component value.
10593 Convert the input video to one of the specified pixel formats.
10594 Libavfilter will try to pick one that is suitable as input to
10597 It accepts the following parameters:
10601 A '|'-separated list of pixel format names, such as
10602 "pix_fmts=yuv420p|monow|rgb24".
10606 @subsection Examples
10610 Convert the input video to the @var{yuv420p} format
10612 format=pix_fmts=yuv420p
10615 Convert the input video to any of the formats in the list
10617 format=pix_fmts=yuv420p|yuv444p|yuv410p
10624 Convert the video to specified constant frame rate by duplicating or dropping
10625 frames as necessary.
10627 It accepts the following parameters:
10631 The desired output frame rate. The default is @code{25}.
10634 Assume the first PTS should be the given value, in seconds. This allows for
10635 padding/trimming at the start of stream. By default, no assumption is made
10636 about the first frame's expected PTS, so no padding or trimming is done.
10637 For example, this could be set to 0 to pad the beginning with duplicates of
10638 the first frame if a video stream starts after the audio stream or to trim any
10639 frames with a negative PTS.
10642 Timestamp (PTS) rounding method.
10644 Possible values are:
10651 round towards -infinity
10653 round towards +infinity
10657 The default is @code{near}.
10660 Action performed when reading the last frame.
10662 Possible values are:
10665 Use same timestamp rounding method as used for other frames.
10667 Pass through last frame if input duration has not been reached yet.
10669 The default is @code{round}.
10673 Alternatively, the options can be specified as a flat string:
10674 @var{fps}[:@var{start_time}[:@var{round}]].
10676 See also the @ref{setpts} filter.
10678 @subsection Examples
10682 A typical usage in order to set the fps to 25:
10688 Sets the fps to 24, using abbreviation and rounding method to round to nearest:
10690 fps=fps=film:round=near
10696 Pack two different video streams into a stereoscopic video, setting proper
10697 metadata on supported codecs. The two views should have the same size and
10698 framerate and processing will stop when the shorter video ends. Please note
10699 that you may conveniently adjust view properties with the @ref{scale} and
10702 It accepts the following parameters:
10706 The desired packing format. Supported values are:
10711 The views are next to each other (default).
10714 The views are on top of each other.
10717 The views are packed by line.
10720 The views are packed by column.
10723 The views are temporally interleaved.
10732 # Convert left and right views into a frame-sequential video
10733 ffmpeg -i LEFT -i RIGHT -filter_complex framepack=frameseq OUTPUT
10735 # Convert views into a side-by-side video with the same output resolution as the input
10736 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
10741 Change the frame rate by interpolating new video output frames from the source
10744 This filter is not designed to function correctly with interlaced media. If
10745 you wish to change the frame rate of interlaced media then you are required
10746 to deinterlace before this filter and re-interlace after this filter.
10748 A description of the accepted options follows.
10752 Specify the output frames per second. This option can also be specified
10753 as a value alone. The default is @code{50}.
10756 Specify the start of a range where the output frame will be created as a
10757 linear interpolation of two frames. The range is [@code{0}-@code{255}],
10758 the default is @code{15}.
10761 Specify the end of a range where the output frame will be created as a
10762 linear interpolation of two frames. The range is [@code{0}-@code{255}],
10763 the default is @code{240}.
10766 Specify the level at which a scene change is detected as a value between
10767 0 and 100 to indicate a new scene; a low value reflects a low
10768 probability for the current frame to introduce a new scene, while a higher
10769 value means the current frame is more likely to be one.
10770 The default is @code{8.2}.
10773 Specify flags influencing the filter process.
10775 Available value for @var{flags} is:
10778 @item scene_change_detect, scd
10779 Enable scene change detection using the value of the option @var{scene}.
10780 This flag is enabled by default.
10786 Select one frame every N-th frame.
10788 This filter accepts the following option:
10791 Select frame after every @code{step} frames.
10792 Allowed values are positive integers higher than 0. Default value is @code{1}.
10795 @section freezedetect
10797 Detect frozen video.
10799 This filter logs a message and sets frame metadata when it detects that the
10800 input video has no significant change in content during a specified duration.
10801 Video freeze detection calculates the mean average absolute difference of all
10802 the components of video frames and compares it to a noise floor.
10804 The printed times and duration are expressed in seconds. The
10805 @code{lavfi.freezedetect.freeze_start} metadata key is set on the first frame
10806 whose timestamp equals or exceeds the detection duration and it contains the
10807 timestamp of the first frame of the freeze. The
10808 @code{lavfi.freezedetect.freeze_duration} and
10809 @code{lavfi.freezedetect.freeze_end} metadata keys are set on the first frame
10812 The filter accepts the following options:
10816 Set noise tolerance. Can be specified in dB (in case "dB" is appended to the
10817 specified value) or as a difference ratio between 0 and 1. Default is -60dB, or
10821 Set freeze duration until notification (default is 2 seconds).
10827 Apply a frei0r effect to the input video.
10829 To enable the compilation of this filter, you need to install the frei0r
10830 header and configure FFmpeg with @code{--enable-frei0r}.
10832 It accepts the following parameters:
10837 The name of the frei0r effect to load. If the environment variable
10838 @env{FREI0R_PATH} is defined, the frei0r effect is searched for in each of the
10839 directories specified by the colon-separated list in @env{FREI0R_PATH}.
10840 Otherwise, the standard frei0r paths are searched, in this order:
10841 @file{HOME/.frei0r-1/lib/}, @file{/usr/local/lib/frei0r-1/},
10842 @file{/usr/lib/frei0r-1/}.
10844 @item filter_params
10845 A '|'-separated list of parameters to pass to the frei0r effect.
10849 A frei0r effect parameter can be a boolean (its value is either
10850 "y" or "n"), a double, a color (specified as
10851 @var{R}/@var{G}/@var{B}, where @var{R}, @var{G}, and @var{B} are floating point
10852 numbers between 0.0 and 1.0, inclusive) or a color description as specified in the
10853 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils},
10854 a position (specified as @var{X}/@var{Y}, where
10855 @var{X} and @var{Y} are floating point numbers) and/or a string.
10857 The number and types of parameters depend on the loaded effect. If an
10858 effect parameter is not specified, the default value is set.
10860 @subsection Examples
10864 Apply the distort0r effect, setting the first two double parameters:
10866 frei0r=filter_name=distort0r:filter_params=0.5|0.01
10870 Apply the colordistance effect, taking a color as the first parameter:
10872 frei0r=colordistance:0.2/0.3/0.4
10873 frei0r=colordistance:violet
10874 frei0r=colordistance:0x112233
10878 Apply the perspective effect, specifying the top left and top right image
10881 frei0r=perspective:0.2/0.2|0.8/0.2
10885 For more information, see
10886 @url{http://frei0r.dyne.org}
10890 Apply fast and simple postprocessing. It is a faster version of @ref{spp}.
10892 It splits (I)DCT into horizontal/vertical passes. Unlike the simple post-
10893 processing filter, one of them is performed once per block, not per pixel.
10894 This allows for much higher speed.
10896 The filter accepts the following options:
10900 Set quality. This option defines the number of levels for averaging. It accepts
10901 an integer in the range 4-5. Default value is @code{4}.
10904 Force a constant quantization parameter. It accepts an integer in range 0-63.
10905 If not set, the filter will use the QP from the video stream (if available).
10908 Set filter strength. It accepts an integer in range -15 to 32. Lower values mean
10909 more details but also more artifacts, while higher values make the image smoother
10910 but also blurrier. Default value is @code{0} − PSNR optimal.
10912 @item use_bframe_qp
10913 Enable the use of the QP from the B-Frames if set to @code{1}. Using this
10914 option may cause flicker since the B-Frames have often larger QP. Default is
10915 @code{0} (not enabled).
10921 Apply Gaussian blur filter.
10923 The filter accepts the following options:
10927 Set horizontal sigma, standard deviation of Gaussian blur. Default is @code{0.5}.
10930 Set number of steps for Gaussian approximation. Default is @code{1}.
10933 Set which planes to filter. By default all planes are filtered.
10936 Set vertical sigma, if negative it will be same as @code{sigma}.
10937 Default is @code{-1}.
10940 @subsection Commands
10941 This filter supports same commands as options.
10942 The command accepts the same syntax of the corresponding option.
10944 If the specified expression is not valid, it is kept at its current
10949 Apply generic equation to each pixel.
10951 The filter accepts the following options:
10954 @item lum_expr, lum
10955 Set the luminance expression.
10957 Set the chrominance blue expression.
10959 Set the chrominance red expression.
10960 @item alpha_expr, a
10961 Set the alpha expression.
10963 Set the red expression.
10964 @item green_expr, g
10965 Set the green expression.
10967 Set the blue expression.
10970 The colorspace is selected according to the specified options. If one
10971 of the @option{lum_expr}, @option{cb_expr}, or @option{cr_expr}
10972 options is specified, the filter will automatically select a YCbCr
10973 colorspace. If one of the @option{red_expr}, @option{green_expr}, or
10974 @option{blue_expr} options is specified, it will select an RGB
10977 If one of the chrominance expression is not defined, it falls back on the other
10978 one. If no alpha expression is specified it will evaluate to opaque value.
10979 If none of chrominance expressions are specified, they will evaluate
10980 to the luminance expression.
10982 The expressions can use the following variables and functions:
10986 The sequential number of the filtered frame, starting from @code{0}.
10990 The coordinates of the current sample.
10994 The width and height of the image.
10998 Width and height scale depending on the currently filtered plane. It is the
10999 ratio between the corresponding luma plane number of pixels and the current
11000 plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and
11001 @code{0.5,0.5} for chroma planes.
11004 Time of the current frame, expressed in seconds.
11007 Return the value of the pixel at location (@var{x},@var{y}) of the current
11011 Return the value of the pixel at location (@var{x},@var{y}) of the luminance
11015 Return the value of the pixel at location (@var{x},@var{y}) of the
11016 blue-difference chroma plane. Return 0 if there is no such plane.
11019 Return the value of the pixel at location (@var{x},@var{y}) of the
11020 red-difference chroma plane. Return 0 if there is no such plane.
11025 Return the value of the pixel at location (@var{x},@var{y}) of the
11026 red/green/blue component. Return 0 if there is no such component.
11029 Return the value of the pixel at location (@var{x},@var{y}) of the alpha
11030 plane. Return 0 if there is no such plane.
11032 @item interpolation
11033 Set one of interpolation methods:
11038 Default is bilinear.
11041 For functions, if @var{x} and @var{y} are outside the area, the value will be
11042 automatically clipped to the closer edge.
11044 @subsection Examples
11048 Flip the image horizontally:
11054 Generate a bidimensional sine wave, with angle @code{PI/3} and a
11055 wavelength of 100 pixels:
11057 geq=128 + 100*sin(2*(PI/100)*(cos(PI/3)*(X-50*T) + sin(PI/3)*Y)):128:128
11061 Generate a fancy enigmatic moving light:
11063 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
11067 Generate a quick emboss effect:
11069 format=gray,geq=lum_expr='(p(X,Y)+(256-p(X-4,Y-4)))/2'
11073 Modify RGB components depending on pixel position:
11075 geq=r='X/W*r(X,Y)':g='(1-X/W)*g(X,Y)':b='(H-Y)/H*b(X,Y)'
11079 Create a radial gradient that is the same size as the input (also see
11080 the @ref{vignette} filter):
11082 geq=lum=255*gauss((X/W-0.5)*3)*gauss((Y/H-0.5)*3)/gauss(0)/gauss(0),format=gray
11088 Fix the banding artifacts that are sometimes introduced into nearly flat
11089 regions by truncation to 8-bit color depth.
11090 Interpolate the gradients that should go where the bands are, and
11093 It is designed for playback only. Do not use it prior to
11094 lossy compression, because compression tends to lose the dither and
11095 bring back the bands.
11097 It accepts the following parameters:
11102 The maximum amount by which the filter will change any one pixel. This is also
11103 the threshold for detecting nearly flat regions. Acceptable values range from
11104 .51 to 64; the default value is 1.2. Out-of-range values will be clipped to the
11108 The neighborhood to fit the gradient to. A larger radius makes for smoother
11109 gradients, but also prevents the filter from modifying the pixels near detailed
11110 regions. Acceptable values are 8-32; the default value is 16. Out-of-range
11111 values will be clipped to the valid range.
11115 Alternatively, the options can be specified as a flat string:
11116 @var{strength}[:@var{radius}]
11118 @subsection Examples
11122 Apply the filter with a @code{3.5} strength and radius of @code{8}:
11128 Specify radius, omitting the strength (which will fall-back to the default
11136 @section graphmonitor, agraphmonitor
11137 Show various filtergraph stats.
11139 With this filter one can debug complete filtergraph.
11140 Especially issues with links filling with queued frames.
11142 The filter accepts the following options:
11146 Set video output size. Default is @var{hd720}.
11149 Set video opacity. Default is @var{0.9}. Allowed range is from @var{0} to @var{1}.
11152 Set output mode, can be @var{fulll} or @var{compact}.
11153 In @var{compact} mode only filters with some queued frames have displayed stats.
11156 Set flags which enable which stats are shown in video.
11158 Available values for flags are:
11161 Display number of queued frames in each link.
11163 @item frame_count_in
11164 Display number of frames taken from filter.
11166 @item frame_count_out
11167 Display number of frames given out from filter.
11170 Display current filtered frame pts.
11173 Display current filtered frame time.
11176 Display time base for filter link.
11179 Display used format for filter link.
11182 Display video size or number of audio channels in case of audio used by filter link.
11185 Display video frame rate or sample rate in case of audio used by filter link.
11189 Set upper limit for video rate of output stream, Default value is @var{25}.
11190 This guarantee that output video frame rate will not be higher than this value.
11194 A color constancy variation filter which estimates scene illumination via grey edge algorithm
11195 and corrects the scene colors accordingly.
11197 See: @url{https://staff.science.uva.nl/th.gevers/pub/GeversTIP07.pdf}
11199 The filter accepts the following options:
11203 The order of differentiation to be applied on the scene. Must be chosen in the range
11204 [0,2] and default value is 1.
11207 The Minkowski parameter to be used for calculating the Minkowski distance. Must
11208 be chosen in the range [0,20] and default value is 1. Set to 0 for getting
11209 max value instead of calculating Minkowski distance.
11212 The standard deviation of Gaussian blur to be applied on the scene. Must be
11213 chosen in the range [0,1024.0] and default value = 1. floor( @var{sigma} * break_off_sigma(3) )
11214 can't be equal to 0 if @var{difford} is greater than 0.
11217 @subsection Examples
11223 greyedge=difford=1:minknorm=5:sigma=2
11229 greyedge=difford=1:minknorm=0:sigma=2
11237 Apply a Hald CLUT to a video stream.
11239 First input is the video stream to process, and second one is the Hald CLUT.
11240 The Hald CLUT input can be a simple picture or a complete video stream.
11242 The filter accepts the following options:
11246 Force termination when the shortest input terminates. Default is @code{0}.
11248 Continue applying the last CLUT after the end of the stream. A value of
11249 @code{0} disable the filter after the last frame of the CLUT is reached.
11250 Default is @code{1}.
11253 @code{haldclut} also has the same interpolation options as @ref{lut3d} (both
11254 filters share the same internals).
11256 This filter also supports the @ref{framesync} options.
11258 More information about the Hald CLUT can be found on Eskil Steenberg's website
11259 (Hald CLUT author) at @url{http://www.quelsolaar.com/technology/clut.html}.
11261 @subsection Workflow examples
11263 @subsubsection Hald CLUT video stream
11265 Generate an identity Hald CLUT stream altered with various effects:
11267 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
11270 Note: make sure you use a lossless codec.
11272 Then use it with @code{haldclut} to apply it on some random stream:
11274 ffmpeg -f lavfi -i mandelbrot -i clut.nut -filter_complex '[0][1] haldclut' -t 20 mandelclut.mkv
11277 The Hald CLUT will be applied to the 10 first seconds (duration of
11278 @file{clut.nut}), then the latest picture of that CLUT stream will be applied
11279 to the remaining frames of the @code{mandelbrot} stream.
11281 @subsubsection Hald CLUT with preview
11283 A Hald CLUT is supposed to be a squared image of @code{Level*Level*Level} by
11284 @code{Level*Level*Level} pixels. For a given Hald CLUT, FFmpeg will select the
11285 biggest possible square starting at the top left of the picture. The remaining
11286 padding pixels (bottom or right) will be ignored. This area can be used to add
11287 a preview of the Hald CLUT.
11289 Typically, the following generated Hald CLUT will be supported by the
11290 @code{haldclut} filter:
11293 ffmpeg -f lavfi -i @ref{haldclutsrc}=8 -vf "
11294 pad=iw+320 [padded_clut];
11295 smptebars=s=320x256, split [a][b];
11296 [padded_clut][a] overlay=W-320:h, curves=color_negative [main];
11297 [main][b] overlay=W-320" -frames:v 1 clut.png
11300 It contains the original and a preview of the effect of the CLUT: SMPTE color
11301 bars are displayed on the right-top, and below the same color bars processed by
11304 Then, the effect of this Hald CLUT can be visualized with:
11306 ffplay input.mkv -vf "movie=clut.png, [in] haldclut"
11311 Flip the input video horizontally.
11313 For example, to horizontally flip the input video with @command{ffmpeg}:
11315 ffmpeg -i in.avi -vf "hflip" out.avi
11319 This filter applies a global color histogram equalization on a
11322 It can be used to correct video that has a compressed range of pixel
11323 intensities. The filter redistributes the pixel intensities to
11324 equalize their distribution across the intensity range. It may be
11325 viewed as an "automatically adjusting contrast filter". This filter is
11326 useful only for correcting degraded or poorly captured source
11329 The filter accepts the following options:
11333 Determine the amount of equalization to be applied. As the strength
11334 is reduced, the distribution of pixel intensities more-and-more
11335 approaches that of the input frame. The value must be a float number
11336 in the range [0,1] and defaults to 0.200.
11339 Set the maximum intensity that can generated and scale the output
11340 values appropriately. The strength should be set as desired and then
11341 the intensity can be limited if needed to avoid washing-out. The value
11342 must be a float number in the range [0,1] and defaults to 0.210.
11345 Set the antibanding level. If enabled the filter will randomly vary
11346 the luminance of output pixels by a small amount to avoid banding of
11347 the histogram. Possible values are @code{none}, @code{weak} or
11348 @code{strong}. It defaults to @code{none}.
11353 Compute and draw a color distribution histogram for the input video.
11355 The computed histogram is a representation of the color component
11356 distribution in an image.
11358 Standard histogram displays the color components distribution in an image.
11359 Displays color graph for each color component. Shows distribution of
11360 the Y, U, V, A or R, G, B components, depending on input format, in the
11361 current frame. Below each graph a color component scale meter is shown.
11363 The filter accepts the following options:
11367 Set height of level. Default value is @code{200}.
11368 Allowed range is [50, 2048].
11371 Set height of color scale. Default value is @code{12}.
11372 Allowed range is [0, 40].
11376 It accepts the following values:
11379 Per color component graphs are placed below each other.
11382 Per color component graphs are placed side by side.
11385 Presents information identical to that in the @code{parade}, except
11386 that the graphs representing color components are superimposed directly
11389 Default is @code{stack}.
11392 Set mode. Can be either @code{linear}, or @code{logarithmic}.
11393 Default is @code{linear}.
11396 Set what color components to display.
11397 Default is @code{7}.
11400 Set foreground opacity. Default is @code{0.7}.
11403 Set background opacity. Default is @code{0.5}.
11406 @subsection Examples
11411 Calculate and draw histogram:
11413 ffplay -i input -vf histogram
11421 This is a high precision/quality 3d denoise filter. It aims to reduce
11422 image noise, producing smooth images and making still images really
11423 still. It should enhance compressibility.
11425 It accepts the following optional parameters:
11429 A non-negative floating point number which specifies spatial luma strength.
11430 It defaults to 4.0.
11432 @item chroma_spatial
11433 A non-negative floating point number which specifies spatial chroma strength.
11434 It defaults to 3.0*@var{luma_spatial}/4.0.
11437 A floating point number which specifies luma temporal strength. It defaults to
11438 6.0*@var{luma_spatial}/4.0.
11441 A floating point number which specifies chroma temporal strength. It defaults to
11442 @var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}.
11445 @anchor{hwdownload}
11446 @section hwdownload
11448 Download hardware frames to system memory.
11450 The input must be in hardware frames, and the output a non-hardware format.
11451 Not all formats will be supported on the output - it may be necessary to insert
11452 an additional @option{format} filter immediately following in the graph to get
11453 the output in a supported format.
11457 Map hardware frames to system memory or to another device.
11459 This filter has several different modes of operation; which one is used depends
11460 on the input and output formats:
11463 Hardware frame input, normal frame output
11465 Map the input frames to system memory and pass them to the output. If the
11466 original hardware frame is later required (for example, after overlaying
11467 something else on part of it), the @option{hwmap} filter can be used again
11468 in the next mode to retrieve it.
11470 Normal frame input, hardware frame output
11472 If the input is actually a software-mapped hardware frame, then unmap it -
11473 that is, return the original hardware frame.
11475 Otherwise, a device must be provided. Create new hardware surfaces on that
11476 device for the output, then map them back to the software format at the input
11477 and give those frames to the preceding filter. This will then act like the
11478 @option{hwupload} filter, but may be able to avoid an additional copy when
11479 the input is already in a compatible format.
11481 Hardware frame input and output
11483 A device must be supplied for the output, either directly or with the
11484 @option{derive_device} option. The input and output devices must be of
11485 different types and compatible - the exact meaning of this is
11486 system-dependent, but typically it means that they must refer to the same
11487 underlying hardware context (for example, refer to the same graphics card).
11489 If the input frames were originally created on the output device, then unmap
11490 to retrieve the original frames.
11492 Otherwise, map the frames to the output device - create new hardware frames
11493 on the output corresponding to the frames on the input.
11496 The following additional parameters are accepted:
11500 Set the frame mapping mode. Some combination of:
11503 The mapped frame should be readable.
11505 The mapped frame should be writeable.
11507 The mapping will always overwrite the entire frame.
11509 This may improve performance in some cases, as the original contents of the
11510 frame need not be loaded.
11512 The mapping must not involve any copying.
11514 Indirect mappings to copies of frames are created in some cases where either
11515 direct mapping is not possible or it would have unexpected properties.
11516 Setting this flag ensures that the mapping is direct and will fail if that is
11519 Defaults to @var{read+write} if not specified.
11521 @item derive_device @var{type}
11522 Rather than using the device supplied at initialisation, instead derive a new
11523 device of type @var{type} from the device the input frames exist on.
11526 In a hardware to hardware mapping, map in reverse - create frames in the sink
11527 and map them back to the source. This may be necessary in some cases where
11528 a mapping in one direction is required but only the opposite direction is
11529 supported by the devices being used.
11531 This option is dangerous - it may break the preceding filter in undefined
11532 ways if there are any additional constraints on that filter's output.
11533 Do not use it without fully understanding the implications of its use.
11539 Upload system memory frames to hardware surfaces.
11541 The device to upload to must be supplied when the filter is initialised. If
11542 using ffmpeg, select the appropriate device with the @option{-filter_hw_device}
11545 @anchor{hwupload_cuda}
11546 @section hwupload_cuda
11548 Upload system memory frames to a CUDA device.
11550 It accepts the following optional parameters:
11554 The number of the CUDA device to use
11559 Apply a high-quality magnification filter designed for pixel art. This filter
11560 was originally created by Maxim Stepin.
11562 It accepts the following option:
11566 Set the scaling dimension: @code{2} for @code{hq2x}, @code{3} for
11567 @code{hq3x} and @code{4} for @code{hq4x}.
11568 Default is @code{3}.
11572 Stack input videos horizontally.
11574 All streams must be of same pixel format and of same height.
11576 Note that this filter is faster than using @ref{overlay} and @ref{pad} filter
11577 to create same output.
11579 The filter accepts the following option:
11583 Set number of input streams. Default is 2.
11586 If set to 1, force the output to terminate when the shortest input
11587 terminates. Default value is 0.
11592 Modify the hue and/or the saturation of the input.
11594 It accepts the following parameters:
11598 Specify the hue angle as a number of degrees. It accepts an expression,
11599 and defaults to "0".
11602 Specify the saturation in the [-10,10] range. It accepts an expression and
11606 Specify the hue angle as a number of radians. It accepts an
11607 expression, and defaults to "0".
11610 Specify the brightness in the [-10,10] range. It accepts an expression and
11614 @option{h} and @option{H} are mutually exclusive, and can't be
11615 specified at the same time.
11617 The @option{b}, @option{h}, @option{H} and @option{s} option values are
11618 expressions containing the following constants:
11622 frame count of the input frame starting from 0
11625 presentation timestamp of the input frame expressed in time base units
11628 frame rate of the input video, NAN if the input frame rate is unknown
11631 timestamp expressed in seconds, NAN if the input timestamp is unknown
11634 time base of the input video
11637 @subsection Examples
11641 Set the hue to 90 degrees and the saturation to 1.0:
11647 Same command but expressing the hue in radians:
11653 Rotate hue and make the saturation swing between 0
11654 and 2 over a period of 1 second:
11656 hue="H=2*PI*t: s=sin(2*PI*t)+1"
11660 Apply a 3 seconds saturation fade-in effect starting at 0:
11662 hue="s=min(t/3\,1)"
11665 The general fade-in expression can be written as:
11667 hue="s=min(0\, max((t-START)/DURATION\, 1))"
11671 Apply a 3 seconds saturation fade-out effect starting at 5 seconds:
11673 hue="s=max(0\, min(1\, (8-t)/3))"
11676 The general fade-out expression can be written as:
11678 hue="s=max(0\, min(1\, (START+DURATION-t)/DURATION))"
11683 @subsection Commands
11685 This filter supports the following commands:
11691 Modify the hue and/or the saturation and/or brightness of the input video.
11692 The command accepts the same syntax of the corresponding option.
11694 If the specified expression is not valid, it is kept at its current
11698 @section hysteresis
11700 Grow first stream into second stream by connecting components.
11701 This makes it possible to build more robust edge masks.
11703 This filter accepts the following options:
11707 Set which planes will be processed as bitmap, unprocessed planes will be
11708 copied from first stream.
11709 By default value 0xf, all planes will be processed.
11712 Set threshold which is used in filtering. If pixel component value is higher than
11713 this value filter algorithm for connecting components is activated.
11714 By default value is 0.
11719 Detect video interlacing type.
11721 This filter tries to detect if the input frames are interlaced, progressive,
11722 top or bottom field first. It will also try to detect fields that are
11723 repeated between adjacent frames (a sign of telecine).
11725 Single frame detection considers only immediately adjacent frames when classifying each frame.
11726 Multiple frame detection incorporates the classification history of previous frames.
11728 The filter will log these metadata values:
11731 @item single.current_frame
11732 Detected type of current frame using single-frame detection. One of:
11733 ``tff'' (top field first), ``bff'' (bottom field first),
11734 ``progressive'', or ``undetermined''
11737 Cumulative number of frames detected as top field first using single-frame detection.
11740 Cumulative number of frames detected as top field first using multiple-frame detection.
11743 Cumulative number of frames detected as bottom field first using single-frame detection.
11745 @item multiple.current_frame
11746 Detected type of current frame using multiple-frame detection. One of:
11747 ``tff'' (top field first), ``bff'' (bottom field first),
11748 ``progressive'', or ``undetermined''
11751 Cumulative number of frames detected as bottom field first using multiple-frame detection.
11753 @item single.progressive
11754 Cumulative number of frames detected as progressive using single-frame detection.
11756 @item multiple.progressive
11757 Cumulative number of frames detected as progressive using multiple-frame detection.
11759 @item single.undetermined
11760 Cumulative number of frames that could not be classified using single-frame detection.
11762 @item multiple.undetermined
11763 Cumulative number of frames that could not be classified using multiple-frame detection.
11765 @item repeated.current_frame
11766 Which field in the current frame is repeated from the last. One of ``neither'', ``top'', or ``bottom''.
11768 @item repeated.neither
11769 Cumulative number of frames with no repeated field.
11772 Cumulative number of frames with the top field repeated from the previous frame's top field.
11774 @item repeated.bottom
11775 Cumulative number of frames with the bottom field repeated from the previous frame's bottom field.
11778 The filter accepts the following options:
11782 Set interlacing threshold.
11784 Set progressive threshold.
11786 Threshold for repeated field detection.
11788 Number of frames after which a given frame's contribution to the
11789 statistics is halved (i.e., it contributes only 0.5 to its
11790 classification). The default of 0 means that all frames seen are given
11791 full weight of 1.0 forever.
11792 @item analyze_interlaced_flag
11793 When this is not 0 then idet will use the specified number of frames to determine
11794 if the interlaced flag is accurate, it will not count undetermined frames.
11795 If the flag is found to be accurate it will be used without any further
11796 computations, if it is found to be inaccurate it will be cleared without any
11797 further computations. This allows inserting the idet filter as a low computational
11798 method to clean up the interlaced flag
11803 Deinterleave or interleave fields.
11805 This filter allows one to process interlaced images fields without
11806 deinterlacing them. Deinterleaving splits the input frame into 2
11807 fields (so called half pictures). Odd lines are moved to the top
11808 half of the output image, even lines to the bottom half.
11809 You can process (filter) them independently and then re-interleave them.
11811 The filter accepts the following options:
11815 @item chroma_mode, c
11816 @item alpha_mode, a
11817 Available values for @var{luma_mode}, @var{chroma_mode} and
11818 @var{alpha_mode} are:
11824 @item deinterleave, d
11825 Deinterleave fields, placing one above the other.
11827 @item interleave, i
11828 Interleave fields. Reverse the effect of deinterleaving.
11830 Default value is @code{none}.
11832 @item luma_swap, ls
11833 @item chroma_swap, cs
11834 @item alpha_swap, as
11835 Swap luma/chroma/alpha fields. Exchange even & odd lines. Default value is @code{0}.
11840 Apply inflate effect to the video.
11842 This filter replaces the pixel by the local(3x3) average by taking into account
11843 only values higher than the pixel.
11845 It accepts the following options:
11852 Limit the maximum change for each plane, default is 65535.
11853 If 0, plane will remain unchanged.
11858 Simple interlacing filter from progressive contents. This interleaves upper (or
11859 lower) lines from odd frames with lower (or upper) lines from even frames,
11860 halving the frame rate and preserving image height.
11863 Original Original New Frame
11864 Frame 'j' Frame 'j+1' (tff)
11865 ========== =========== ==================
11866 Line 0 --------------------> Frame 'j' Line 0
11867 Line 1 Line 1 ----> Frame 'j+1' Line 1
11868 Line 2 ---------------------> Frame 'j' Line 2
11869 Line 3 Line 3 ----> Frame 'j+1' Line 3
11871 New Frame + 1 will be generated by Frame 'j+2' and Frame 'j+3' and so on
11874 It accepts the following optional parameters:
11878 This determines whether the interlaced frame is taken from the even
11879 (tff - default) or odd (bff) lines of the progressive frame.
11882 Vertical lowpass filter to avoid twitter interlacing and
11883 reduce moire patterns.
11887 Disable vertical lowpass filter
11890 Enable linear filter (default)
11893 Enable complex filter. This will slightly less reduce twitter and moire
11894 but better retain detail and subjective sharpness impression.
11901 Deinterlace input video by applying Donald Graft's adaptive kernel
11902 deinterling. Work on interlaced parts of a video to produce
11903 progressive frames.
11905 The description of the accepted parameters follows.
11909 Set the threshold which affects the filter's tolerance when
11910 determining if a pixel line must be processed. It must be an integer
11911 in the range [0,255] and defaults to 10. A value of 0 will result in
11912 applying the process on every pixels.
11915 Paint pixels exceeding the threshold value to white if set to 1.
11919 Set the fields order. Swap fields if set to 1, leave fields alone if
11923 Enable additional sharpening if set to 1. Default is 0.
11926 Enable twoway sharpening if set to 1. Default is 0.
11929 @subsection Examples
11933 Apply default values:
11935 kerndeint=thresh=10:map=0:order=0:sharp=0:twoway=0
11939 Enable additional sharpening:
11945 Paint processed pixels in white:
11953 Slowly update darker pixels.
11955 This filter makes short flashes of light appear longer.
11956 This filter accepts the following options:
11960 Set factor for decaying. Default is .95. Allowed range is from 0 to 1.
11963 Set which planes to filter. Default is all. Allowed range is from 0 to 15.
11966 @section lenscorrection
11968 Correct radial lens distortion
11970 This filter can be used to correct for radial distortion as can result from the use
11971 of wide angle lenses, and thereby re-rectify the image. To find the right parameters
11972 one can use tools available for example as part of opencv or simply trial-and-error.
11973 To use opencv use the calibration sample (under samples/cpp) from the opencv sources
11974 and extract the k1 and k2 coefficients from the resulting matrix.
11976 Note that effectively the same filter is available in the open-source tools Krita and
11977 Digikam from the KDE project.
11979 In contrast to the @ref{vignette} filter, which can also be used to compensate lens errors,
11980 this filter corrects the distortion of the image, whereas @ref{vignette} corrects the
11981 brightness distribution, so you may want to use both filters together in certain
11982 cases, though you will have to take care of ordering, i.e. whether vignetting should
11983 be applied before or after lens correction.
11985 @subsection Options
11987 The filter accepts the following options:
11991 Relative x-coordinate of the focal point of the image, and thereby the center of the
11992 distortion. This value has a range [0,1] and is expressed as fractions of the image
11993 width. Default is 0.5.
11995 Relative y-coordinate of the focal point of the image, and thereby the center of the
11996 distortion. This value has a range [0,1] and is expressed as fractions of the image
11997 height. Default is 0.5.
11999 Coefficient of the quadratic correction term. This value has a range [-1,1]. 0 means
12000 no correction. Default is 0.
12002 Coefficient of the double quadratic correction term. This value has a range [-1,1].
12003 0 means no correction. Default is 0.
12006 The formula that generates the correction is:
12008 @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)
12010 where @var{r_0} is halve of the image diagonal and @var{r_src} and @var{r_tgt} are the
12011 distances from the focal point in the source and target images, respectively.
12015 Apply lens correction via the lensfun library (@url{http://lensfun.sourceforge.net/}).
12017 The @code{lensfun} filter requires the camera make, camera model, and lens model
12018 to apply the lens correction. The filter will load the lensfun database and
12019 query it to find the corresponding camera and lens entries in the database. As
12020 long as these entries can be found with the given options, the filter can
12021 perform corrections on frames. Note that incomplete strings will result in the
12022 filter choosing the best match with the given options, and the filter will
12023 output the chosen camera and lens models (logged with level "info"). You must
12024 provide the make, camera model, and lens model as they are required.
12026 The filter accepts the following options:
12030 The make of the camera (for example, "Canon"). This option is required.
12033 The model of the camera (for example, "Canon EOS 100D"). This option is
12037 The model of the lens (for example, "Canon EF-S 18-55mm f/3.5-5.6 IS STM"). This
12038 option is required.
12041 The type of correction to apply. The following values are valid options:
12045 Enables fixing lens vignetting.
12048 Enables fixing lens geometry. This is the default.
12051 Enables fixing chromatic aberrations.
12054 Enables fixing lens vignetting and lens geometry.
12057 Enables fixing lens vignetting and chromatic aberrations.
12060 Enables fixing both lens geometry and chromatic aberrations.
12063 Enables all possible corrections.
12067 The focal length of the image/video (zoom; expected constant for video). For
12068 example, a 18--55mm lens has focal length range of [18--55], so a value in that
12069 range should be chosen when using that lens. Default 18.
12072 The aperture of the image/video (expected constant for video). Note that
12073 aperture is only used for vignetting correction. Default 3.5.
12075 @item focus_distance
12076 The focus distance of the image/video (expected constant for video). Note that
12077 focus distance is only used for vignetting and only slightly affects the
12078 vignetting correction process. If unknown, leave it at the default value (which
12082 The scale factor which is applied after transformation. After correction the
12083 video is no longer necessarily rectangular. This parameter controls how much of
12084 the resulting image is visible. The value 0 means that a value will be chosen
12085 automatically such that there is little or no unmapped area in the output
12086 image. 1.0 means that no additional scaling is done. Lower values may result
12087 in more of the corrected image being visible, while higher values may avoid
12088 unmapped areas in the output.
12090 @item target_geometry
12091 The target geometry of the output image/video. The following values are valid
12095 @item rectilinear (default)
12098 @item equirectangular
12099 @item fisheye_orthographic
12100 @item fisheye_stereographic
12101 @item fisheye_equisolid
12102 @item fisheye_thoby
12105 Apply the reverse of image correction (instead of correcting distortion, apply
12108 @item interpolation
12109 The type of interpolation used when correcting distortion. The following values
12114 @item linear (default)
12119 @subsection Examples
12123 Apply lens correction with make "Canon", camera model "Canon EOS 100D", and lens
12124 model "Canon EF-S 18-55mm f/3.5-5.6 IS STM" with focal length of "18" and
12128 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
12132 Apply the same as before, but only for the first 5 seconds of video.
12135 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
12142 Obtain the VMAF (Video Multi-Method Assessment Fusion)
12143 score between two input videos.
12145 The obtained VMAF score is printed through the logging system.
12147 It requires Netflix's vmaf library (libvmaf) as a pre-requisite.
12148 After installing the library it can be enabled using:
12149 @code{./configure --enable-libvmaf --enable-version3}.
12150 If no model path is specified it uses the default model: @code{vmaf_v0.6.1.pkl}.
12152 The filter has following options:
12156 Set the model path which is to be used for SVM.
12157 Default value: @code{"vmaf_v0.6.1.pkl"}
12160 Set the file path to be used to store logs.
12163 Set the format of the log file (xml or json).
12165 @item enable_transform
12166 This option can enable/disable the @code{score_transform} applied to the final predicted VMAF score,
12167 if you have specified score_transform option in the input parameter file passed to @code{run_vmaf_training.py}
12168 Default value: @code{false}
12171 Invokes the phone model which will generate VMAF scores higher than in the
12172 regular model, which is more suitable for laptop, TV, etc. viewing conditions.
12175 Enables computing psnr along with vmaf.
12178 Enables computing ssim along with vmaf.
12181 Enables computing ms_ssim along with vmaf.
12184 Set the pool method (mean, min or harmonic mean) to be used for computing vmaf.
12187 Set number of threads to be used when computing vmaf.
12190 Set interval for frame subsampling used when computing vmaf.
12192 @item enable_conf_interval
12193 Enables confidence interval.
12196 This filter also supports the @ref{framesync} options.
12198 On the below examples the input file @file{main.mpg} being processed is
12199 compared with the reference file @file{ref.mpg}.
12202 ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf -f null -
12205 Example with options:
12207 ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf="psnr=1:log_fmt=json" -f null -
12212 Limits the pixel components values to the specified range [min, max].
12214 The filter accepts the following options:
12218 Lower bound. Defaults to the lowest allowed value for the input.
12221 Upper bound. Defaults to the highest allowed value for the input.
12224 Specify which planes will be processed. Defaults to all available.
12231 The filter accepts the following options:
12235 Set the number of loops. Setting this value to -1 will result in infinite loops.
12239 Set maximal size in number of frames. Default is 0.
12242 Set first frame of loop. Default is 0.
12245 @subsection Examples
12249 Loop single first frame infinitely:
12251 loop=loop=-1:size=1:start=0
12255 Loop single first frame 10 times:
12257 loop=loop=10:size=1:start=0
12261 Loop 10 first frames 5 times:
12263 loop=loop=5:size=10:start=0
12269 Apply a 1D LUT to an input video.
12271 The filter accepts the following options:
12275 Set the 1D LUT file name.
12277 Currently supported formats:
12286 Select interpolation mode.
12288 Available values are:
12292 Use values from the nearest defined point.
12294 Interpolate values using the linear interpolation.
12296 Interpolate values using the cosine interpolation.
12298 Interpolate values using the cubic interpolation.
12300 Interpolate values using the spline interpolation.
12307 Apply a 3D LUT to an input video.
12309 The filter accepts the following options:
12313 Set the 3D LUT file name.
12315 Currently supported formats:
12329 Select interpolation mode.
12331 Available values are:
12335 Use values from the nearest defined point.
12337 Interpolate values using the 8 points defining a cube.
12339 Interpolate values using a tetrahedron.
12345 Turn certain luma values into transparency.
12347 The filter accepts the following options:
12351 Set the luma which will be used as base for transparency.
12352 Default value is @code{0}.
12355 Set the range of luma values to be keyed out.
12356 Default value is @code{0}.
12359 Set the range of softness. Default value is @code{0}.
12360 Use this to control gradual transition from zero to full transparency.
12363 @section lut, lutrgb, lutyuv
12365 Compute a look-up table for binding each pixel component input value
12366 to an output value, and apply it to the input video.
12368 @var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb}
12369 to an RGB input video.
12371 These filters accept the following parameters:
12374 set first pixel component expression
12376 set second pixel component expression
12378 set third pixel component expression
12380 set fourth pixel component expression, corresponds to the alpha component
12383 set red component expression
12385 set green component expression
12387 set blue component expression
12389 alpha component expression
12392 set Y/luminance component expression
12394 set U/Cb component expression
12396 set V/Cr component expression
12399 Each of them specifies the expression to use for computing the lookup table for
12400 the corresponding pixel component values.
12402 The exact component associated to each of the @var{c*} options depends on the
12405 The @var{lut} filter requires either YUV or RGB pixel formats in input,
12406 @var{lutrgb} requires RGB pixel formats in input, and @var{lutyuv} requires YUV.
12408 The expressions can contain the following constants and functions:
12413 The input width and height.
12416 The input value for the pixel component.
12419 The input value, clipped to the @var{minval}-@var{maxval} range.
12422 The maximum value for the pixel component.
12425 The minimum value for the pixel component.
12428 The negated value for the pixel component value, clipped to the
12429 @var{minval}-@var{maxval} range; it corresponds to the expression
12430 "maxval-clipval+minval".
12433 The computed value in @var{val}, clipped to the
12434 @var{minval}-@var{maxval} range.
12436 @item gammaval(gamma)
12437 The computed gamma correction value of the pixel component value,
12438 clipped to the @var{minval}-@var{maxval} range. It corresponds to the
12440 "pow((clipval-minval)/(maxval-minval)\,@var{gamma})*(maxval-minval)+minval"
12444 All expressions default to "val".
12446 @subsection Examples
12450 Negate input video:
12452 lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val"
12453 lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val"
12456 The above is the same as:
12458 lutrgb="r=negval:g=negval:b=negval"
12459 lutyuv="y=negval:u=negval:v=negval"
12469 Remove chroma components, turning the video into a graytone image:
12471 lutyuv="u=128:v=128"
12475 Apply a luma burning effect:
12481 Remove green and blue components:
12487 Set a constant alpha channel value on input:
12489 format=rgba,lutrgb=a="maxval-minval/2"
12493 Correct luminance gamma by a factor of 0.5:
12495 lutyuv=y=gammaval(0.5)
12499 Discard least significant bits of luma:
12501 lutyuv=y='bitand(val, 128+64+32)'
12505 Technicolor like effect:
12507 lutyuv=u='(val-maxval/2)*2+maxval/2':v='(val-maxval/2)*2+maxval/2'
12511 @section lut2, tlut2
12513 The @code{lut2} filter takes two input streams and outputs one
12516 The @code{tlut2} (time lut2) filter takes two consecutive frames
12517 from one single stream.
12519 This filter accepts the following parameters:
12522 set first pixel component expression
12524 set second pixel component expression
12526 set third pixel component expression
12528 set fourth pixel component expression, corresponds to the alpha component
12531 set output bit depth, only available for @code{lut2} filter. By default is 0,
12532 which means bit depth is automatically picked from first input format.
12535 Each of them specifies the expression to use for computing the lookup table for
12536 the corresponding pixel component values.
12538 The exact component associated to each of the @var{c*} options depends on the
12541 The expressions can contain the following constants:
12546 The input width and height.
12549 The first input value for the pixel component.
12552 The second input value for the pixel component.
12555 The first input video bit depth.
12558 The second input video bit depth.
12561 All expressions default to "x".
12563 @subsection Examples
12567 Highlight differences between two RGB video streams:
12569 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)'
12573 Highlight differences between two YUV video streams:
12575 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)'
12579 Show max difference between two video streams:
12581 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)))'
12585 @section maskedclamp
12587 Clamp the first input stream with the second input and third input stream.
12589 Returns the value of first stream to be between second input
12590 stream - @code{undershoot} and third input stream + @code{overshoot}.
12592 This filter accepts the following options:
12595 Default value is @code{0}.
12598 Default value is @code{0}.
12601 Set which planes will be processed as bitmap, unprocessed planes will be
12602 copied from first stream.
12603 By default value 0xf, all planes will be processed.
12606 @section maskedmerge
12608 Merge the first input stream with the second input stream using per pixel
12609 weights in the third input stream.
12611 A value of 0 in the third stream pixel component means that pixel component
12612 from first stream is returned unchanged, while maximum value (eg. 255 for
12613 8-bit videos) means that pixel component from second stream is returned
12614 unchanged. Intermediate values define the amount of merging between both
12615 input stream's pixel components.
12617 This filter accepts the following options:
12620 Set which planes will be processed as bitmap, unprocessed planes will be
12621 copied from first stream.
12622 By default value 0xf, all planes will be processed.
12626 Create mask from input video.
12628 For example it is useful to create motion masks after @code{tblend} filter.
12630 This filter accepts the following options:
12634 Set low threshold. Any pixel component lower or exact than this value will be set to 0.
12637 Set high threshold. Any pixel component higher than this value will be set to max value
12638 allowed for current pixel format.
12641 Set planes to filter, by default all available planes are filtered.
12644 Fill all frame pixels with this value.
12647 Set max average pixel value for frame. If sum of all pixel components is higher that this
12648 average, output frame will be completely filled with value set by @var{fill} option.
12649 Typically useful for scene changes when used in combination with @code{tblend} filter.
12654 Apply motion-compensation deinterlacing.
12656 It needs one field per frame as input and must thus be used together
12657 with yadif=1/3 or equivalent.
12659 This filter accepts the following options:
12662 Set the deinterlacing mode.
12664 It accepts one of the following values:
12669 use iterative motion estimation
12671 like @samp{slow}, but use multiple reference frames.
12673 Default value is @samp{fast}.
12676 Set the picture field parity assumed for the input video. It must be
12677 one of the following values:
12681 assume top field first
12683 assume bottom field first
12686 Default value is @samp{bff}.
12689 Set per-block quantization parameter (QP) used by the internal
12692 Higher values should result in a smoother motion vector field but less
12693 optimal individual vectors. Default value is 1.
12696 @section mergeplanes
12698 Merge color channel components from several video streams.
12700 The filter accepts up to 4 input streams, and merge selected input
12701 planes to the output video.
12703 This filter accepts the following options:
12706 Set input to output plane mapping. Default is @code{0}.
12708 The mappings is specified as a bitmap. It should be specified as a
12709 hexadecimal number in the form 0xAa[Bb[Cc[Dd]]]. 'Aa' describes the
12710 mapping for the first plane of the output stream. 'A' sets the number of
12711 the input stream to use (from 0 to 3), and 'a' the plane number of the
12712 corresponding input to use (from 0 to 3). The rest of the mappings is
12713 similar, 'Bb' describes the mapping for the output stream second
12714 plane, 'Cc' describes the mapping for the output stream third plane and
12715 'Dd' describes the mapping for the output stream fourth plane.
12718 Set output pixel format. Default is @code{yuva444p}.
12721 @subsection Examples
12725 Merge three gray video streams of same width and height into single video stream:
12727 [a0][a1][a2]mergeplanes=0x001020:yuv444p
12731 Merge 1st yuv444p stream and 2nd gray video stream into yuva444p video stream:
12733 [a0][a1]mergeplanes=0x00010210:yuva444p
12737 Swap Y and A plane in yuva444p stream:
12739 format=yuva444p,mergeplanes=0x03010200:yuva444p
12743 Swap U and V plane in yuv420p stream:
12745 format=yuv420p,mergeplanes=0x000201:yuv420p
12749 Cast a rgb24 clip to yuv444p:
12751 format=rgb24,mergeplanes=0x000102:yuv444p
12757 Estimate and export motion vectors using block matching algorithms.
12758 Motion vectors are stored in frame side data to be used by other filters.
12760 This filter accepts the following options:
12763 Specify the motion estimation method. Accepts one of the following values:
12767 Exhaustive search algorithm.
12769 Three step search algorithm.
12771 Two dimensional logarithmic search algorithm.
12773 New three step search algorithm.
12775 Four step search algorithm.
12777 Diamond search algorithm.
12779 Hexagon-based search algorithm.
12781 Enhanced predictive zonal search algorithm.
12783 Uneven multi-hexagon search algorithm.
12785 Default value is @samp{esa}.
12788 Macroblock size. Default @code{16}.
12791 Search parameter. Default @code{7}.
12794 @section midequalizer
12796 Apply Midway Image Equalization effect using two video streams.
12798 Midway Image Equalization adjusts a pair of images to have the same
12799 histogram, while maintaining their dynamics as much as possible. It's
12800 useful for e.g. matching exposures from a pair of stereo cameras.
12802 This filter has two inputs and one output, which must be of same pixel format, but
12803 may be of different sizes. The output of filter is first input adjusted with
12804 midway histogram of both inputs.
12806 This filter accepts the following option:
12810 Set which planes to process. Default is @code{15}, which is all available planes.
12813 @section minterpolate
12815 Convert the video to specified frame rate using motion interpolation.
12817 This filter accepts the following options:
12820 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}.
12823 Motion interpolation mode. Following values are accepted:
12826 Duplicate previous or next frame for interpolating new ones.
12828 Blend source frames. Interpolated frame is mean of previous and next frames.
12830 Motion compensated interpolation. Following options are effective when this mode is selected:
12834 Motion compensation mode. Following values are accepted:
12837 Overlapped block motion compensation.
12839 Adaptive overlapped block motion compensation. Window weighting coefficients are controlled adaptively according to the reliabilities of the neighboring motion vectors to reduce oversmoothing.
12841 Default mode is @samp{obmc}.
12844 Motion estimation mode. Following values are accepted:
12847 Bidirectional motion estimation. Motion vectors are estimated for each source frame in both forward and backward directions.
12849 Bilateral motion estimation. Motion vectors are estimated directly for interpolated frame.
12851 Default mode is @samp{bilat}.
12854 The algorithm to be used for motion estimation. Following values are accepted:
12857 Exhaustive search algorithm.
12859 Three step search algorithm.
12861 Two dimensional logarithmic search algorithm.
12863 New three step search algorithm.
12865 Four step search algorithm.
12867 Diamond search algorithm.
12869 Hexagon-based search algorithm.
12871 Enhanced predictive zonal search algorithm.
12873 Uneven multi-hexagon search algorithm.
12875 Default algorithm is @samp{epzs}.
12878 Macroblock size. Default @code{16}.
12881 Motion estimation search parameter. Default @code{32}.
12884 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).
12889 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:
12892 Disable scene change detection.
12894 Frame difference. Corresponding pixel values are compared and if it satisfies @var{scd_threshold} scene change is detected.
12896 Default method is @samp{fdiff}.
12898 @item scd_threshold
12899 Scene change detection threshold. Default is @code{5.0}.
12904 Mix several video input streams into one video stream.
12906 A description of the accepted options follows.
12910 The number of inputs. If unspecified, it defaults to 2.
12913 Specify weight of each input video stream as sequence.
12914 Each weight is separated by space. If number of weights
12915 is smaller than number of @var{frames} last specified
12916 weight will be used for all remaining unset weights.
12919 Specify scale, if it is set it will be multiplied with sum
12920 of each weight multiplied with pixel values to give final destination
12921 pixel value. By default @var{scale} is auto scaled to sum of weights.
12924 Specify how end of stream is determined.
12927 The duration of the longest input. (default)
12930 The duration of the shortest input.
12933 The duration of the first input.
12937 @section mpdecimate
12939 Drop frames that do not differ greatly from the previous frame in
12940 order to reduce frame rate.
12942 The main use of this filter is for very-low-bitrate encoding
12943 (e.g. streaming over dialup modem), but it could in theory be used for
12944 fixing movies that were inverse-telecined incorrectly.
12946 A description of the accepted options follows.
12950 Set the maximum number of consecutive frames which can be dropped (if
12951 positive), or the minimum interval between dropped frames (if
12952 negative). If the value is 0, the frame is dropped disregarding the
12953 number of previous sequentially dropped frames.
12955 Default value is 0.
12960 Set the dropping threshold values.
12962 Values for @option{hi} and @option{lo} are for 8x8 pixel blocks and
12963 represent actual pixel value differences, so a threshold of 64
12964 corresponds to 1 unit of difference for each pixel, or the same spread
12965 out differently over the block.
12967 A frame is a candidate for dropping if no 8x8 blocks differ by more
12968 than a threshold of @option{hi}, and if no more than @option{frac} blocks (1
12969 meaning the whole image) differ by more than a threshold of @option{lo}.
12971 Default value for @option{hi} is 64*12, default value for @option{lo} is
12972 64*5, and default value for @option{frac} is 0.33.
12978 Negate (invert) the input video.
12980 It accepts the following option:
12985 With value 1, it negates the alpha component, if present. Default value is 0.
12991 Denoise frames using Non-Local Means algorithm.
12993 Each pixel is adjusted by looking for other pixels with similar contexts. This
12994 context similarity is defined by comparing their surrounding patches of size
12995 @option{p}x@option{p}. Patches are searched in an area of @option{r}x@option{r}
12998 Note that the research area defines centers for patches, which means some
12999 patches will be made of pixels outside that research area.
13001 The filter accepts the following options.
13005 Set denoising strength. Default is 1.0. Must be in range [1.0, 30.0].
13008 Set patch size. Default is 7. Must be odd number in range [0, 99].
13011 Same as @option{p} but for chroma planes.
13013 The default value is @var{0} and means automatic.
13016 Set research size. Default is 15. Must be odd number in range [0, 99].
13019 Same as @option{r} but for chroma planes.
13021 The default value is @var{0} and means automatic.
13026 Deinterlace video using neural network edge directed interpolation.
13028 This filter accepts the following options:
13032 Mandatory option, without binary file filter can not work.
13033 Currently file can be found here:
13034 https://github.com/dubhater/vapoursynth-nnedi3/blob/master/src/nnedi3_weights.bin
13037 Set which frames to deinterlace, by default it is @code{all}.
13038 Can be @code{all} or @code{interlaced}.
13041 Set mode of operation.
13043 Can be one of the following:
13047 Use frame flags, both fields.
13049 Use frame flags, single field.
13051 Use top field only.
13053 Use bottom field only.
13055 Use both fields, top first.
13057 Use both fields, bottom first.
13061 Set which planes to process, by default filter process all frames.
13064 Set size of local neighborhood around each pixel, used by the predictor neural
13067 Can be one of the following:
13080 Set the number of neurons in predictor neural network.
13081 Can be one of the following:
13092 Controls the number of different neural network predictions that are blended
13093 together to compute the final output value. Can be @code{fast}, default or
13097 Set which set of weights to use in the predictor.
13098 Can be one of the following:
13102 weights trained to minimize absolute error
13104 weights trained to minimize squared error
13108 Controls whether or not the prescreener neural network is used to decide
13109 which pixels should be processed by the predictor neural network and which
13110 can be handled by simple cubic interpolation.
13111 The prescreener is trained to know whether cubic interpolation will be
13112 sufficient for a pixel or whether it should be predicted by the predictor nn.
13113 The computational complexity of the prescreener nn is much less than that of
13114 the predictor nn. Since most pixels can be handled by cubic interpolation,
13115 using the prescreener generally results in much faster processing.
13116 The prescreener is pretty accurate, so the difference between using it and not
13117 using it is almost always unnoticeable.
13119 Can be one of the following:
13127 Default is @code{new}.
13130 Set various debugging flags.
13135 Force libavfilter not to use any of the specified pixel formats for the
13136 input to the next filter.
13138 It accepts the following parameters:
13142 A '|'-separated list of pixel format names, such as
13143 pix_fmts=yuv420p|monow|rgb24".
13147 @subsection Examples
13151 Force libavfilter to use a format different from @var{yuv420p} for the
13152 input to the vflip filter:
13154 noformat=pix_fmts=yuv420p,vflip
13158 Convert the input video to any of the formats not contained in the list:
13160 noformat=yuv420p|yuv444p|yuv410p
13166 Add noise on video input frame.
13168 The filter accepts the following options:
13176 Set noise seed for specific pixel component or all pixel components in case
13177 of @var{all_seed}. Default value is @code{123457}.
13179 @item all_strength, alls
13180 @item c0_strength, c0s
13181 @item c1_strength, c1s
13182 @item c2_strength, c2s
13183 @item c3_strength, c3s
13184 Set noise strength for specific pixel component or all pixel components in case
13185 @var{all_strength}. Default value is @code{0}. Allowed range is [0, 100].
13187 @item all_flags, allf
13188 @item c0_flags, c0f
13189 @item c1_flags, c1f
13190 @item c2_flags, c2f
13191 @item c3_flags, c3f
13192 Set pixel component flags or set flags for all components if @var{all_flags}.
13193 Available values for component flags are:
13196 averaged temporal noise (smoother)
13198 mix random noise with a (semi)regular pattern
13200 temporal noise (noise pattern changes between frames)
13202 uniform noise (gaussian otherwise)
13206 @subsection Examples
13208 Add temporal and uniform noise to input video:
13210 noise=alls=20:allf=t+u
13215 Normalize RGB video (aka histogram stretching, contrast stretching).
13216 See: https://en.wikipedia.org/wiki/Normalization_(image_processing)
13218 For each channel of each frame, the filter computes the input range and maps
13219 it linearly to the user-specified output range. The output range defaults
13220 to the full dynamic range from pure black to pure white.
13222 Temporal smoothing can be used on the input range to reduce flickering (rapid
13223 changes in brightness) caused when small dark or bright objects enter or leave
13224 the scene. This is similar to the auto-exposure (automatic gain control) on a
13225 video camera, and, like a video camera, it may cause a period of over- or
13226 under-exposure of the video.
13228 The R,G,B channels can be normalized independently, which may cause some
13229 color shifting, or linked together as a single channel, which prevents
13230 color shifting. Linked normalization preserves hue. Independent normalization
13231 does not, so it can be used to remove some color casts. Independent and linked
13232 normalization can be combined in any ratio.
13234 The normalize filter accepts the following options:
13239 Colors which define the output range. The minimum input value is mapped to
13240 the @var{blackpt}. The maximum input value is mapped to the @var{whitept}.
13241 The defaults are black and white respectively. Specifying white for
13242 @var{blackpt} and black for @var{whitept} will give color-inverted,
13243 normalized video. Shades of grey can be used to reduce the dynamic range
13244 (contrast). Specifying saturated colors here can create some interesting
13248 The number of previous frames to use for temporal smoothing. The input range
13249 of each channel is smoothed using a rolling average over the current frame
13250 and the @var{smoothing} previous frames. The default is 0 (no temporal
13254 Controls the ratio of independent (color shifting) channel normalization to
13255 linked (color preserving) normalization. 0.0 is fully linked, 1.0 is fully
13256 independent. Defaults to 1.0 (fully independent).
13259 Overall strength of the filter. 1.0 is full strength. 0.0 is a rather
13260 expensive no-op. Defaults to 1.0 (full strength).
13264 @subsection Examples
13266 Stretch video contrast to use the full dynamic range, with no temporal
13267 smoothing; may flicker depending on the source content:
13269 normalize=blackpt=black:whitept=white:smoothing=0
13272 As above, but with 50 frames of temporal smoothing; flicker should be
13273 reduced, depending on the source content:
13275 normalize=blackpt=black:whitept=white:smoothing=50
13278 As above, but with hue-preserving linked channel normalization:
13280 normalize=blackpt=black:whitept=white:smoothing=50:independence=0
13283 As above, but with half strength:
13285 normalize=blackpt=black:whitept=white:smoothing=50:independence=0:strength=0.5
13288 Map the darkest input color to red, the brightest input color to cyan:
13290 normalize=blackpt=red:whitept=cyan
13295 Pass the video source unchanged to the output.
13298 Optical Character Recognition
13300 This filter uses Tesseract for optical character recognition. To enable
13301 compilation of this filter, you need to configure FFmpeg with
13302 @code{--enable-libtesseract}.
13304 It accepts the following options:
13308 Set datapath to tesseract data. Default is to use whatever was
13309 set at installation.
13312 Set language, default is "eng".
13315 Set character whitelist.
13318 Set character blacklist.
13321 The filter exports recognized text as the frame metadata @code{lavfi.ocr.text}.
13322 The filter exports confidence of recognized words as the frame metadata @code{lavfi.ocr.confidence}.
13326 Apply a video transform using libopencv.
13328 To enable this filter, install the libopencv library and headers and
13329 configure FFmpeg with @code{--enable-libopencv}.
13331 It accepts the following parameters:
13336 The name of the libopencv filter to apply.
13338 @item filter_params
13339 The parameters to pass to the libopencv filter. If not specified, the default
13340 values are assumed.
13344 Refer to the official libopencv documentation for more precise
13346 @url{http://docs.opencv.org/master/modules/imgproc/doc/filtering.html}
13348 Several libopencv filters are supported; see the following subsections.
13353 Dilate an image by using a specific structuring element.
13354 It corresponds to the libopencv function @code{cvDilate}.
13356 It accepts the parameters: @var{struct_el}|@var{nb_iterations}.
13358 @var{struct_el} represents a structuring element, and has the syntax:
13359 @var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape}
13361 @var{cols} and @var{rows} represent the number of columns and rows of
13362 the structuring element, @var{anchor_x} and @var{anchor_y} the anchor
13363 point, and @var{shape} the shape for the structuring element. @var{shape}
13364 must be "rect", "cross", "ellipse", or "custom".
13366 If the value for @var{shape} is "custom", it must be followed by a
13367 string of the form "=@var{filename}". The file with name
13368 @var{filename} is assumed to represent a binary image, with each
13369 printable character corresponding to a bright pixel. When a custom
13370 @var{shape} is used, @var{cols} and @var{rows} are ignored, the number
13371 or columns and rows of the read file are assumed instead.
13373 The default value for @var{struct_el} is "3x3+0x0/rect".
13375 @var{nb_iterations} specifies the number of times the transform is
13376 applied to the image, and defaults to 1.
13380 # Use the default values
13383 # Dilate using a structuring element with a 5x5 cross, iterating two times
13384 ocv=filter_name=dilate:filter_params=5x5+2x2/cross|2
13386 # Read the shape from the file diamond.shape, iterating two times.
13387 # The file diamond.shape may contain a pattern of characters like this
13393 # The specified columns and rows are ignored
13394 # but the anchor point coordinates are not
13395 ocv=dilate:0x0+2x2/custom=diamond.shape|2
13400 Erode an image by using a specific structuring element.
13401 It corresponds to the libopencv function @code{cvErode}.
13403 It accepts the parameters: @var{struct_el}:@var{nb_iterations},
13404 with the same syntax and semantics as the @ref{dilate} filter.
13408 Smooth the input video.
13410 The filter takes the following parameters:
13411 @var{type}|@var{param1}|@var{param2}|@var{param3}|@var{param4}.
13413 @var{type} is the type of smooth filter to apply, and must be one of
13414 the following values: "blur", "blur_no_scale", "median", "gaussian",
13415 or "bilateral". The default value is "gaussian".
13417 The meaning of @var{param1}, @var{param2}, @var{param3}, and @var{param4}
13418 depends on the smooth type. @var{param1} and
13419 @var{param2} accept integer positive values or 0. @var{param3} and
13420 @var{param4} accept floating point values.
13422 The default value for @var{param1} is 3. The default value for the
13423 other parameters is 0.
13425 These parameters correspond to the parameters assigned to the
13426 libopencv function @code{cvSmooth}.
13428 @section oscilloscope
13430 2D Video Oscilloscope.
13432 Useful to measure spatial impulse, step responses, chroma delays, etc.
13434 It accepts the following parameters:
13438 Set scope center x position.
13441 Set scope center y position.
13444 Set scope size, relative to frame diagonal.
13447 Set scope tilt/rotation.
13453 Set trace center x position.
13456 Set trace center y position.
13459 Set trace width, relative to width of frame.
13462 Set trace height, relative to height of frame.
13465 Set which components to trace. By default it traces first three components.
13468 Draw trace grid. By default is enabled.
13471 Draw some statistics. By default is enabled.
13474 Draw scope. By default is enabled.
13477 @subsection Examples
13481 Inspect full first row of video frame.
13483 oscilloscope=x=0.5:y=0:s=1
13487 Inspect full last row of video frame.
13489 oscilloscope=x=0.5:y=1:s=1
13493 Inspect full 5th line of video frame of height 1080.
13495 oscilloscope=x=0.5:y=5/1080:s=1
13499 Inspect full last column of video frame.
13501 oscilloscope=x=1:y=0.5:s=1:t=1
13509 Overlay one video on top of another.
13511 It takes two inputs and has one output. The first input is the "main"
13512 video on which the second input is overlaid.
13514 It accepts the following parameters:
13516 A description of the accepted options follows.
13521 Set the expression for the x and y coordinates of the overlaid video
13522 on the main video. Default value is "0" for both expressions. In case
13523 the expression is invalid, it is set to a huge value (meaning that the
13524 overlay will not be displayed within the output visible area).
13527 See @ref{framesync}.
13530 Set when the expressions for @option{x}, and @option{y} are evaluated.
13532 It accepts the following values:
13535 only evaluate expressions once during the filter initialization or
13536 when a command is processed
13539 evaluate expressions for each incoming frame
13542 Default value is @samp{frame}.
13545 See @ref{framesync}.
13548 Set the format for the output video.
13550 It accepts the following values:
13553 force YUV420 output
13556 force YUV422 output
13559 force YUV444 output
13562 force packed RGB output
13565 force planar RGB output
13568 automatically pick format
13571 Default value is @samp{yuv420}.
13574 See @ref{framesync}.
13577 Set format of alpha of the overlaid video, it can be @var{straight} or
13578 @var{premultiplied}. Default is @var{straight}.
13581 The @option{x}, and @option{y} expressions can contain the following
13587 The main input width and height.
13591 The overlay input width and height.
13595 The computed values for @var{x} and @var{y}. They are evaluated for
13600 horizontal and vertical chroma subsample values of the output
13601 format. For example for the pixel format "yuv422p" @var{hsub} is 2 and
13605 the number of input frame, starting from 0
13608 the position in the file of the input frame, NAN if unknown
13611 The timestamp, expressed in seconds. It's NAN if the input timestamp is unknown.
13615 This filter also supports the @ref{framesync} options.
13617 Note that the @var{n}, @var{pos}, @var{t} variables are available only
13618 when evaluation is done @emph{per frame}, and will evaluate to NAN
13619 when @option{eval} is set to @samp{init}.
13621 Be aware that frames are taken from each input video in timestamp
13622 order, hence, if their initial timestamps differ, it is a good idea
13623 to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to
13624 have them begin in the same zero timestamp, as the example for
13625 the @var{movie} filter does.
13627 You can chain together more overlays but you should test the
13628 efficiency of such approach.
13630 @subsection Commands
13632 This filter supports the following commands:
13636 Modify the x and y of the overlay input.
13637 The command accepts the same syntax of the corresponding option.
13639 If the specified expression is not valid, it is kept at its current
13643 @subsection Examples
13647 Draw the overlay at 10 pixels from the bottom right corner of the main
13650 overlay=main_w-overlay_w-10:main_h-overlay_h-10
13653 Using named options the example above becomes:
13655 overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10
13659 Insert a transparent PNG logo in the bottom left corner of the input,
13660 using the @command{ffmpeg} tool with the @code{-filter_complex} option:
13662 ffmpeg -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output
13666 Insert 2 different transparent PNG logos (second logo on bottom
13667 right corner) using the @command{ffmpeg} tool:
13669 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
13673 Add a transparent color layer on top of the main video; @code{WxH}
13674 must specify the size of the main input to the overlay filter:
13676 color=color=red@@.3:size=WxH [over]; [in][over] overlay [out]
13680 Play an original video and a filtered version (here with the deshake
13681 filter) side by side using the @command{ffplay} tool:
13683 ffplay input.avi -vf 'split[a][b]; [a]pad=iw*2:ih[src]; [b]deshake[filt]; [src][filt]overlay=w'
13686 The above command is the same as:
13688 ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w'
13692 Make a sliding overlay appearing from the left to the right top part of the
13693 screen starting since time 2:
13695 overlay=x='if(gte(t,2), -w+(t-2)*20, NAN)':y=0
13699 Compose output by putting two input videos side to side:
13701 ffmpeg -i left.avi -i right.avi -filter_complex "
13702 nullsrc=size=200x100 [background];
13703 [0:v] setpts=PTS-STARTPTS, scale=100x100 [left];
13704 [1:v] setpts=PTS-STARTPTS, scale=100x100 [right];
13705 [background][left] overlay=shortest=1 [background+left];
13706 [background+left][right] overlay=shortest=1:x=100 [left+right]
13711 Mask 10-20 seconds of a video by applying the delogo filter to a section
13713 ffmpeg -i test.avi -codec:v:0 wmv2 -ar 11025 -b:v 9000k
13714 -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]'
13719 Chain several overlays in cascade:
13721 nullsrc=s=200x200 [bg];
13722 testsrc=s=100x100, split=4 [in0][in1][in2][in3];
13723 [in0] lutrgb=r=0, [bg] overlay=0:0 [mid0];
13724 [in1] lutrgb=g=0, [mid0] overlay=100:0 [mid1];
13725 [in2] lutrgb=b=0, [mid1] overlay=0:100 [mid2];
13726 [in3] null, [mid2] overlay=100:100 [out0]
13733 Apply Overcomplete Wavelet denoiser.
13735 The filter accepts the following options:
13741 Larger depth values will denoise lower frequency components more, but
13742 slow down filtering.
13744 Must be an int in the range 8-16, default is @code{8}.
13746 @item luma_strength, ls
13749 Must be a double value in the range 0-1000, default is @code{1.0}.
13751 @item chroma_strength, cs
13752 Set chroma strength.
13754 Must be a double value in the range 0-1000, default is @code{1.0}.
13760 Add paddings to the input image, and place the original input at the
13761 provided @var{x}, @var{y} coordinates.
13763 It accepts the following parameters:
13768 Specify an expression for the size of the output image with the
13769 paddings added. If the value for @var{width} or @var{height} is 0, the
13770 corresponding input size is used for the output.
13772 The @var{width} expression can reference the value set by the
13773 @var{height} expression, and vice versa.
13775 The default value of @var{width} and @var{height} is 0.
13779 Specify the offsets to place the input image at within the padded area,
13780 with respect to the top/left border of the output image.
13782 The @var{x} expression can reference the value set by the @var{y}
13783 expression, and vice versa.
13785 The default value of @var{x} and @var{y} is 0.
13787 If @var{x} or @var{y} evaluate to a negative number, they'll be changed
13788 so the input image is centered on the padded area.
13791 Specify the color of the padded area. For the syntax of this option,
13792 check the @ref{color syntax,,"Color" section in the ffmpeg-utils
13793 manual,ffmpeg-utils}.
13795 The default value of @var{color} is "black".
13798 Specify when to evaluate @var{width}, @var{height}, @var{x} and @var{y} expression.
13800 It accepts the following values:
13804 Only evaluate expressions once during the filter initialization or when
13805 a command is processed.
13808 Evaluate expressions for each incoming frame.
13812 Default value is @samp{init}.
13815 Pad to aspect instead to a resolution.
13819 The value for the @var{width}, @var{height}, @var{x}, and @var{y}
13820 options are expressions containing the following constants:
13825 The input video width and height.
13829 These are the same as @var{in_w} and @var{in_h}.
13833 The output width and height (the size of the padded area), as
13834 specified by the @var{width} and @var{height} expressions.
13838 These are the same as @var{out_w} and @var{out_h}.
13842 The x and y offsets as specified by the @var{x} and @var{y}
13843 expressions, or NAN if not yet specified.
13846 same as @var{iw} / @var{ih}
13849 input sample aspect ratio
13852 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
13856 The horizontal and vertical chroma subsample values. For example for the
13857 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
13860 @subsection Examples
13864 Add paddings with the color "violet" to the input video. The output video
13865 size is 640x480, and the top-left corner of the input video is placed at
13868 pad=640:480:0:40:violet
13871 The example above is equivalent to the following command:
13873 pad=width=640:height=480:x=0:y=40:color=violet
13877 Pad the input to get an output with dimensions increased by 3/2,
13878 and put the input video at the center of the padded area:
13880 pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2"
13884 Pad the input to get a squared output with size equal to the maximum
13885 value between the input width and height, and put the input video at
13886 the center of the padded area:
13888 pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2"
13892 Pad the input to get a final w/h ratio of 16:9:
13894 pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2"
13898 In case of anamorphic video, in order to set the output display aspect
13899 correctly, it is necessary to use @var{sar} in the expression,
13900 according to the relation:
13902 (ih * X / ih) * sar = output_dar
13903 X = output_dar / sar
13906 Thus the previous example needs to be modified to:
13908 pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2"
13912 Double the output size and put the input video in the bottom-right
13913 corner of the output padded area:
13915 pad="2*iw:2*ih:ow-iw:oh-ih"
13919 @anchor{palettegen}
13920 @section palettegen
13922 Generate one palette for a whole video stream.
13924 It accepts the following options:
13928 Set the maximum number of colors to quantize in the palette.
13929 Note: the palette will still contain 256 colors; the unused palette entries
13932 @item reserve_transparent
13933 Create a palette of 255 colors maximum and reserve the last one for
13934 transparency. Reserving the transparency color is useful for GIF optimization.
13935 If not set, the maximum of colors in the palette will be 256. You probably want
13936 to disable this option for a standalone image.
13939 @item transparency_color
13940 Set the color that will be used as background for transparency.
13943 Set statistics mode.
13945 It accepts the following values:
13948 Compute full frame histograms.
13950 Compute histograms only for the part that differs from previous frame. This
13951 might be relevant to give more importance to the moving part of your input if
13952 the background is static.
13954 Compute new histogram for each frame.
13957 Default value is @var{full}.
13960 The filter also exports the frame metadata @code{lavfi.color_quant_ratio}
13961 (@code{nb_color_in / nb_color_out}) which you can use to evaluate the degree of
13962 color quantization of the palette. This information is also visible at
13963 @var{info} logging level.
13965 @subsection Examples
13969 Generate a representative palette of a given video using @command{ffmpeg}:
13971 ffmpeg -i input.mkv -vf palettegen palette.png
13975 @section paletteuse
13977 Use a palette to downsample an input video stream.
13979 The filter takes two inputs: one video stream and a palette. The palette must
13980 be a 256 pixels image.
13982 It accepts the following options:
13986 Select dithering mode. Available algorithms are:
13989 Ordered 8x8 bayer dithering (deterministic)
13991 Dithering as defined by Paul Heckbert in 1982 (simple error diffusion).
13992 Note: this dithering is sometimes considered "wrong" and is included as a
13994 @item floyd_steinberg
13995 Floyd and Steingberg dithering (error diffusion)
13997 Frankie Sierra dithering v2 (error diffusion)
13999 Frankie Sierra dithering v2 "Lite" (error diffusion)
14002 Default is @var{sierra2_4a}.
14005 When @var{bayer} dithering is selected, this option defines the scale of the
14006 pattern (how much the crosshatch pattern is visible). A low value means more
14007 visible pattern for less banding, and higher value means less visible pattern
14008 at the cost of more banding.
14010 The option must be an integer value in the range [0,5]. Default is @var{2}.
14013 If set, define the zone to process
14017 Only the changing rectangle will be reprocessed. This is similar to GIF
14018 cropping/offsetting compression mechanism. This option can be useful for speed
14019 if only a part of the image is changing, and has use cases such as limiting the
14020 scope of the error diffusal @option{dither} to the rectangle that bounds the
14021 moving scene (it leads to more deterministic output if the scene doesn't change
14022 much, and as a result less moving noise and better GIF compression).
14025 Default is @var{none}.
14028 Take new palette for each output frame.
14030 @item alpha_threshold
14031 Sets the alpha threshold for transparency. Alpha values above this threshold
14032 will be treated as completely opaque, and values below this threshold will be
14033 treated as completely transparent.
14035 The option must be an integer value in the range [0,255]. Default is @var{128}.
14038 @subsection Examples
14042 Use a palette (generated for example with @ref{palettegen}) to encode a GIF
14043 using @command{ffmpeg}:
14045 ffmpeg -i input.mkv -i palette.png -lavfi paletteuse output.gif
14049 @section perspective
14051 Correct perspective of video not recorded perpendicular to the screen.
14053 A description of the accepted parameters follows.
14064 Set coordinates expression for top left, top right, bottom left and bottom right corners.
14065 Default values are @code{0:0:W:0:0:H:W:H} with which perspective will remain unchanged.
14066 If the @code{sense} option is set to @code{source}, then the specified points will be sent
14067 to the corners of the destination. If the @code{sense} option is set to @code{destination},
14068 then the corners of the source will be sent to the specified coordinates.
14070 The expressions can use the following variables:
14075 the width and height of video frame.
14079 Output frame count.
14082 @item interpolation
14083 Set interpolation for perspective correction.
14085 It accepts the following values:
14091 Default value is @samp{linear}.
14094 Set interpretation of coordinate options.
14096 It accepts the following values:
14100 Send point in the source specified by the given coordinates to
14101 the corners of the destination.
14103 @item 1, destination
14105 Send the corners of the source to the point in the destination specified
14106 by the given coordinates.
14108 Default value is @samp{source}.
14112 Set when the expressions for coordinates @option{x0,y0,...x3,y3} are evaluated.
14114 It accepts the following values:
14117 only evaluate expressions once during the filter initialization or
14118 when a command is processed
14121 evaluate expressions for each incoming frame
14124 Default value is @samp{init}.
14129 Delay interlaced video by one field time so that the field order changes.
14131 The intended use is to fix PAL movies that have been captured with the
14132 opposite field order to the film-to-video transfer.
14134 A description of the accepted parameters follows.
14140 It accepts the following values:
14143 Capture field order top-first, transfer bottom-first.
14144 Filter will delay the bottom field.
14147 Capture field order bottom-first, transfer top-first.
14148 Filter will delay the top field.
14151 Capture and transfer with the same field order. This mode only exists
14152 for the documentation of the other options to refer to, but if you
14153 actually select it, the filter will faithfully do nothing.
14156 Capture field order determined automatically by field flags, transfer
14158 Filter selects among @samp{t} and @samp{b} modes on a frame by frame
14159 basis using field flags. If no field information is available,
14160 then this works just like @samp{u}.
14163 Capture unknown or varying, transfer opposite.
14164 Filter selects among @samp{t} and @samp{b} on a frame by frame basis by
14165 analyzing the images and selecting the alternative that produces best
14166 match between the fields.
14169 Capture top-first, transfer unknown or varying.
14170 Filter selects among @samp{t} and @samp{p} using image analysis.
14173 Capture bottom-first, transfer unknown or varying.
14174 Filter selects among @samp{b} and @samp{p} using image analysis.
14177 Capture determined by field flags, transfer unknown or varying.
14178 Filter selects among @samp{t}, @samp{b} and @samp{p} using field flags and
14179 image analysis. If no field information is available, then this works just
14180 like @samp{U}. This is the default mode.
14183 Both capture and transfer unknown or varying.
14184 Filter selects among @samp{t}, @samp{b} and @samp{p} using image analysis only.
14188 @section photosensitivity
14189 Reduce various flashes in video, so to help users with epilepsy.
14191 It accepts the following options:
14194 Set how many frames to use when filtering. Default is 30.
14197 Set detection threshold factor. Default is 1.
14201 Set how many pixels to skip when sampling frames. Defalt is 1.
14202 Allowed range is from 1 to 1024.
14205 Leave frames unchanged. Default is disabled.
14208 @section pixdesctest
14210 Pixel format descriptor test filter, mainly useful for internal
14211 testing. The output video should be equal to the input video.
14215 format=monow, pixdesctest
14218 can be used to test the monowhite pixel format descriptor definition.
14222 Display sample values of color channels. Mainly useful for checking color
14223 and levels. Minimum supported resolution is 640x480.
14225 The filters accept the following options:
14229 Set scope X position, relative offset on X axis.
14232 Set scope Y position, relative offset on Y axis.
14241 Set window opacity. This window also holds statistics about pixel area.
14244 Set window X position, relative offset on X axis.
14247 Set window Y position, relative offset on Y axis.
14252 Enable the specified chain of postprocessing subfilters using libpostproc. This
14253 library should be automatically selected with a GPL build (@code{--enable-gpl}).
14254 Subfilters must be separated by '/' and can be disabled by prepending a '-'.
14255 Each subfilter and some options have a short and a long name that can be used
14256 interchangeably, i.e. dr/dering are the same.
14258 The filters accept the following options:
14262 Set postprocessing subfilters string.
14265 All subfilters share common options to determine their scope:
14269 Honor the quality commands for this subfilter.
14272 Do chrominance filtering, too (default).
14275 Do luminance filtering only (no chrominance).
14278 Do chrominance filtering only (no luminance).
14281 These options can be appended after the subfilter name, separated by a '|'.
14283 Available subfilters are:
14286 @item hb/hdeblock[|difference[|flatness]]
14287 Horizontal deblocking filter
14290 Difference factor where higher values mean more deblocking (default: @code{32}).
14292 Flatness threshold where lower values mean more deblocking (default: @code{39}).
14295 @item vb/vdeblock[|difference[|flatness]]
14296 Vertical deblocking filter
14299 Difference factor where higher values mean more deblocking (default: @code{32}).
14301 Flatness threshold where lower values mean more deblocking (default: @code{39}).
14304 @item ha/hadeblock[|difference[|flatness]]
14305 Accurate horizontal deblocking filter
14308 Difference factor where higher values mean more deblocking (default: @code{32}).
14310 Flatness threshold where lower values mean more deblocking (default: @code{39}).
14313 @item va/vadeblock[|difference[|flatness]]
14314 Accurate vertical deblocking filter
14317 Difference factor where higher values mean more deblocking (default: @code{32}).
14319 Flatness threshold where lower values mean more deblocking (default: @code{39}).
14323 The horizontal and vertical deblocking filters share the difference and
14324 flatness values so you cannot set different horizontal and vertical
14328 @item h1/x1hdeblock
14329 Experimental horizontal deblocking filter
14331 @item v1/x1vdeblock
14332 Experimental vertical deblocking filter
14337 @item tn/tmpnoise[|threshold1[|threshold2[|threshold3]]], temporal noise reducer
14340 larger -> stronger filtering
14342 larger -> stronger filtering
14344 larger -> stronger filtering
14347 @item al/autolevels[:f/fullyrange], automatic brightness / contrast correction
14350 Stretch luminance to @code{0-255}.
14353 @item lb/linblenddeint
14354 Linear blend deinterlacing filter that deinterlaces the given block by
14355 filtering all lines with a @code{(1 2 1)} filter.
14357 @item li/linipoldeint
14358 Linear interpolating deinterlacing filter that deinterlaces the given block by
14359 linearly interpolating every second line.
14361 @item ci/cubicipoldeint
14362 Cubic interpolating deinterlacing filter deinterlaces the given block by
14363 cubically interpolating every second line.
14365 @item md/mediandeint
14366 Median deinterlacing filter that deinterlaces the given block by applying a
14367 median filter to every second line.
14369 @item fd/ffmpegdeint
14370 FFmpeg deinterlacing filter that deinterlaces the given block by filtering every
14371 second line with a @code{(-1 4 2 4 -1)} filter.
14374 Vertically applied FIR lowpass deinterlacing filter that deinterlaces the given
14375 block by filtering all lines with a @code{(-1 2 6 2 -1)} filter.
14377 @item fq/forceQuant[|quantizer]
14378 Overrides the quantizer table from the input with the constant quantizer you
14386 Default pp filter combination (@code{hb|a,vb|a,dr|a})
14389 Fast pp filter combination (@code{h1|a,v1|a,dr|a})
14392 High quality pp filter combination (@code{ha|a|128|7,va|a,dr|a})
14395 @subsection Examples
14399 Apply horizontal and vertical deblocking, deringing and automatic
14400 brightness/contrast:
14406 Apply default filters without brightness/contrast correction:
14412 Apply default filters and temporal denoiser:
14414 pp=default/tmpnoise|1|2|3
14418 Apply deblocking on luminance only, and switch vertical deblocking on or off
14419 automatically depending on available CPU time:
14426 Apply Postprocessing filter 7. It is variant of the @ref{spp} filter,
14427 similar to spp = 6 with 7 point DCT, where only the center sample is
14430 The filter accepts the following options:
14434 Force a constant quantization parameter. It accepts an integer in range
14435 0 to 63. If not set, the filter will use the QP from the video stream
14439 Set thresholding mode. Available modes are:
14443 Set hard thresholding.
14445 Set soft thresholding (better de-ringing effect, but likely blurrier).
14447 Set medium thresholding (good results, default).
14451 @section premultiply
14452 Apply alpha premultiply effect to input video stream using first plane
14453 of second stream as alpha.
14455 Both streams must have same dimensions and same pixel format.
14457 The filter accepts the following option:
14461 Set which planes will be processed, unprocessed planes will be copied.
14462 By default value 0xf, all planes will be processed.
14465 Do not require 2nd input for processing, instead use alpha plane from input stream.
14469 Apply prewitt operator to input video stream.
14471 The filter accepts the following option:
14475 Set which planes will be processed, unprocessed planes will be copied.
14476 By default value 0xf, all planes will be processed.
14479 Set value which will be multiplied with filtered result.
14482 Set value which will be added to filtered result.
14485 @anchor{program_opencl}
14486 @section program_opencl
14488 Filter video using an OpenCL program.
14493 OpenCL program source file.
14496 Kernel name in program.
14499 Number of inputs to the filter. Defaults to 1.
14502 Size of output frames. Defaults to the same as the first input.
14506 The program source file must contain a kernel function with the given name,
14507 which will be run once for each plane of the output. Each run on a plane
14508 gets enqueued as a separate 2D global NDRange with one work-item for each
14509 pixel to be generated. The global ID offset for each work-item is therefore
14510 the coordinates of a pixel in the destination image.
14512 The kernel function needs to take the following arguments:
14515 Destination image, @var{__write_only image2d_t}.
14517 This image will become the output; the kernel should write all of it.
14519 Frame index, @var{unsigned int}.
14521 This is a counter starting from zero and increasing by one for each frame.
14523 Source images, @var{__read_only image2d_t}.
14525 These are the most recent images on each input. The kernel may read from
14526 them to generate the output, but they can't be written to.
14533 Copy the input to the output (output must be the same size as the input).
14535 __kernel void copy(__write_only image2d_t destination,
14536 unsigned int index,
14537 __read_only image2d_t source)
14539 const sampler_t sampler = CLK_NORMALIZED_COORDS_FALSE;
14541 int2 location = (int2)(get_global_id(0), get_global_id(1));
14543 float4 value = read_imagef(source, sampler, location);
14545 write_imagef(destination, location, value);
14550 Apply a simple transformation, rotating the input by an amount increasing
14551 with the index counter. Pixel values are linearly interpolated by the
14552 sampler, and the output need not have the same dimensions as the input.
14554 __kernel void rotate_image(__write_only image2d_t dst,
14555 unsigned int index,
14556 __read_only image2d_t src)
14558 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
14559 CLK_FILTER_LINEAR);
14561 float angle = (float)index / 100.0f;
14563 float2 dst_dim = convert_float2(get_image_dim(dst));
14564 float2 src_dim = convert_float2(get_image_dim(src));
14566 float2 dst_cen = dst_dim / 2.0f;
14567 float2 src_cen = src_dim / 2.0f;
14569 int2 dst_loc = (int2)(get_global_id(0), get_global_id(1));
14571 float2 dst_pos = convert_float2(dst_loc) - dst_cen;
14573 cos(angle) * dst_pos.x - sin(angle) * dst_pos.y,
14574 sin(angle) * dst_pos.x + cos(angle) * dst_pos.y
14576 src_pos = src_pos * src_dim / dst_dim;
14578 float2 src_loc = src_pos + src_cen;
14580 if (src_loc.x < 0.0f || src_loc.y < 0.0f ||
14581 src_loc.x > src_dim.x || src_loc.y > src_dim.y)
14582 write_imagef(dst, dst_loc, 0.5f);
14584 write_imagef(dst, dst_loc, read_imagef(src, sampler, src_loc));
14589 Blend two inputs together, with the amount of each input used varying
14590 with the index counter.
14592 __kernel void blend_images(__write_only image2d_t dst,
14593 unsigned int index,
14594 __read_only image2d_t src1,
14595 __read_only image2d_t src2)
14597 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
14598 CLK_FILTER_LINEAR);
14600 float blend = (cos((float)index / 50.0f) + 1.0f) / 2.0f;
14602 int2 dst_loc = (int2)(get_global_id(0), get_global_id(1));
14603 int2 src1_loc = dst_loc * get_image_dim(src1) / get_image_dim(dst);
14604 int2 src2_loc = dst_loc * get_image_dim(src2) / get_image_dim(dst);
14606 float4 val1 = read_imagef(src1, sampler, src1_loc);
14607 float4 val2 = read_imagef(src2, sampler, src2_loc);
14609 write_imagef(dst, dst_loc, val1 * blend + val2 * (1.0f - blend));
14615 @section pseudocolor
14617 Alter frame colors in video with pseudocolors.
14619 This filter accepts the following options:
14623 set pixel first component expression
14626 set pixel second component expression
14629 set pixel third component expression
14632 set pixel fourth component expression, corresponds to the alpha component
14635 set component to use as base for altering colors
14638 Each of them specifies the expression to use for computing the lookup table for
14639 the corresponding pixel component values.
14641 The expressions can contain the following constants and functions:
14646 The input width and height.
14649 The input value for the pixel component.
14651 @item ymin, umin, vmin, amin
14652 The minimum allowed component value.
14654 @item ymax, umax, vmax, amax
14655 The maximum allowed component value.
14658 All expressions default to "val".
14660 @subsection Examples
14664 Change too high luma values to gradient:
14666 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'"
14672 Obtain the average, maximum and minimum PSNR (Peak Signal to Noise
14673 Ratio) between two input videos.
14675 This filter takes in input two input videos, the first input is
14676 considered the "main" source and is passed unchanged to the
14677 output. The second input is used as a "reference" video for computing
14680 Both video inputs must have the same resolution and pixel format for
14681 this filter to work correctly. Also it assumes that both inputs
14682 have the same number of frames, which are compared one by one.
14684 The obtained average PSNR is printed through the logging system.
14686 The filter stores the accumulated MSE (mean squared error) of each
14687 frame, and at the end of the processing it is averaged across all frames
14688 equally, and the following formula is applied to obtain the PSNR:
14691 PSNR = 10*log10(MAX^2/MSE)
14694 Where MAX is the average of the maximum values of each component of the
14697 The description of the accepted parameters follows.
14700 @item stats_file, f
14701 If specified the filter will use the named file to save the PSNR of
14702 each individual frame. When filename equals "-" the data is sent to
14705 @item stats_version
14706 Specifies which version of the stats file format to use. Details of
14707 each format are written below.
14708 Default value is 1.
14710 @item stats_add_max
14711 Determines whether the max value is output to the stats log.
14712 Default value is 0.
14713 Requires stats_version >= 2. If this is set and stats_version < 2,
14714 the filter will return an error.
14717 This filter also supports the @ref{framesync} options.
14719 The file printed if @var{stats_file} is selected, contains a sequence of
14720 key/value pairs of the form @var{key}:@var{value} for each compared
14723 If a @var{stats_version} greater than 1 is specified, a header line precedes
14724 the list of per-frame-pair stats, with key value pairs following the frame
14725 format with the following parameters:
14728 @item psnr_log_version
14729 The version of the log file format. Will match @var{stats_version}.
14732 A comma separated list of the per-frame-pair parameters included in
14736 A description of each shown per-frame-pair parameter follows:
14740 sequential number of the input frame, starting from 1
14743 Mean Square Error pixel-by-pixel average difference of the compared
14744 frames, averaged over all the image components.
14746 @item mse_y, mse_u, mse_v, mse_r, mse_g, mse_b, mse_a
14747 Mean Square Error pixel-by-pixel average difference of the compared
14748 frames for the component specified by the suffix.
14750 @item psnr_y, psnr_u, psnr_v, psnr_r, psnr_g, psnr_b, psnr_a
14751 Peak Signal to Noise ratio of the compared frames for the component
14752 specified by the suffix.
14754 @item max_avg, max_y, max_u, max_v
14755 Maximum allowed value for each channel, and average over all
14761 movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
14762 [main][ref] psnr="stats_file=stats.log" [out]
14765 On this example the input file being processed is compared with the
14766 reference file @file{ref_movie.mpg}. The PSNR of each individual frame
14767 is stored in @file{stats.log}.
14772 Pulldown reversal (inverse telecine) filter, capable of handling mixed
14773 hard-telecine, 24000/1001 fps progressive, and 30000/1001 fps progressive
14776 The pullup filter is designed to take advantage of future context in making
14777 its decisions. This filter is stateless in the sense that it does not lock
14778 onto a pattern to follow, but it instead looks forward to the following
14779 fields in order to identify matches and rebuild progressive frames.
14781 To produce content with an even framerate, insert the fps filter after
14782 pullup, use @code{fps=24000/1001} if the input frame rate is 29.97fps,
14783 @code{fps=24} for 30fps and the (rare) telecined 25fps input.
14785 The filter accepts the following options:
14792 These options set the amount of "junk" to ignore at the left, right, top, and
14793 bottom of the image, respectively. Left and right are in units of 8 pixels,
14794 while top and bottom are in units of 2 lines.
14795 The default is 8 pixels on each side.
14798 Set the strict breaks. Setting this option to 1 will reduce the chances of
14799 filter generating an occasional mismatched frame, but it may also cause an
14800 excessive number of frames to be dropped during high motion sequences.
14801 Conversely, setting it to -1 will make filter match fields more easily.
14802 This may help processing of video where there is slight blurring between
14803 the fields, but may also cause there to be interlaced frames in the output.
14804 Default value is @code{0}.
14807 Set the metric plane to use. It accepts the following values:
14813 Use chroma blue plane.
14816 Use chroma red plane.
14819 This option may be set to use chroma plane instead of the default luma plane
14820 for doing filter's computations. This may improve accuracy on very clean
14821 source material, but more likely will decrease accuracy, especially if there
14822 is chroma noise (rainbow effect) or any grayscale video.
14823 The main purpose of setting @option{mp} to a chroma plane is to reduce CPU
14824 load and make pullup usable in realtime on slow machines.
14827 For best results (without duplicated frames in the output file) it is
14828 necessary to change the output frame rate. For example, to inverse
14829 telecine NTSC input:
14831 ffmpeg -i input -vf pullup -r 24000/1001 ...
14836 Change video quantization parameters (QP).
14838 The filter accepts the following option:
14842 Set expression for quantization parameter.
14845 The expression is evaluated through the eval API and can contain, among others,
14846 the following constants:
14850 1 if index is not 129, 0 otherwise.
14853 Sequential index starting from -129 to 128.
14856 @subsection Examples
14860 Some equation like:
14868 Flush video frames from internal cache of frames into a random order.
14869 No frame is discarded.
14870 Inspired by @ref{frei0r} nervous filter.
14874 Set size in number of frames of internal cache, in range from @code{2} to
14875 @code{512}. Default is @code{30}.
14878 Set seed for random number generator, must be an integer included between
14879 @code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to
14880 less than @code{0}, the filter will try to use a good random seed on a
14884 @section readeia608
14886 Read closed captioning (EIA-608) information from the top lines of a video frame.
14888 This filter adds frame metadata for @code{lavfi.readeia608.X.cc} and
14889 @code{lavfi.readeia608.X.line}, where @code{X} is the number of the identified line
14890 with EIA-608 data (starting from 0). A description of each metadata value follows:
14893 @item lavfi.readeia608.X.cc
14894 The two bytes stored as EIA-608 data (printed in hexadecimal).
14896 @item lavfi.readeia608.X.line
14897 The number of the line on which the EIA-608 data was identified and read.
14900 This filter accepts the following options:
14904 Set the line to start scanning for EIA-608 data. Default is @code{0}.
14907 Set the line to end scanning for EIA-608 data. Default is @code{29}.
14910 Set minimal acceptable amplitude change for sync codes detection.
14911 Default is @code{0.2}. Allowed range is @code{[0.001 - 1]}.
14914 Set the ratio of width reserved for sync code detection.
14915 Default is @code{0.27}. Allowed range is @code{[0.01 - 0.7]}.
14918 Set the max peaks height difference for sync code detection.
14919 Default is @code{0.1}. Allowed range is @code{[0.0 - 0.5]}.
14922 Set max peaks period difference for sync code detection.
14923 Default is @code{0.1}. Allowed range is @code{[0.0 - 0.5]}.
14926 Set the first two max start code bits differences.
14927 Default is @code{0.02}. Allowed range is @code{[0.0 - 0.5]}.
14930 Set the minimum ratio of bits height compared to 3rd start code bit.
14931 Default is @code{0.75}. Allowed range is @code{[0.01 - 1]}.
14934 Set the white color threshold. Default is @code{0.35}. Allowed range is @code{[0.1 - 1]}.
14937 Set the black color threshold. Default is @code{0.15}. Allowed range is @code{[0.0 - 0.5]}.
14940 Enable checking the parity bit. In the event of a parity error, the filter will output
14941 @code{0x00} for that character. Default is false.
14944 Lowpass lines prior to further processing. Default is disabled.
14947 @subsection Examples
14951 Output a csv with presentation time and the first two lines of identified EIA-608 captioning data.
14953 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
14959 Read vertical interval timecode (VITC) information from the top lines of a
14962 The filter adds frame metadata key @code{lavfi.readvitc.tc_str} with the
14963 timecode value, if a valid timecode has been detected. Further metadata key
14964 @code{lavfi.readvitc.found} is set to 0/1 depending on whether
14965 timecode data has been found or not.
14967 This filter accepts the following options:
14971 Set the maximum number of lines to scan for VITC data. If the value is set to
14972 @code{-1} the full video frame is scanned. Default is @code{45}.
14975 Set the luma threshold for black. Accepts float numbers in the range [0.0,1.0],
14976 default value is @code{0.2}. The value must be equal or less than @code{thr_w}.
14979 Set the luma threshold for white. Accepts float numbers in the range [0.0,1.0],
14980 default value is @code{0.6}. The value must be equal or greater than @code{thr_b}.
14983 @subsection Examples
14987 Detect and draw VITC data onto the video frame; if no valid VITC is detected,
14988 draw @code{--:--:--:--} as a placeholder:
14990 ffmpeg -i input.avi -filter:v 'readvitc,drawtext=fontfile=FreeMono.ttf:text=%@{metadata\\:lavfi.readvitc.tc_str\\:--\\\\\\:--\\\\\\:--\\\\\\:--@}:x=(w-tw)/2:y=400-ascent'
14996 Remap pixels using 2nd: Xmap and 3rd: Ymap input video stream.
14998 Destination pixel at position (X, Y) will be picked from source (x, y) position
14999 where x = Xmap(X, Y) and y = Ymap(X, Y). If mapping values are out of range, zero
15000 value for pixel will be used for destination pixel.
15002 Xmap and Ymap input video streams must be of same dimensions. Output video stream
15003 will have Xmap/Ymap video stream dimensions.
15004 Xmap and Ymap input video streams are 16bit depth, single channel.
15008 Specify pixel format of output from this filter. Can be @code{color} or @code{gray}.
15009 Default is @code{color}.
15012 @section removegrain
15014 The removegrain filter is a spatial denoiser for progressive video.
15018 Set mode for the first plane.
15021 Set mode for the second plane.
15024 Set mode for the third plane.
15027 Set mode for the fourth plane.
15030 Range of mode is from 0 to 24. Description of each mode follows:
15034 Leave input plane unchanged. Default.
15037 Clips the pixel with the minimum and maximum of the 8 neighbour pixels.
15040 Clips the pixel with the second minimum and maximum of the 8 neighbour pixels.
15043 Clips the pixel with the third minimum and maximum of the 8 neighbour pixels.
15046 Clips the pixel with the fourth minimum and maximum of the 8 neighbour pixels.
15047 This is equivalent to a median filter.
15050 Line-sensitive clipping giving the minimal change.
15053 Line-sensitive clipping, intermediate.
15056 Line-sensitive clipping, intermediate.
15059 Line-sensitive clipping, intermediate.
15062 Line-sensitive clipping on a line where the neighbours pixels are the closest.
15065 Replaces the target pixel with the closest neighbour.
15068 [1 2 1] horizontal and vertical kernel blur.
15074 Bob mode, interpolates top field from the line where the neighbours
15075 pixels are the closest.
15078 Bob mode, interpolates bottom field from the line where the neighbours
15079 pixels are the closest.
15082 Bob mode, interpolates top field. Same as 13 but with a more complicated
15083 interpolation formula.
15086 Bob mode, interpolates bottom field. Same as 14 but with a more complicated
15087 interpolation formula.
15090 Clips the pixel with the minimum and maximum of respectively the maximum and
15091 minimum of each pair of opposite neighbour pixels.
15094 Line-sensitive clipping using opposite neighbours whose greatest distance from
15095 the current pixel is minimal.
15098 Replaces the pixel with the average of its 8 neighbours.
15101 Averages the 9 pixels ([1 1 1] horizontal and vertical blur).
15104 Clips pixels using the averages of opposite neighbour.
15107 Same as mode 21 but simpler and faster.
15110 Small edge and halo removal, but reputed useless.
15116 @section removelogo
15118 Suppress a TV station logo, using an image file to determine which
15119 pixels comprise the logo. It works by filling in the pixels that
15120 comprise the logo with neighboring pixels.
15122 The filter accepts the following options:
15126 Set the filter bitmap file, which can be any image format supported by
15127 libavformat. The width and height of the image file must match those of the
15128 video stream being processed.
15131 Pixels in the provided bitmap image with a value of zero are not
15132 considered part of the logo, non-zero pixels are considered part of
15133 the logo. If you use white (255) for the logo and black (0) for the
15134 rest, you will be safe. For making the filter bitmap, it is
15135 recommended to take a screen capture of a black frame with the logo
15136 visible, and then using a threshold filter followed by the erode
15137 filter once or twice.
15139 If needed, little splotches can be fixed manually. Remember that if
15140 logo pixels are not covered, the filter quality will be much
15141 reduced. Marking too many pixels as part of the logo does not hurt as
15142 much, but it will increase the amount of blurring needed to cover over
15143 the image and will destroy more information than necessary, and extra
15144 pixels will slow things down on a large logo.
15146 @section repeatfields
15148 This filter uses the repeat_field flag from the Video ES headers and hard repeats
15149 fields based on its value.
15153 Reverse a video clip.
15155 Warning: This filter requires memory to buffer the entire clip, so trimming
15158 @subsection Examples
15162 Take the first 5 seconds of a clip, and reverse it.
15169 Shift R/G/B/A pixels horizontally and/or vertically.
15171 The filter accepts the following options:
15174 Set amount to shift red horizontally.
15176 Set amount to shift red vertically.
15178 Set amount to shift green horizontally.
15180 Set amount to shift green vertically.
15182 Set amount to shift blue horizontally.
15184 Set amount to shift blue vertically.
15186 Set amount to shift alpha horizontally.
15188 Set amount to shift alpha vertically.
15190 Set edge mode, can be @var{smear}, default, or @var{warp}.
15194 Apply roberts cross operator to input video stream.
15196 The filter accepts the following option:
15200 Set which planes will be processed, unprocessed planes will be copied.
15201 By default value 0xf, all planes will be processed.
15204 Set value which will be multiplied with filtered result.
15207 Set value which will be added to filtered result.
15212 Rotate video by an arbitrary angle expressed in radians.
15214 The filter accepts the following options:
15216 A description of the optional parameters follows.
15219 Set an expression for the angle by which to rotate the input video
15220 clockwise, expressed as a number of radians. A negative value will
15221 result in a counter-clockwise rotation. By default it is set to "0".
15223 This expression is evaluated for each frame.
15226 Set the output width expression, default value is "iw".
15227 This expression is evaluated just once during configuration.
15230 Set the output height expression, default value is "ih".
15231 This expression is evaluated just once during configuration.
15234 Enable bilinear interpolation if set to 1, a value of 0 disables
15235 it. Default value is 1.
15238 Set the color used to fill the output area not covered by the rotated
15239 image. For the general syntax of this option, check the
15240 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
15241 If the special value "none" is selected then no
15242 background is printed (useful for example if the background is never shown).
15244 Default value is "black".
15247 The expressions for the angle and the output size can contain the
15248 following constants and functions:
15252 sequential number of the input frame, starting from 0. It is always NAN
15253 before the first frame is filtered.
15256 time in seconds of the input frame, it is set to 0 when the filter is
15257 configured. It is always NAN before the first frame is filtered.
15261 horizontal and vertical chroma subsample values. For example for the
15262 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
15266 the input video width and height
15270 the output width and height, that is the size of the padded area as
15271 specified by the @var{width} and @var{height} expressions
15275 the minimal width/height required for completely containing the input
15276 video rotated by @var{a} radians.
15278 These are only available when computing the @option{out_w} and
15279 @option{out_h} expressions.
15282 @subsection Examples
15286 Rotate the input by PI/6 radians clockwise:
15292 Rotate the input by PI/6 radians counter-clockwise:
15298 Rotate the input by 45 degrees clockwise:
15304 Apply a constant rotation with period T, starting from an angle of PI/3:
15306 rotate=PI/3+2*PI*t/T
15310 Make the input video rotation oscillating with a period of T
15311 seconds and an amplitude of A radians:
15313 rotate=A*sin(2*PI/T*t)
15317 Rotate the video, output size is chosen so that the whole rotating
15318 input video is always completely contained in the output:
15320 rotate='2*PI*t:ow=hypot(iw,ih):oh=ow'
15324 Rotate the video, reduce the output size so that no background is ever
15327 rotate=2*PI*t:ow='min(iw,ih)/sqrt(2)':oh=ow:c=none
15331 @subsection Commands
15333 The filter supports the following commands:
15337 Set the angle expression.
15338 The command accepts the same syntax of the corresponding option.
15340 If the specified expression is not valid, it is kept at its current
15346 Apply Shape Adaptive Blur.
15348 The filter accepts the following options:
15351 @item luma_radius, lr
15352 Set luma blur filter strength, must be a value in range 0.1-4.0, default
15353 value is 1.0. A greater value will result in a more blurred image, and
15354 in slower processing.
15356 @item luma_pre_filter_radius, lpfr
15357 Set luma pre-filter radius, must be a value in the 0.1-2.0 range, default
15360 @item luma_strength, ls
15361 Set luma maximum difference between pixels to still be considered, must
15362 be a value in the 0.1-100.0 range, default value is 1.0.
15364 @item chroma_radius, cr
15365 Set chroma blur filter strength, must be a value in range -0.9-4.0. A
15366 greater value will result in a more blurred image, and in slower
15369 @item chroma_pre_filter_radius, cpfr
15370 Set chroma pre-filter radius, must be a value in the -0.9-2.0 range.
15372 @item chroma_strength, cs
15373 Set chroma maximum difference between pixels to still be considered,
15374 must be a value in the -0.9-100.0 range.
15377 Each chroma option value, if not explicitly specified, is set to the
15378 corresponding luma option value.
15383 Scale (resize) the input video, using the libswscale library.
15385 The scale filter forces the output display aspect ratio to be the same
15386 of the input, by changing the output sample aspect ratio.
15388 If the input image format is different from the format requested by
15389 the next filter, the scale filter will convert the input to the
15392 @subsection Options
15393 The filter accepts the following options, or any of the options
15394 supported by the libswscale scaler.
15396 See @ref{scaler_options,,the ffmpeg-scaler manual,ffmpeg-scaler} for
15397 the complete list of scaler options.
15402 Set the output video dimension expression. Default value is the input
15405 If the @var{width} or @var{w} value is 0, the input width is used for
15406 the output. If the @var{height} or @var{h} value is 0, the input height
15407 is used for the output.
15409 If one and only one of the values is -n with n >= 1, the scale filter
15410 will use a value that maintains the aspect ratio of the input image,
15411 calculated from the other specified dimension. After that it will,
15412 however, make sure that the calculated dimension is divisible by n and
15413 adjust the value if necessary.
15415 If both values are -n with n >= 1, the behavior will be identical to
15416 both values being set to 0 as previously detailed.
15418 See below for the list of accepted constants for use in the dimension
15422 Specify when to evaluate @var{width} and @var{height} expression. It accepts the following values:
15426 Only evaluate expressions once during the filter initialization or when a command is processed.
15429 Evaluate expressions for each incoming frame.
15433 Default value is @samp{init}.
15437 Set the interlacing mode. It accepts the following values:
15441 Force interlaced aware scaling.
15444 Do not apply interlaced scaling.
15447 Select interlaced aware scaling depending on whether the source frames
15448 are flagged as interlaced or not.
15451 Default value is @samp{0}.
15454 Set libswscale scaling flags. See
15455 @ref{sws_flags,,the ffmpeg-scaler manual,ffmpeg-scaler} for the
15456 complete list of values. If not explicitly specified the filter applies
15460 @item param0, param1
15461 Set libswscale input parameters for scaling algorithms that need them. See
15462 @ref{sws_params,,the ffmpeg-scaler manual,ffmpeg-scaler} for the
15463 complete documentation. If not explicitly specified the filter applies
15469 Set the video size. For the syntax of this option, check the
15470 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
15472 @item in_color_matrix
15473 @item out_color_matrix
15474 Set in/output YCbCr color space type.
15476 This allows the autodetected value to be overridden as well as allows forcing
15477 a specific value used for the output and encoder.
15479 If not specified, the color space type depends on the pixel format.
15485 Choose automatically.
15488 Format conforming to International Telecommunication Union (ITU)
15489 Recommendation BT.709.
15492 Set color space conforming to the United States Federal Communications
15493 Commission (FCC) Code of Federal Regulations (CFR) Title 47 (2003) 73.682 (a).
15498 Set color space conforming to:
15502 ITU Radiocommunication Sector (ITU-R) Recommendation BT.601
15505 ITU-R Rec. BT.470-6 (1998) Systems B, B1, and G
15508 Society of Motion Picture and Television Engineers (SMPTE) ST 170:2004
15513 Set color space conforming to SMPTE ST 240:1999.
15516 Set color space conforming to ITU-R BT.2020 non-constant luminance system.
15521 Set in/output YCbCr sample range.
15523 This allows the autodetected value to be overridden as well as allows forcing
15524 a specific value used for the output and encoder. If not specified, the
15525 range depends on the pixel format. Possible values:
15529 Choose automatically.
15532 Set full range (0-255 in case of 8-bit luma).
15534 @item mpeg/limited/tv
15535 Set "MPEG" range (16-235 in case of 8-bit luma).
15538 @item force_original_aspect_ratio
15539 Enable decreasing or increasing output video width or height if necessary to
15540 keep the original aspect ratio. Possible values:
15544 Scale the video as specified and disable this feature.
15547 The output video dimensions will automatically be decreased if needed.
15550 The output video dimensions will automatically be increased if needed.
15554 One useful instance of this option is that when you know a specific device's
15555 maximum allowed resolution, you can use this to limit the output video to
15556 that, while retaining the aspect ratio. For example, device A allows
15557 1280x720 playback, and your video is 1920x800. Using this option (set it to
15558 decrease) and specifying 1280x720 to the command line makes the output
15561 Please note that this is a different thing than specifying -1 for @option{w}
15562 or @option{h}, you still need to specify the output resolution for this option
15565 @item force_divisible_by Ensures that the output resolution is divisible by the
15566 given integer when used together with @option{force_original_aspect_ratio}. This
15567 works similar to using -n in the @option{w} and @option{h} options.
15569 This option respects the value set for @option{force_original_aspect_ratio},
15570 increasing or decreasing the resolution accordingly. This may slightly modify
15571 the video's aspect ration.
15573 This can be handy, for example, if you want to have a video fit within a defined
15574 resolution using the @option{force_original_aspect_ratio} option but have
15575 encoder restrictions when it comes to width or height.
15579 The values of the @option{w} and @option{h} options are expressions
15580 containing the following constants:
15585 The input width and height
15589 These are the same as @var{in_w} and @var{in_h}.
15593 The output (scaled) width and height
15597 These are the same as @var{out_w} and @var{out_h}
15600 The same as @var{iw} / @var{ih}
15603 input sample aspect ratio
15606 The input display aspect ratio. Calculated from @code{(iw / ih) * sar}.
15610 horizontal and vertical input chroma subsample values. For example for the
15611 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
15615 horizontal and vertical output chroma subsample values. For example for the
15616 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
15619 @subsection Examples
15623 Scale the input video to a size of 200x100
15628 This is equivalent to:
15639 Specify a size abbreviation for the output size:
15644 which can also be written as:
15650 Scale the input to 2x:
15652 scale=w=2*iw:h=2*ih
15656 The above is the same as:
15658 scale=2*in_w:2*in_h
15662 Scale the input to 2x with forced interlaced scaling:
15664 scale=2*iw:2*ih:interl=1
15668 Scale the input to half size:
15670 scale=w=iw/2:h=ih/2
15674 Increase the width, and set the height to the same size:
15680 Seek Greek harmony:
15687 Increase the height, and set the width to 3/2 of the height:
15689 scale=w=3/2*oh:h=3/5*ih
15693 Increase the size, making the size a multiple of the chroma
15696 scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub"
15700 Increase the width to a maximum of 500 pixels,
15701 keeping the same aspect ratio as the input:
15703 scale=w='min(500\, iw*3/2):h=-1'
15707 Make pixels square by combining scale and setsar:
15709 scale='trunc(ih*dar):ih',setsar=1/1
15713 Make pixels square by combining scale and setsar,
15714 making sure the resulting resolution is even (required by some codecs):
15716 scale='trunc(ih*dar/2)*2:trunc(ih/2)*2',setsar=1/1
15720 @subsection Commands
15722 This filter supports the following commands:
15726 Set the output video dimension expression.
15727 The command accepts the same syntax of the corresponding option.
15729 If the specified expression is not valid, it is kept at its current
15735 Use the NVIDIA Performance Primitives (libnpp) to perform scaling and/or pixel
15736 format conversion on CUDA video frames. Setting the output width and height
15737 works in the same way as for the @var{scale} filter.
15739 The following additional options are accepted:
15742 The pixel format of the output CUDA frames. If set to the string "same" (the
15743 default), the input format will be kept. Note that automatic format negotiation
15744 and conversion is not yet supported for hardware frames
15747 The interpolation algorithm used for resizing. One of the following:
15754 @item cubic2p_bspline
15755 2-parameter cubic (B=1, C=0)
15757 @item cubic2p_catmullrom
15758 2-parameter cubic (B=0, C=1/2)
15760 @item cubic2p_b05c03
15761 2-parameter cubic (B=1/2, C=3/10)
15773 Scale (resize) the input video, based on a reference video.
15775 See the scale filter for available options, scale2ref supports the same but
15776 uses the reference video instead of the main input as basis. scale2ref also
15777 supports the following additional constants for the @option{w} and
15778 @option{h} options:
15783 The main input video's width and height
15786 The same as @var{main_w} / @var{main_h}
15789 The main input video's sample aspect ratio
15791 @item main_dar, mdar
15792 The main input video's display aspect ratio. Calculated from
15793 @code{(main_w / main_h) * main_sar}.
15797 The main input video's horizontal and vertical chroma subsample values.
15798 For example for the pixel format "yuv422p" @var{hsub} is 2 and @var{vsub}
15802 @subsection Examples
15806 Scale a subtitle stream (b) to match the main video (a) in size before overlaying
15808 'scale2ref[b][a];[a][b]overlay'
15812 Scale a logo to 1/10th the height of a video, while preserving its display aspect ratio.
15814 [logo-in][video-in]scale2ref=w=oh*mdar:h=ih/10[logo-out][video-out]
15819 Scroll input video horizontally and/or vertically by constant speed.
15821 The filter accepts the following options:
15823 @item horizontal, h
15824 Set the horizontal scrolling speed. Default is 0. Allowed range is from -1 to 1.
15825 Negative values changes scrolling direction.
15828 Set the vertical scrolling speed. Default is 0. Allowed range is from -1 to 1.
15829 Negative values changes scrolling direction.
15832 Set the initial horizontal scrolling position. Default is 0. Allowed range is from 0 to 1.
15835 Set the initial vertical scrolling position. Default is 0. Allowed range is from 0 to 1.
15838 @anchor{selectivecolor}
15839 @section selectivecolor
15841 Adjust cyan, magenta, yellow and black (CMYK) to certain ranges of colors (such
15842 as "reds", "yellows", "greens", "cyans", ...). The adjustment range is defined
15843 by the "purity" of the color (that is, how saturated it already is).
15845 This filter is similar to the Adobe Photoshop Selective Color tool.
15847 The filter accepts the following options:
15850 @item correction_method
15851 Select color correction method.
15853 Available values are:
15856 Specified adjustments are applied "as-is" (added/subtracted to original pixel
15859 Specified adjustments are relative to the original component value.
15861 Default is @code{absolute}.
15863 Adjustments for red pixels (pixels where the red component is the maximum)
15865 Adjustments for yellow pixels (pixels where the blue component is the minimum)
15867 Adjustments for green pixels (pixels where the green component is the maximum)
15869 Adjustments for cyan pixels (pixels where the red component is the minimum)
15871 Adjustments for blue pixels (pixels where the blue component is the maximum)
15873 Adjustments for magenta pixels (pixels where the green component is the minimum)
15875 Adjustments for white pixels (pixels where all components are greater than 128)
15877 Adjustments for all pixels except pure black and pure white
15879 Adjustments for black pixels (pixels where all components are lesser than 128)
15881 Specify a Photoshop selective color file (@code{.asv}) to import the settings from.
15884 All the adjustment settings (@option{reds}, @option{yellows}, ...) accept up to
15885 4 space separated floating point adjustment values in the [-1,1] range,
15886 respectively to adjust the amount of cyan, magenta, yellow and black for the
15887 pixels of its range.
15889 @subsection Examples
15893 Increase cyan by 50% and reduce yellow by 33% in every green areas, and
15894 increase magenta by 27% in blue areas:
15896 selectivecolor=greens=.5 0 -.33 0:blues=0 .27
15900 Use a Photoshop selective color preset:
15902 selectivecolor=psfile=MySelectiveColorPresets/Misty.asv
15906 @anchor{separatefields}
15907 @section separatefields
15909 The @code{separatefields} takes a frame-based video input and splits
15910 each frame into its components fields, producing a new half height clip
15911 with twice the frame rate and twice the frame count.
15913 This filter use field-dominance information in frame to decide which
15914 of each pair of fields to place first in the output.
15915 If it gets it wrong use @ref{setfield} filter before @code{separatefields} filter.
15917 @section setdar, setsar
15919 The @code{setdar} filter sets the Display Aspect Ratio for the filter
15922 This is done by changing the specified Sample (aka Pixel) Aspect
15923 Ratio, according to the following equation:
15925 @var{DAR} = @var{HORIZONTAL_RESOLUTION} / @var{VERTICAL_RESOLUTION} * @var{SAR}
15928 Keep in mind that the @code{setdar} filter does not modify the pixel
15929 dimensions of the video frame. Also, the display aspect ratio set by
15930 this filter may be changed by later filters in the filterchain,
15931 e.g. in case of scaling or if another "setdar" or a "setsar" filter is
15934 The @code{setsar} filter sets the Sample (aka Pixel) Aspect Ratio for
15935 the filter output video.
15937 Note that as a consequence of the application of this filter, the
15938 output display aspect ratio will change according to the equation
15941 Keep in mind that the sample aspect ratio set by the @code{setsar}
15942 filter may be changed by later filters in the filterchain, e.g. if
15943 another "setsar" or a "setdar" filter is applied.
15945 It accepts the following parameters:
15948 @item r, ratio, dar (@code{setdar} only), sar (@code{setsar} only)
15949 Set the aspect ratio used by the filter.
15951 The parameter can be a floating point number string, an expression, or
15952 a string of the form @var{num}:@var{den}, where @var{num} and
15953 @var{den} are the numerator and denominator of the aspect ratio. If
15954 the parameter is not specified, it is assumed the value "0".
15955 In case the form "@var{num}:@var{den}" is used, the @code{:} character
15959 Set the maximum integer value to use for expressing numerator and
15960 denominator when reducing the expressed aspect ratio to a rational.
15961 Default value is @code{100}.
15965 The parameter @var{sar} is an expression containing
15966 the following constants:
15970 These are approximated values for the mathematical constants e
15971 (Euler's number), pi (Greek pi), and phi (the golden ratio).
15974 The input width and height.
15977 These are the same as @var{w} / @var{h}.
15980 The input sample aspect ratio.
15983 The input display aspect ratio. It is the same as
15984 (@var{w} / @var{h}) * @var{sar}.
15987 Horizontal and vertical chroma subsample values. For example, for the
15988 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
15991 @subsection Examples
15996 To change the display aspect ratio to 16:9, specify one of the following:
16003 To change the sample aspect ratio to 10:11, specify:
16009 To set a display aspect ratio of 16:9, and specify a maximum integer value of
16010 1000 in the aspect ratio reduction, use the command:
16012 setdar=ratio=16/9:max=1000
16020 Force field for the output video frame.
16022 The @code{setfield} filter marks the interlace type field for the
16023 output frames. It does not change the input frame, but only sets the
16024 corresponding property, which affects how the frame is treated by
16025 following filters (e.g. @code{fieldorder} or @code{yadif}).
16027 The filter accepts the following options:
16032 Available values are:
16036 Keep the same field property.
16039 Mark the frame as bottom-field-first.
16042 Mark the frame as top-field-first.
16045 Mark the frame as progressive.
16052 Force frame parameter for the output video frame.
16054 The @code{setparams} filter marks interlace and color range for the
16055 output frames. It does not change the input frame, but only sets the
16056 corresponding property, which affects how the frame is treated by
16061 Available values are:
16065 Keep the same field property (default).
16068 Mark the frame as bottom-field-first.
16071 Mark the frame as top-field-first.
16074 Mark the frame as progressive.
16078 Available values are:
16082 Keep the same color range property (default).
16084 @item unspecified, unknown
16085 Mark the frame as unspecified color range.
16087 @item limited, tv, mpeg
16088 Mark the frame as limited range.
16090 @item full, pc, jpeg
16091 Mark the frame as full range.
16094 @item color_primaries
16095 Set the color primaries.
16096 Available values are:
16100 Keep the same color primaries property (default).
16117 Set the color transfer.
16118 Available values are:
16122 Keep the same color trc property (default).
16144 Set the colorspace.
16145 Available values are:
16149 Keep the same colorspace property (default).
16162 @item chroma-derived-nc
16163 @item chroma-derived-c
16170 Show a line containing various information for each input video frame.
16171 The input video is not modified.
16173 This filter supports the following options:
16177 Calculate checksums of each plane. By default enabled.
16180 The shown line contains a sequence of key/value pairs of the form
16181 @var{key}:@var{value}.
16183 The following values are shown in the output:
16187 The (sequential) number of the input frame, starting from 0.
16190 The Presentation TimeStamp of the input frame, expressed as a number of
16191 time base units. The time base unit depends on the filter input pad.
16194 The Presentation TimeStamp of the input frame, expressed as a number of
16198 The position of the frame in the input stream, or -1 if this information is
16199 unavailable and/or meaningless (for example in case of synthetic video).
16202 The pixel format name.
16205 The sample aspect ratio of the input frame, expressed in the form
16206 @var{num}/@var{den}.
16209 The size of the input frame. For the syntax of this option, check the
16210 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
16213 The type of interlaced mode ("P" for "progressive", "T" for top field first, "B"
16214 for bottom field first).
16217 This is 1 if the frame is a key frame, 0 otherwise.
16220 The picture type of the input frame ("I" for an I-frame, "P" for a
16221 P-frame, "B" for a B-frame, or "?" for an unknown type).
16222 Also refer to the documentation of the @code{AVPictureType} enum and of
16223 the @code{av_get_picture_type_char} function defined in
16224 @file{libavutil/avutil.h}.
16227 The Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame.
16229 @item plane_checksum
16230 The Adler-32 checksum (printed in hexadecimal) of each plane of the input frame,
16231 expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3}]".
16234 @section showpalette
16236 Displays the 256 colors palette of each frame. This filter is only relevant for
16237 @var{pal8} pixel format frames.
16239 It accepts the following option:
16243 Set the size of the box used to represent one palette color entry. Default is
16244 @code{30} (for a @code{30x30} pixel box).
16247 @section shuffleframes
16249 Reorder and/or duplicate and/or drop video frames.
16251 It accepts the following parameters:
16255 Set the destination indexes of input frames.
16256 This is space or '|' separated list of indexes that maps input frames to output
16257 frames. Number of indexes also sets maximal value that each index may have.
16258 '-1' index have special meaning and that is to drop frame.
16261 The first frame has the index 0. The default is to keep the input unchanged.
16263 @subsection Examples
16267 Swap second and third frame of every three frames of the input:
16269 ffmpeg -i INPUT -vf "shuffleframes=0 2 1" OUTPUT
16273 Swap 10th and 1st frame of every ten frames of the input:
16275 ffmpeg -i INPUT -vf "shuffleframes=9 1 2 3 4 5 6 7 8 0" OUTPUT
16279 @section shuffleplanes
16281 Reorder and/or duplicate video planes.
16283 It accepts the following parameters:
16288 The index of the input plane to be used as the first output plane.
16291 The index of the input plane to be used as the second output plane.
16294 The index of the input plane to be used as the third output plane.
16297 The index of the input plane to be used as the fourth output plane.
16301 The first plane has the index 0. The default is to keep the input unchanged.
16303 @subsection Examples
16307 Swap the second and third planes of the input:
16309 ffmpeg -i INPUT -vf shuffleplanes=0:2:1:3 OUTPUT
16313 @anchor{signalstats}
16314 @section signalstats
16315 Evaluate various visual metrics that assist in determining issues associated
16316 with the digitization of analog video media.
16318 By default the filter will log these metadata values:
16322 Display the minimal Y value contained within the input frame. Expressed in
16326 Display the Y value at the 10% percentile within the input frame. Expressed in
16330 Display the average Y value within the input frame. Expressed in range of
16334 Display the Y value at the 90% percentile within the input frame. Expressed in
16338 Display the maximum Y value contained within the input frame. Expressed in
16342 Display the minimal U value contained within the input frame. Expressed in
16346 Display the U value at the 10% percentile within the input frame. Expressed in
16350 Display the average U value within the input frame. Expressed in range of
16354 Display the U value at the 90% percentile within the input frame. Expressed in
16358 Display the maximum U value contained within the input frame. Expressed in
16362 Display the minimal V value contained within the input frame. Expressed in
16366 Display the V value at the 10% percentile within the input frame. Expressed in
16370 Display the average V value within the input frame. Expressed in range of
16374 Display the V value at the 90% percentile within the input frame. Expressed in
16378 Display the maximum V value contained within the input frame. Expressed in
16382 Display the minimal saturation value contained within the input frame.
16383 Expressed in range of [0-~181.02].
16386 Display the saturation value at the 10% percentile within the input frame.
16387 Expressed in range of [0-~181.02].
16390 Display the average saturation value within the input frame. Expressed in range
16394 Display the saturation value at the 90% percentile within the input frame.
16395 Expressed in range of [0-~181.02].
16398 Display the maximum saturation value contained within the input frame.
16399 Expressed in range of [0-~181.02].
16402 Display the median value for hue within the input frame. Expressed in range of
16406 Display the average value for hue within the input frame. Expressed in range of
16410 Display the average of sample value difference between all values of the Y
16411 plane in the current frame and corresponding values of the previous input frame.
16412 Expressed in range of [0-255].
16415 Display the average of sample value difference between all values of the U
16416 plane in the current frame and corresponding values of the previous input frame.
16417 Expressed in range of [0-255].
16420 Display the average of sample value difference between all values of the V
16421 plane in the current frame and corresponding values of the previous input frame.
16422 Expressed in range of [0-255].
16425 Display bit depth of Y plane in current frame.
16426 Expressed in range of [0-16].
16429 Display bit depth of U plane in current frame.
16430 Expressed in range of [0-16].
16433 Display bit depth of V plane in current frame.
16434 Expressed in range of [0-16].
16437 The filter accepts the following options:
16443 @option{stat} specify an additional form of image analysis.
16444 @option{out} output video with the specified type of pixel highlighted.
16446 Both options accept the following values:
16450 Identify @var{temporal outliers} pixels. A @var{temporal outlier} is a pixel
16451 unlike the neighboring pixels of the same field. Examples of temporal outliers
16452 include the results of video dropouts, head clogs, or tape tracking issues.
16455 Identify @var{vertical line repetition}. Vertical line repetition includes
16456 similar rows of pixels within a frame. In born-digital video vertical line
16457 repetition is common, but this pattern is uncommon in video digitized from an
16458 analog source. When it occurs in video that results from the digitization of an
16459 analog source it can indicate concealment from a dropout compensator.
16462 Identify pixels that fall outside of legal broadcast range.
16466 Set the highlight color for the @option{out} option. The default color is
16470 @subsection Examples
16474 Output data of various video metrics:
16476 ffprobe -f lavfi movie=example.mov,signalstats="stat=tout+vrep+brng" -show_frames
16480 Output specific data about the minimum and maximum values of the Y plane per frame:
16482 ffprobe -f lavfi movie=example.mov,signalstats -show_entries frame_tags=lavfi.signalstats.YMAX,lavfi.signalstats.YMIN
16486 Playback video while highlighting pixels that are outside of broadcast range in red.
16488 ffplay example.mov -vf signalstats="out=brng:color=red"
16492 Playback video with signalstats metadata drawn over the frame.
16494 ffplay example.mov -vf signalstats=stat=brng+vrep+tout,drawtext=fontfile=FreeSerif.ttf:textfile=signalstat_drawtext.txt
16497 The contents of signalstat_drawtext.txt used in the command are:
16500 Y (%@{metadata:lavfi.signalstats.YMIN@}-%@{metadata:lavfi.signalstats.YMAX@})
16501 U (%@{metadata:lavfi.signalstats.UMIN@}-%@{metadata:lavfi.signalstats.UMAX@})
16502 V (%@{metadata:lavfi.signalstats.VMIN@}-%@{metadata:lavfi.signalstats.VMAX@})
16503 saturation maximum: %@{metadata:lavfi.signalstats.SATMAX@}
16511 Calculates the MPEG-7 Video Signature. The filter can handle more than one
16512 input. In this case the matching between the inputs can be calculated additionally.
16513 The filter always passes through the first input. The signature of each stream can
16514 be written into a file.
16516 It accepts the following options:
16520 Enable or disable the matching process.
16522 Available values are:
16526 Disable the calculation of a matching (default).
16528 Calculate the matching for the whole video and output whether the whole video
16529 matches or only parts.
16531 Calculate only until a matching is found or the video ends. Should be faster in
16536 Set the number of inputs. The option value must be a non negative integer.
16537 Default value is 1.
16540 Set the path to which the output is written. If there is more than one input,
16541 the path must be a prototype, i.e. must contain %d or %0nd (where n is a positive
16542 integer), that will be replaced with the input number. If no filename is
16543 specified, no output will be written. This is the default.
16546 Choose the output format.
16548 Available values are:
16552 Use the specified binary representation (default).
16554 Use the specified xml representation.
16558 Set threshold to detect one word as similar. The option value must be an integer
16559 greater than zero. The default value is 9000.
16562 Set threshold to detect all words as similar. The option value must be an integer
16563 greater than zero. The default value is 60000.
16566 Set threshold to detect frames as similar. The option value must be an integer
16567 greater than zero. The default value is 116.
16570 Set the minimum length of a sequence in frames to recognize it as matching
16571 sequence. The option value must be a non negative integer value.
16572 The default value is 0.
16575 Set the minimum relation, that matching frames to all frames must have.
16576 The option value must be a double value between 0 and 1. The default value is 0.5.
16579 @subsection Examples
16583 To calculate the signature of an input video and store it in signature.bin:
16585 ffmpeg -i input.mkv -vf signature=filename=signature.bin -map 0:v -f null -
16589 To detect whether two videos match and store the signatures in XML format in
16590 signature0.xml and signature1.xml:
16592 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 -
16600 Blur the input video without impacting the outlines.
16602 It accepts the following options:
16605 @item luma_radius, lr
16606 Set the luma radius. The option value must be a float number in
16607 the range [0.1,5.0] that specifies the variance of the gaussian filter
16608 used to blur the image (slower if larger). Default value is 1.0.
16610 @item luma_strength, ls
16611 Set the luma strength. The option value must be a float number
16612 in the range [-1.0,1.0] that configures the blurring. A value included
16613 in [0.0,1.0] will blur the image whereas a value included in
16614 [-1.0,0.0] will sharpen the image. Default value is 1.0.
16616 @item luma_threshold, lt
16617 Set the luma threshold used as a coefficient to determine
16618 whether a pixel should be blurred or not. The option value must be an
16619 integer in the range [-30,30]. A value of 0 will filter all the image,
16620 a value included in [0,30] will filter flat areas and a value included
16621 in [-30,0] will filter edges. Default value is 0.
16623 @item chroma_radius, cr
16624 Set the chroma radius. The option value must be a float number in
16625 the range [0.1,5.0] that specifies the variance of the gaussian filter
16626 used to blur the image (slower if larger). Default value is @option{luma_radius}.
16628 @item chroma_strength, cs
16629 Set the chroma strength. The option value must be a float number
16630 in the range [-1.0,1.0] that configures the blurring. A value included
16631 in [0.0,1.0] will blur the image whereas a value included in
16632 [-1.0,0.0] will sharpen the image. Default value is @option{luma_strength}.
16634 @item chroma_threshold, ct
16635 Set the chroma threshold used as a coefficient to determine
16636 whether a pixel should be blurred or not. The option value must be an
16637 integer in the range [-30,30]. A value of 0 will filter all the image,
16638 a value included in [0,30] will filter flat areas and a value included
16639 in [-30,0] will filter edges. Default value is @option{luma_threshold}.
16642 If a chroma option is not explicitly set, the corresponding luma value
16646 Apply sobel operator to input video stream.
16648 The filter accepts the following option:
16652 Set which planes will be processed, unprocessed planes will be copied.
16653 By default value 0xf, all planes will be processed.
16656 Set value which will be multiplied with filtered result.
16659 Set value which will be added to filtered result.
16665 Apply a simple postprocessing filter that compresses and decompresses the image
16666 at several (or - in the case of @option{quality} level @code{6} - all) shifts
16667 and average the results.
16669 The filter accepts the following options:
16673 Set quality. This option defines the number of levels for averaging. It accepts
16674 an integer in the range 0-6. If set to @code{0}, the filter will have no
16675 effect. A value of @code{6} means the higher quality. For each increment of
16676 that value the speed drops by a factor of approximately 2. Default value is
16680 Force a constant quantization parameter. If not set, the filter will use the QP
16681 from the video stream (if available).
16684 Set thresholding mode. Available modes are:
16688 Set hard thresholding (default).
16690 Set soft thresholding (better de-ringing effect, but likely blurrier).
16693 @item use_bframe_qp
16694 Enable the use of the QP from the B-Frames if set to @code{1}. Using this
16695 option may cause flicker since the B-Frames have often larger QP. Default is
16696 @code{0} (not enabled).
16701 Scale the input by applying one of the super-resolution methods based on
16702 convolutional neural networks. Supported models:
16706 Super-Resolution Convolutional Neural Network model (SRCNN).
16707 See @url{https://arxiv.org/abs/1501.00092}.
16710 Efficient Sub-Pixel Convolutional Neural Network model (ESPCN).
16711 See @url{https://arxiv.org/abs/1609.05158}.
16714 Training scripts as well as scripts for model file (.pb) saving can be found at
16715 @url{https://github.com/XueweiMeng/sr/tree/sr_dnn_native}. Original repository
16716 is at @url{https://github.com/HighVoltageRocknRoll/sr.git}.
16718 Native model files (.model) can be generated from TensorFlow model
16719 files (.pb) by using tools/python/convert.py
16721 The filter accepts the following options:
16725 Specify which DNN backend to use for model loading and execution. This option accepts
16726 the following values:
16730 Native implementation of DNN loading and execution.
16733 TensorFlow backend. To enable this backend you
16734 need to install the TensorFlow for C library (see
16735 @url{https://www.tensorflow.org/install/install_c}) and configure FFmpeg with
16736 @code{--enable-libtensorflow}
16739 Default value is @samp{native}.
16742 Set path to model file specifying network architecture and its parameters.
16743 Note that different backends use different file formats. TensorFlow backend
16744 can load files for both formats, while native backend can load files for only
16748 Set scale factor for SRCNN model. Allowed values are @code{2}, @code{3} and @code{4}.
16749 Default value is @code{2}. Scale factor is necessary for SRCNN model, because it accepts
16750 input upscaled using bicubic upscaling with proper scale factor.
16755 Obtain the SSIM (Structural SImilarity Metric) between two input videos.
16757 This filter takes in input two input videos, the first input is
16758 considered the "main" source and is passed unchanged to the
16759 output. The second input is used as a "reference" video for computing
16762 Both video inputs must have the same resolution and pixel format for
16763 this filter to work correctly. Also it assumes that both inputs
16764 have the same number of frames, which are compared one by one.
16766 The filter stores the calculated SSIM of each frame.
16768 The description of the accepted parameters follows.
16771 @item stats_file, f
16772 If specified the filter will use the named file to save the SSIM of
16773 each individual frame. When filename equals "-" the data is sent to
16777 The file printed if @var{stats_file} is selected, contains a sequence of
16778 key/value pairs of the form @var{key}:@var{value} for each compared
16781 A description of each shown parameter follows:
16785 sequential number of the input frame, starting from 1
16787 @item Y, U, V, R, G, B
16788 SSIM of the compared frames for the component specified by the suffix.
16791 SSIM of the compared frames for the whole frame.
16794 Same as above but in dB representation.
16797 This filter also supports the @ref{framesync} options.
16801 movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
16802 [main][ref] ssim="stats_file=stats.log" [out]
16805 On this example the input file being processed is compared with the
16806 reference file @file{ref_movie.mpg}. The SSIM of each individual frame
16807 is stored in @file{stats.log}.
16809 Another example with both psnr and ssim at same time:
16811 ffmpeg -i main.mpg -i ref.mpg -lavfi "ssim;[0:v][1:v]psnr" -f null -
16816 Convert between different stereoscopic image formats.
16818 The filters accept the following options:
16822 Set stereoscopic image format of input.
16824 Available values for input image formats are:
16827 side by side parallel (left eye left, right eye right)
16830 side by side crosseye (right eye left, left eye right)
16833 side by side parallel with half width resolution
16834 (left eye left, right eye right)
16837 side by side crosseye with half width resolution
16838 (right eye left, left eye right)
16842 above-below (left eye above, right eye below)
16846 above-below (right eye above, left eye below)
16850 above-below with half height resolution
16851 (left eye above, right eye below)
16855 above-below with half height resolution
16856 (right eye above, left eye below)
16859 alternating frames (left eye first, right eye second)
16862 alternating frames (right eye first, left eye second)
16865 interleaved rows (left eye has top row, right eye starts on next row)
16868 interleaved rows (right eye has top row, left eye starts on next row)
16871 interleaved columns, left eye first
16874 interleaved columns, right eye first
16876 Default value is @samp{sbsl}.
16880 Set stereoscopic image format of output.
16884 side by side parallel (left eye left, right eye right)
16887 side by side crosseye (right eye left, left eye right)
16890 side by side parallel with half width resolution
16891 (left eye left, right eye right)
16894 side by side crosseye with half width resolution
16895 (right eye left, left eye right)
16899 above-below (left eye above, right eye below)
16903 above-below (right eye above, left eye below)
16907 above-below with half height resolution
16908 (left eye above, right eye below)
16912 above-below with half height resolution
16913 (right eye above, left eye below)
16916 alternating frames (left eye first, right eye second)
16919 alternating frames (right eye first, left eye second)
16922 interleaved rows (left eye has top row, right eye starts on next row)
16925 interleaved rows (right eye has top row, left eye starts on next row)
16928 anaglyph red/blue gray
16929 (red filter on left eye, blue filter on right eye)
16932 anaglyph red/green gray
16933 (red filter on left eye, green filter on right eye)
16936 anaglyph red/cyan gray
16937 (red filter on left eye, cyan filter on right eye)
16940 anaglyph red/cyan half colored
16941 (red filter on left eye, cyan filter on right eye)
16944 anaglyph red/cyan color
16945 (red filter on left eye, cyan filter on right eye)
16948 anaglyph red/cyan color optimized with the least squares projection of dubois
16949 (red filter on left eye, cyan filter on right eye)
16952 anaglyph green/magenta gray
16953 (green filter on left eye, magenta filter on right eye)
16956 anaglyph green/magenta half colored
16957 (green filter on left eye, magenta filter on right eye)
16960 anaglyph green/magenta colored
16961 (green filter on left eye, magenta filter on right eye)
16964 anaglyph green/magenta color optimized with the least squares projection of dubois
16965 (green filter on left eye, magenta filter on right eye)
16968 anaglyph yellow/blue gray
16969 (yellow filter on left eye, blue filter on right eye)
16972 anaglyph yellow/blue half colored
16973 (yellow filter on left eye, blue filter on right eye)
16976 anaglyph yellow/blue colored
16977 (yellow filter on left eye, blue filter on right eye)
16980 anaglyph yellow/blue color optimized with the least squares projection of dubois
16981 (yellow filter on left eye, blue filter on right eye)
16984 mono output (left eye only)
16987 mono output (right eye only)
16990 checkerboard, left eye first
16993 checkerboard, right eye first
16996 interleaved columns, left eye first
16999 interleaved columns, right eye first
17005 Default value is @samp{arcd}.
17008 @subsection Examples
17012 Convert input video from side by side parallel to anaglyph yellow/blue dubois:
17018 Convert input video from above below (left eye above, right eye below) to side by side crosseye.
17024 @section streamselect, astreamselect
17025 Select video or audio streams.
17027 The filter accepts the following options:
17031 Set number of inputs. Default is 2.
17034 Set input indexes to remap to outputs.
17037 @subsection Commands
17039 The @code{streamselect} and @code{astreamselect} filter supports the following
17044 Set input indexes to remap to outputs.
17047 @subsection Examples
17051 Select first 5 seconds 1st stream and rest of time 2nd stream:
17053 sendcmd='5.0 streamselect map 1',streamselect=inputs=2:map=0
17057 Same as above, but for audio:
17059 asendcmd='5.0 astreamselect map 1',astreamselect=inputs=2:map=0
17066 Draw subtitles on top of input video using the libass library.
17068 To enable compilation of this filter you need to configure FFmpeg with
17069 @code{--enable-libass}. This filter also requires a build with libavcodec and
17070 libavformat to convert the passed subtitles file to ASS (Advanced Substation
17071 Alpha) subtitles format.
17073 The filter accepts the following options:
17077 Set the filename of the subtitle file to read. It must be specified.
17079 @item original_size
17080 Specify the size of the original video, the video for which the ASS file
17081 was composed. For the syntax of this option, check the
17082 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
17083 Due to a misdesign in ASS aspect ratio arithmetic, this is necessary to
17084 correctly scale the fonts if the aspect ratio has been changed.
17087 Set a directory path containing fonts that can be used by the filter.
17088 These fonts will be used in addition to whatever the font provider uses.
17091 Process alpha channel, by default alpha channel is untouched.
17094 Set subtitles input character encoding. @code{subtitles} filter only. Only
17095 useful if not UTF-8.
17097 @item stream_index, si
17098 Set subtitles stream index. @code{subtitles} filter only.
17101 Override default style or script info parameters of the subtitles. It accepts a
17102 string containing ASS style format @code{KEY=VALUE} couples separated by ",".
17105 If the first key is not specified, it is assumed that the first value
17106 specifies the @option{filename}.
17108 For example, to render the file @file{sub.srt} on top of the input
17109 video, use the command:
17114 which is equivalent to:
17116 subtitles=filename=sub.srt
17119 To render the default subtitles stream from file @file{video.mkv}, use:
17121 subtitles=video.mkv
17124 To render the second subtitles stream from that file, use:
17126 subtitles=video.mkv:si=1
17129 To make the subtitles stream from @file{sub.srt} appear in 80% transparent blue
17130 @code{DejaVu Serif}, use:
17132 subtitles=sub.srt:force_style='FontName=DejaVu Serif,PrimaryColour=&HCCFF0000'
17135 @section super2xsai
17137 Scale the input by 2x and smooth using the Super2xSaI (Scale and
17138 Interpolate) pixel art scaling algorithm.
17140 Useful for enlarging pixel art images without reducing sharpness.
17144 Swap two rectangular objects in video.
17146 This filter accepts the following options:
17156 Set 1st rect x coordinate.
17159 Set 1st rect y coordinate.
17162 Set 2nd rect x coordinate.
17165 Set 2nd rect y coordinate.
17167 All expressions are evaluated once for each frame.
17170 The all options are expressions containing the following constants:
17175 The input width and height.
17178 same as @var{w} / @var{h}
17181 input sample aspect ratio
17184 input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
17187 The number of the input frame, starting from 0.
17190 The timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
17193 the position in the file of the input frame, NAN if unknown
17201 Apply telecine process to the video.
17203 This filter accepts the following options:
17212 The default value is @code{top}.
17216 A string of numbers representing the pulldown pattern you wish to apply.
17217 The default value is @code{23}.
17221 Some typical patterns:
17226 24p: 2332 (preferred)
17233 24p: 222222222223 ("Euro pulldown")
17240 Apply threshold effect to video stream.
17242 This filter needs four video streams to perform thresholding.
17243 First stream is stream we are filtering.
17244 Second stream is holding threshold values, third stream is holding min values,
17245 and last, fourth stream is holding max values.
17247 The filter accepts the following option:
17251 Set which planes will be processed, unprocessed planes will be copied.
17252 By default value 0xf, all planes will be processed.
17255 For example if first stream pixel's component value is less then threshold value
17256 of pixel component from 2nd threshold stream, third stream value will picked,
17257 otherwise fourth stream pixel component value will be picked.
17259 Using color source filter one can perform various types of thresholding:
17261 @subsection Examples
17265 Binary threshold, using gray color as threshold:
17267 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=black -f lavfi -i color=white -lavfi threshold output.avi
17271 Inverted binary threshold, using gray color as threshold:
17273 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -f lavfi -i color=black -lavfi threshold output.avi
17277 Truncate binary threshold, using gray color as threshold:
17279 ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=gray -lavfi threshold output.avi
17283 Threshold to zero, using gray color as threshold:
17285 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -i 320x240.avi -lavfi threshold output.avi
17289 Inverted threshold to zero, using gray color as threshold:
17291 ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=white -lavfi threshold output.avi
17296 Select the most representative frame in a given sequence of consecutive frames.
17298 The filter accepts the following options:
17302 Set the frames batch size to analyze; in a set of @var{n} frames, the filter
17303 will pick one of them, and then handle the next batch of @var{n} frames until
17304 the end. Default is @code{100}.
17307 Since the filter keeps track of the whole frames sequence, a bigger @var{n}
17308 value will result in a higher memory usage, so a high value is not recommended.
17310 @subsection Examples
17314 Extract one picture each 50 frames:
17320 Complete example of a thumbnail creation with @command{ffmpeg}:
17322 ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png
17328 Tile several successive frames together.
17330 The filter accepts the following options:
17335 Set the grid size (i.e. the number of lines and columns). For the syntax of
17336 this option, check the
17337 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
17340 Set the maximum number of frames to render in the given area. It must be less
17341 than or equal to @var{w}x@var{h}. The default value is @code{0}, meaning all
17342 the area will be used.
17345 Set the outer border margin in pixels.
17348 Set the inner border thickness (i.e. the number of pixels between frames). For
17349 more advanced padding options (such as having different values for the edges),
17350 refer to the pad video filter.
17353 Specify the color of the unused area. For the syntax of this option, check the
17354 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
17355 The default value of @var{color} is "black".
17358 Set the number of frames to overlap when tiling several successive frames together.
17359 The value must be between @code{0} and @var{nb_frames - 1}.
17362 Set the number of frames to initially be empty before displaying first output frame.
17363 This controls how soon will one get first output frame.
17364 The value must be between @code{0} and @var{nb_frames - 1}.
17367 @subsection Examples
17371 Produce 8x8 PNG tiles of all keyframes (@option{-skip_frame nokey}) in a movie:
17373 ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -vsync 0 keyframes%03d.png
17375 The @option{-vsync 0} is necessary to prevent @command{ffmpeg} from
17376 duplicating each output frame to accommodate the originally detected frame
17380 Display @code{5} pictures in an area of @code{3x2} frames,
17381 with @code{7} pixels between them, and @code{2} pixels of initial margin, using
17382 mixed flat and named options:
17384 tile=3x2:nb_frames=5:padding=7:margin=2
17388 @section tinterlace
17390 Perform various types of temporal field interlacing.
17392 Frames are counted starting from 1, so the first input frame is
17395 The filter accepts the following options:
17400 Specify the mode of the interlacing. This option can also be specified
17401 as a value alone. See below for a list of values for this option.
17403 Available values are:
17407 Move odd frames into the upper field, even into the lower field,
17408 generating a double height frame at half frame rate.
17412 Frame 1 Frame 2 Frame 3 Frame 4
17414 11111 22222 33333 44444
17415 11111 22222 33333 44444
17416 11111 22222 33333 44444
17417 11111 22222 33333 44444
17431 Only output odd frames, even frames are dropped, generating a frame with
17432 unchanged height at half frame rate.
17437 Frame 1 Frame 2 Frame 3 Frame 4
17439 11111 22222 33333 44444
17440 11111 22222 33333 44444
17441 11111 22222 33333 44444
17442 11111 22222 33333 44444
17452 Only output even frames, odd frames are dropped, generating a frame with
17453 unchanged height at half frame rate.
17458 Frame 1 Frame 2 Frame 3 Frame 4
17460 11111 22222 33333 44444
17461 11111 22222 33333 44444
17462 11111 22222 33333 44444
17463 11111 22222 33333 44444
17473 Expand each frame to full height, but pad alternate lines with black,
17474 generating a frame with double height at the same input frame rate.
17479 Frame 1 Frame 2 Frame 3 Frame 4
17481 11111 22222 33333 44444
17482 11111 22222 33333 44444
17483 11111 22222 33333 44444
17484 11111 22222 33333 44444
17487 11111 ..... 33333 .....
17488 ..... 22222 ..... 44444
17489 11111 ..... 33333 .....
17490 ..... 22222 ..... 44444
17491 11111 ..... 33333 .....
17492 ..... 22222 ..... 44444
17493 11111 ..... 33333 .....
17494 ..... 22222 ..... 44444
17498 @item interleave_top, 4
17499 Interleave the upper field from odd frames with the lower field from
17500 even frames, generating a frame with unchanged height at half 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<-
17520 @item interleave_bottom, 5
17521 Interleave the lower field from odd frames with the upper field from
17522 even frames, generating a frame with unchanged height at half frame rate.
17527 Frame 1 Frame 2 Frame 3 Frame 4
17529 11111 22222<- 33333 44444<-
17530 11111<- 22222 33333<- 44444
17531 11111 22222<- 33333 44444<-
17532 11111<- 22222 33333<- 44444
17542 @item interlacex2, 6
17543 Double frame rate with unchanged height. Frames are inserted each
17544 containing the second temporal field from the previous input frame and
17545 the first temporal field from the next input frame. This mode relies on
17546 the top_field_first flag. Useful for interlaced video displays with no
17547 field synchronisation.
17552 Frame 1 Frame 2 Frame 3 Frame 4
17554 11111 22222 33333 44444
17555 11111 22222 33333 44444
17556 11111 22222 33333 44444
17557 11111 22222 33333 44444
17560 11111 22222 22222 33333 33333 44444 44444
17561 11111 11111 22222 22222 33333 33333 44444
17562 11111 22222 22222 33333 33333 44444 44444
17563 11111 11111 22222 22222 33333 33333 44444
17568 Move odd frames into the upper field, even into the lower field,
17569 generating a double height frame at same frame rate.
17574 Frame 1 Frame 2 Frame 3 Frame 4
17576 11111 22222 33333 44444
17577 11111 22222 33333 44444
17578 11111 22222 33333 44444
17579 11111 22222 33333 44444
17582 11111 33333 33333 55555
17583 22222 22222 44444 44444
17584 11111 33333 33333 55555
17585 22222 22222 44444 44444
17586 11111 33333 33333 55555
17587 22222 22222 44444 44444
17588 11111 33333 33333 55555
17589 22222 22222 44444 44444
17594 Numeric values are deprecated but are accepted for backward
17595 compatibility reasons.
17597 Default mode is @code{merge}.
17600 Specify flags influencing the filter process.
17602 Available value for @var{flags} is:
17605 @item low_pass_filter, vlpf
17606 Enable linear vertical low-pass filtering in the filter.
17607 Vertical low-pass filtering is required when creating an interlaced
17608 destination from a progressive source which contains high-frequency
17609 vertical detail. Filtering will reduce interlace 'twitter' and Moire
17612 @item complex_filter, cvlpf
17613 Enable complex vertical low-pass filtering.
17614 This will slightly less reduce interlace 'twitter' and Moire
17615 patterning but better retain detail and subjective sharpness impression.
17619 Vertical low-pass filtering can only be enabled for @option{mode}
17620 @var{interleave_top} and @var{interleave_bottom}.
17626 Mix successive video frames.
17628 A description of the accepted options follows.
17632 The number of successive frames to mix. If unspecified, it defaults to 3.
17635 Specify weight of each input video frame.
17636 Each weight is separated by space. If number of weights is smaller than
17637 number of @var{frames} last specified weight will be used for all remaining
17641 Specify scale, if it is set it will be multiplied with sum
17642 of each weight multiplied with pixel values to give final destination
17643 pixel value. By default @var{scale} is auto scaled to sum of weights.
17646 @subsection Examples
17650 Average 7 successive frames:
17652 tmix=frames=7:weights="1 1 1 1 1 1 1"
17656 Apply simple temporal convolution:
17658 tmix=frames=3:weights="-1 3 -1"
17662 Similar as above but only showing temporal differences:
17664 tmix=frames=3:weights="-1 2 -1":scale=1
17670 Tone map colors from different dynamic ranges.
17672 This filter expects data in single precision floating point, as it needs to
17673 operate on (and can output) out-of-range values. Another filter, such as
17674 @ref{zscale}, is needed to convert the resulting frame to a usable format.
17676 The tonemapping algorithms implemented only work on linear light, so input
17677 data should be linearized beforehand (and possibly correctly tagged).
17680 ffmpeg -i INPUT -vf zscale=transfer=linear,tonemap=clip,zscale=transfer=bt709,format=yuv420p OUTPUT
17683 @subsection Options
17684 The filter accepts the following options.
17688 Set the tone map algorithm to use.
17690 Possible values are:
17693 Do not apply any tone map, only desaturate overbright pixels.
17696 Hard-clip any out-of-range values. Use it for perfect color accuracy for
17697 in-range values, while distorting out-of-range values.
17700 Stretch the entire reference gamut to a linear multiple of the display.
17703 Fit a logarithmic transfer between the tone curves.
17706 Preserve overall image brightness with a simple curve, using nonlinear
17707 contrast, which results in flattening details and degrading color accuracy.
17710 Preserve both dark and bright details better than @var{reinhard}, at the cost
17711 of slightly darkening everything. Use it when detail preservation is more
17712 important than color and brightness accuracy.
17715 Smoothly map out-of-range values, while retaining contrast and colors for
17716 in-range material as much as possible. Use it when color accuracy is more
17717 important than detail preservation.
17723 Tune the tone mapping algorithm.
17725 This affects the following algorithms:
17731 Specifies the scale factor to use while stretching.
17735 Specifies the exponent of the function.
17739 Specify an extra linear coefficient to multiply into the signal before clipping.
17743 Specify the local contrast coefficient at the display peak.
17744 Default to 0.5, which means that in-gamut values will be about half as bright
17751 Specify the transition point from linear to mobius transform. Every value
17752 below this point is guaranteed to be mapped 1:1. The higher the value, the
17753 more accurate the result will be, at the cost of losing bright details.
17754 Default to 0.3, which due to the steep initial slope still preserves in-range
17755 colors fairly accurately.
17759 Apply desaturation for highlights that exceed this level of brightness. The
17760 higher the parameter, the more color information will be preserved. This
17761 setting helps prevent unnaturally blown-out colors for super-highlights, by
17762 (smoothly) turning into white instead. This makes images feel more natural,
17763 at the cost of reducing information about out-of-range colors.
17765 The default of 2.0 is somewhat conservative and will mostly just apply to
17766 skies or directly sunlit surfaces. A setting of 0.0 disables this option.
17768 This option works only if the input frame has a supported color tag.
17771 Override signal/nominal/reference peak with this value. Useful when the
17772 embedded peak information in display metadata is not reliable or when tone
17773 mapping from a lower range to a higher range.
17778 Temporarily pad video frames.
17780 The filter accepts the following options:
17784 Specify number of delay frames before input video stream.
17787 Specify number of padding frames after input video stream.
17788 Set to -1 to pad indefinitely.
17791 Set kind of frames added to beginning of stream.
17792 Can be either @var{add} or @var{clone}.
17793 With @var{add} frames of solid-color are added.
17794 With @var{clone} frames are clones of first frame.
17797 Set kind of frames added to end of stream.
17798 Can be either @var{add} or @var{clone}.
17799 With @var{add} frames of solid-color are added.
17800 With @var{clone} frames are clones of last frame.
17802 @item start_duration, stop_duration
17803 Specify the duration of the start/stop delay. See
17804 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
17805 for the accepted syntax.
17806 These options override @var{start} and @var{stop}.
17809 Specify the color of the padded area. For the syntax of this option,
17810 check the @ref{color syntax,,"Color" section in the ffmpeg-utils
17811 manual,ffmpeg-utils}.
17813 The default value of @var{color} is "black".
17819 Transpose rows with columns in the input video and optionally flip it.
17821 It accepts the following parameters:
17826 Specify the transposition direction.
17828 Can assume the following values:
17830 @item 0, 4, cclock_flip
17831 Rotate by 90 degrees counterclockwise and vertically flip (default), that is:
17839 Rotate by 90 degrees clockwise, that is:
17847 Rotate by 90 degrees counterclockwise, that is:
17854 @item 3, 7, clock_flip
17855 Rotate by 90 degrees clockwise and vertically flip, that is:
17863 For values between 4-7, the transposition is only done if the input
17864 video geometry is portrait and not landscape. These values are
17865 deprecated, the @code{passthrough} option should be used instead.
17867 Numerical values are deprecated, and should be dropped in favor of
17868 symbolic constants.
17871 Do not apply the transposition if the input geometry matches the one
17872 specified by the specified value. It accepts the following values:
17875 Always apply transposition.
17877 Preserve portrait geometry (when @var{height} >= @var{width}).
17879 Preserve landscape geometry (when @var{width} >= @var{height}).
17882 Default value is @code{none}.
17885 For example to rotate by 90 degrees clockwise and preserve portrait
17888 transpose=dir=1:passthrough=portrait
17891 The command above can also be specified as:
17893 transpose=1:portrait
17896 @section transpose_npp
17898 Transpose rows with columns in the input video and optionally flip it.
17899 For more in depth examples see the @ref{transpose} video filter, which shares mostly the same options.
17901 It accepts the following parameters:
17906 Specify the transposition direction.
17908 Can assume the following values:
17911 Rotate by 90 degrees counterclockwise and vertically flip. (default)
17914 Rotate by 90 degrees clockwise.
17917 Rotate by 90 degrees counterclockwise.
17920 Rotate by 90 degrees clockwise and vertically flip.
17924 Do not apply the transposition if the input geometry matches the one
17925 specified by the specified value. It accepts the following values:
17928 Always apply transposition. (default)
17930 Preserve portrait geometry (when @var{height} >= @var{width}).
17932 Preserve landscape geometry (when @var{width} >= @var{height}).
17938 Trim the input so that the output contains one continuous subpart of the input.
17940 It accepts the following parameters:
17943 Specify the time of the start of the kept section, i.e. the frame with the
17944 timestamp @var{start} will be the first frame in the output.
17947 Specify the time of the first frame that will be dropped, i.e. the frame
17948 immediately preceding the one with the timestamp @var{end} will be the last
17949 frame in the output.
17952 This is the same as @var{start}, except this option sets the start timestamp
17953 in timebase units instead of seconds.
17956 This is the same as @var{end}, except this option sets the end timestamp
17957 in timebase units instead of seconds.
17960 The maximum duration of the output in seconds.
17963 The number of the first frame that should be passed to the output.
17966 The number of the first frame that should be dropped.
17969 @option{start}, @option{end}, and @option{duration} are expressed as time
17970 duration specifications; see
17971 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
17972 for the accepted syntax.
17974 Note that the first two sets of the start/end options and the @option{duration}
17975 option look at the frame timestamp, while the _frame variants simply count the
17976 frames that pass through the filter. Also note that this filter does not modify
17977 the timestamps. If you wish for the output timestamps to start at zero, insert a
17978 setpts filter after the trim filter.
17980 If multiple start or end options are set, this filter tries to be greedy and
17981 keep all the frames that match at least one of the specified constraints. To keep
17982 only the part that matches all the constraints at once, chain multiple trim
17985 The defaults are such that all the input is kept. So it is possible to set e.g.
17986 just the end values to keep everything before the specified time.
17991 Drop everything except the second minute of input:
17993 ffmpeg -i INPUT -vf trim=60:120
17997 Keep only the first second:
17999 ffmpeg -i INPUT -vf trim=duration=1
18004 @section unpremultiply
18005 Apply alpha unpremultiply effect to input video stream using first plane
18006 of second stream as alpha.
18008 Both streams must have same dimensions and same pixel format.
18010 The filter accepts the following option:
18014 Set which planes will be processed, unprocessed planes will be copied.
18015 By default value 0xf, all planes will be processed.
18017 If the format has 1 or 2 components, then luma is bit 0.
18018 If the format has 3 or 4 components:
18019 for RGB formats bit 0 is green, bit 1 is blue and bit 2 is red;
18020 for YUV formats bit 0 is luma, bit 1 is chroma-U and bit 2 is chroma-V.
18021 If present, the alpha channel is always the last bit.
18024 Do not require 2nd input for processing, instead use alpha plane from input stream.
18030 Sharpen or blur the input video.
18032 It accepts the following parameters:
18035 @item luma_msize_x, lx
18036 Set the luma matrix horizontal size. It must be an odd integer between
18037 3 and 23. The default value is 5.
18039 @item luma_msize_y, ly
18040 Set the luma matrix vertical size. It must be an odd integer between 3
18041 and 23. The default value is 5.
18043 @item luma_amount, la
18044 Set the luma effect strength. It must be a floating point number, reasonable
18045 values lay between -1.5 and 1.5.
18047 Negative values will blur the input video, while positive values will
18048 sharpen it, a value of zero will disable the effect.
18050 Default value is 1.0.
18052 @item chroma_msize_x, cx
18053 Set the chroma matrix horizontal size. It must be an odd integer
18054 between 3 and 23. The default value is 5.
18056 @item chroma_msize_y, cy
18057 Set the chroma matrix vertical size. It must be an odd integer
18058 between 3 and 23. The default value is 5.
18060 @item chroma_amount, ca
18061 Set the chroma effect strength. It must be a floating point number, reasonable
18062 values lay between -1.5 and 1.5.
18064 Negative values will blur the input video, while positive values will
18065 sharpen it, a value of zero will disable the effect.
18067 Default value is 0.0.
18071 All parameters are optional and default to the equivalent of the
18072 string '5:5:1.0:5:5:0.0'.
18074 @subsection Examples
18078 Apply strong luma sharpen effect:
18080 unsharp=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5
18084 Apply a strong blur of both luma and chroma parameters:
18086 unsharp=7:7:-2:7:7:-2
18092 Apply ultra slow/simple postprocessing filter that compresses and decompresses
18093 the image at several (or - in the case of @option{quality} level @code{8} - all)
18094 shifts and average the results.
18096 The way this differs from the behavior of spp is that uspp actually encodes &
18097 decodes each case with libavcodec Snow, whereas spp uses a simplified intra only 8x8
18098 DCT similar to MJPEG.
18100 The filter accepts the following options:
18104 Set quality. This option defines the number of levels for averaging. It accepts
18105 an integer in the range 0-8. If set to @code{0}, the filter will have no
18106 effect. A value of @code{8} means the higher quality. For each increment of
18107 that value the speed drops by a factor of approximately 2. Default value is
18111 Force a constant quantization parameter. If not set, the filter will use the QP
18112 from the video stream (if available).
18117 Convert 360 videos between various formats.
18119 The filter accepts the following options:
18125 Set format of the input/output video.
18133 Equirectangular projection.
18138 Cubemap with 3x2/6x1/1x6 layout.
18140 Format specific options:
18145 Set padding proportion for the input/output cubemap. Values in decimals.
18152 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)
18155 Default value is @b{@samp{0}}.
18159 Set fixed padding for the input/output cubemap. Values in pixels.
18161 Default value is @b{@samp{0}}. If greater than zero it overrides other padding options.
18165 Set order of faces for the input/output cubemap. Choose one direction for each position.
18167 Designation of directions:
18183 Default value is @b{@samp{rludfb}}.
18187 Set rotation of faces for the input/output cubemap. Choose one angle for each position.
18189 Designation of angles:
18192 0 degrees clockwise
18194 90 degrees clockwise
18196 180 degrees clockwise
18198 270 degrees clockwise
18201 Default value is @b{@samp{000000}}.
18205 Equi-Angular Cubemap.
18210 Regular video. @i{(output only)}
18212 Format specific options:
18217 Set horizontal/vertical/diagonal field of view. Values in degrees.
18219 If diagonal field of view is set it overrides horizontal and vertical field of view.
18225 Format specific options:
18229 Set padding proportion. Values in decimals.
18239 Default value is @b{@samp{0}}.
18244 Facebook's 360 format.
18247 Stereographic format.
18249 Format specific options:
18254 Set horizontal/vertical/diagonal field of view. Values in degrees.
18256 If diagonal field of view is set it overrides horizontal and vertical field of view.
18263 Ball format, gives significant distortion toward the back.
18266 Hammer-Aitoff map projection format.
18269 Sinusoidal map projection format.
18274 Set interpolation method.@*
18275 @i{Note: more complex interpolation methods require much more memory to run.}
18285 Bilinear interpolation.
18288 Bicubic interpolation.
18291 Lanczos interpolation.
18294 Default value is @b{@samp{line}}.
18298 Set the output video resolution.
18300 Default resolution depends on formats.
18304 Set the input/output stereo format.
18315 Default value is @b{@samp{2d}} for input and output format.
18320 Set rotation for the output video. Values in degrees.
18323 Set rotation order for the output video. Choose one item for each position.
18334 Default value is @b{@samp{ypr}}.
18339 Flip the output video horizontally(swaps left-right)/vertically(swaps up-down)/in-depth(swaps back-forward). Boolean values.
18343 Set if input video is flipped horizontally/vertically. Boolean values.
18346 Set if input video is transposed. Boolean value, by default disabled.
18349 Set if output video needs to be transposed. Boolean value, by default disabled.
18353 @subsection Examples
18357 Convert equirectangular video to cubemap with 3x2 layout and 1% padding using bicubic interpolation:
18359 ffmpeg -i input.mkv -vf v360=e:c3x2:cubic:out_pad=0.01 output.mkv
18362 Extract back view of Equi-Angular Cubemap:
18364 ffmpeg -i input.mkv -vf v360=eac:flat:yaw=180 output.mkv
18367 Convert transposed and horizontally flipped Equi-Angular Cubemap in side-by-side stereo format to equirectangular top-bottom stereo format:
18369 v360=eac:equirect:in_stereo=sbs:in_trans=1:ih_flip=1:out_stereo=tb
18373 @section vaguedenoiser
18375 Apply a wavelet based denoiser.
18377 It transforms each frame from the video input into the wavelet domain,
18378 using Cohen-Daubechies-Feauveau 9/7. Then it applies some filtering to
18379 the obtained coefficients. It does an inverse wavelet transform after.
18380 Due to wavelet properties, it should give a nice smoothed result, and
18381 reduced noise, without blurring picture features.
18383 This filter accepts the following options:
18387 The filtering strength. The higher, the more filtered the video will be.
18388 Hard thresholding can use a higher threshold than soft thresholding
18389 before the video looks overfiltered. Default value is 2.
18392 The filtering method the filter will use.
18394 It accepts the following values:
18397 All values under the threshold will be zeroed.
18400 All values under the threshold will be zeroed. All values above will be
18401 reduced by the threshold.
18404 Scales or nullifies coefficients - intermediary between (more) soft and
18405 (less) hard thresholding.
18408 Default is garrote.
18411 Number of times, the wavelet will decompose the picture. Picture can't
18412 be decomposed beyond a particular point (typically, 8 for a 640x480
18413 frame - as 2^9 = 512 > 480). Valid values are integers between 1 and 32. Default value is 6.
18416 Partial of full denoising (limited coefficients shrinking), from 0 to 100. Default value is 85.
18419 A list of the planes to process. By default all planes are processed.
18422 @section vectorscope
18424 Display 2 color component values in the two dimensional graph (which is called
18427 This filter accepts the following options:
18431 Set vectorscope mode.
18433 It accepts the following values:
18436 Gray values are displayed on graph, higher brightness means more pixels have
18437 same component color value on location in graph. This is the default mode.
18440 Gray values are displayed on graph. Surrounding pixels values which are not
18441 present in video frame are drawn in gradient of 2 color components which are
18442 set by option @code{x} and @code{y}. The 3rd color component is static.
18445 Actual color components values present in video frame are displayed on graph.
18448 Similar as color2 but higher frequency of same values @code{x} and @code{y}
18449 on graph increases value of another color component, which is luminance by
18450 default values of @code{x} and @code{y}.
18453 Actual colors present in video frame are displayed on graph. If two different
18454 colors map to same position on graph then color with higher value of component
18455 not present in graph is picked.
18458 Gray values are displayed on graph. Similar to @code{color} but with 3rd color
18459 component picked from radial gradient.
18463 Set which color component will be represented on X-axis. Default is @code{1}.
18466 Set which color component will be represented on Y-axis. Default is @code{2}.
18469 Set intensity, used by modes: gray, color, color3 and color5 for increasing brightness
18470 of color component which represents frequency of (X, Y) location in graph.
18475 No envelope, this is default.
18478 Instant envelope, even darkest single pixel will be clearly highlighted.
18481 Hold maximum and minimum values presented in graph over time. This way you
18482 can still spot out of range values without constantly looking at vectorscope.
18485 Peak and instant envelope combined together.
18489 Set what kind of graticule to draw.
18497 Set graticule opacity.
18500 Set graticule flags.
18504 Draw graticule for white point.
18507 Draw graticule for black point.
18510 Draw color points short names.
18514 Set background opacity.
18516 @item lthreshold, l
18517 Set low threshold for color component not represented on X or Y axis.
18518 Values lower than this value will be ignored. Default is 0.
18519 Note this value is multiplied with actual max possible value one pixel component
18520 can have. So for 8-bit input and low threshold value of 0.1 actual threshold
18523 @item hthreshold, h
18524 Set high threshold for color component not represented on X or Y axis.
18525 Values higher than this value will be ignored. Default is 1.
18526 Note this value is multiplied with actual max possible value one pixel component
18527 can have. So for 8-bit input and high threshold value of 0.9 actual threshold
18528 is 0.9 * 255 = 230.
18530 @item colorspace, c
18531 Set what kind of colorspace to use when drawing graticule.
18540 @anchor{vidstabdetect}
18541 @section vidstabdetect
18543 Analyze video stabilization/deshaking. Perform pass 1 of 2, see
18544 @ref{vidstabtransform} for pass 2.
18546 This filter generates a file with relative translation and rotation
18547 transform information about subsequent frames, which is then used by
18548 the @ref{vidstabtransform} filter.
18550 To enable compilation of this filter you need to configure FFmpeg with
18551 @code{--enable-libvidstab}.
18553 This filter accepts the following options:
18557 Set the path to the file used to write the transforms information.
18558 Default value is @file{transforms.trf}.
18561 Set how shaky the video is and how quick the camera is. It accepts an
18562 integer in the range 1-10, a value of 1 means little shakiness, a
18563 value of 10 means strong shakiness. Default value is 5.
18566 Set the accuracy of the detection process. It must be a value in the
18567 range 1-15. A value of 1 means low accuracy, a value of 15 means high
18568 accuracy. Default value is 15.
18571 Set stepsize of the search process. The region around minimum is
18572 scanned with 1 pixel resolution. Default value is 6.
18575 Set minimum contrast. Below this value a local measurement field is
18576 discarded. Must be a floating point value in the range 0-1. Default
18580 Set reference frame number for tripod mode.
18582 If enabled, the motion of the frames is compared to a reference frame
18583 in the filtered stream, identified by the specified number. The idea
18584 is to compensate all movements in a more-or-less static scene and keep
18585 the camera view absolutely still.
18587 If set to 0, it is disabled. The frames are counted starting from 1.
18590 Show fields and transforms in the resulting frames. It accepts an
18591 integer in the range 0-2. Default value is 0, which disables any
18595 @subsection Examples
18599 Use default values:
18605 Analyze strongly shaky movie and put the results in file
18606 @file{mytransforms.trf}:
18608 vidstabdetect=shakiness=10:accuracy=15:result="mytransforms.trf"
18612 Visualize the result of internal transformations in the resulting
18615 vidstabdetect=show=1
18619 Analyze a video with medium shakiness using @command{ffmpeg}:
18621 ffmpeg -i input -vf vidstabdetect=shakiness=5:show=1 dummy.avi
18625 @anchor{vidstabtransform}
18626 @section vidstabtransform
18628 Video stabilization/deshaking: pass 2 of 2,
18629 see @ref{vidstabdetect} for pass 1.
18631 Read a file with transform information for each frame and
18632 apply/compensate them. Together with the @ref{vidstabdetect}
18633 filter this can be used to deshake videos. See also
18634 @url{http://public.hronopik.de/vid.stab}. It is important to also use
18635 the @ref{unsharp} filter, see below.
18637 To enable compilation of this filter you need to configure FFmpeg with
18638 @code{--enable-libvidstab}.
18640 @subsection Options
18644 Set path to the file used to read the transforms. Default value is
18645 @file{transforms.trf}.
18648 Set the number of frames (value*2 + 1) used for lowpass filtering the
18649 camera movements. Default value is 10.
18651 For example a number of 10 means that 21 frames are used (10 in the
18652 past and 10 in the future) to smoothen the motion in the video. A
18653 larger value leads to a smoother video, but limits the acceleration of
18654 the camera (pan/tilt movements). 0 is a special case where a static
18655 camera is simulated.
18658 Set the camera path optimization algorithm.
18660 Accepted values are:
18663 gaussian kernel low-pass filter on camera motion (default)
18665 averaging on transformations
18669 Set maximal number of pixels to translate frames. Default value is -1,
18673 Set maximal angle in radians (degree*PI/180) to rotate frames. Default
18674 value is -1, meaning no limit.
18677 Specify how to deal with borders that may be visible due to movement
18680 Available values are:
18683 keep image information from previous frame (default)
18685 fill the border black
18689 Invert transforms if set to 1. Default value is 0.
18692 Consider transforms as relative to previous frame if set to 1,
18693 absolute if set to 0. Default value is 0.
18696 Set percentage to zoom. A positive value will result in a zoom-in
18697 effect, a negative value in a zoom-out effect. Default value is 0 (no
18701 Set optimal zooming to avoid borders.
18703 Accepted values are:
18708 optimal static zoom value is determined (only very strong movements
18709 will lead to visible borders) (default)
18711 optimal adaptive zoom value is determined (no borders will be
18712 visible), see @option{zoomspeed}
18715 Note that the value given at zoom is added to the one calculated here.
18718 Set percent to zoom maximally each frame (enabled when
18719 @option{optzoom} is set to 2). Range is from 0 to 5, default value is
18723 Specify type of interpolation.
18725 Available values are:
18730 linear only horizontal
18732 linear in both directions (default)
18734 cubic in both directions (slow)
18738 Enable virtual tripod mode if set to 1, which is equivalent to
18739 @code{relative=0:smoothing=0}. Default value is 0.
18741 Use also @code{tripod} option of @ref{vidstabdetect}.
18744 Increase log verbosity if set to 1. Also the detected global motions
18745 are written to the temporary file @file{global_motions.trf}. Default
18749 @subsection Examples
18753 Use @command{ffmpeg} for a typical stabilization with default values:
18755 ffmpeg -i inp.mpeg -vf vidstabtransform,unsharp=5:5:0.8:3:3:0.4 inp_stabilized.mpeg
18758 Note the use of the @ref{unsharp} filter which is always recommended.
18761 Zoom in a bit more and load transform data from a given file:
18763 vidstabtransform=zoom=5:input="mytransforms.trf"
18767 Smoothen the video even more:
18769 vidstabtransform=smoothing=30
18775 Flip the input video vertically.
18777 For example, to vertically flip a video with @command{ffmpeg}:
18779 ffmpeg -i in.avi -vf "vflip" out.avi
18784 Detect variable frame rate video.
18786 This filter tries to detect if the input is variable or constant frame rate.
18788 At end it will output number of frames detected as having variable delta pts,
18789 and ones with constant delta pts.
18790 If there was frames with variable delta, than it will also show min and max delta
18795 Boost or alter saturation.
18797 The filter accepts the following options:
18800 Set strength of boost if positive value or strength of alter if negative value.
18801 Default is 0. Allowed range is from -2 to 2.
18804 Set the red balance. Default is 1. Allowed range is from -10 to 10.
18807 Set the green balance. Default is 1. Allowed range is from -10 to 10.
18810 Set the blue balance. Default is 1. Allowed range is from -10 to 10.
18813 Set the red luma coefficient.
18816 Set the green luma coefficient.
18819 Set the blue luma coefficient.
18822 If @code{intensity} is negative and this is set to 1, colors will change,
18823 otherwise colors will be less saturated, more towards gray.
18829 Make or reverse a natural vignetting effect.
18831 The filter accepts the following options:
18835 Set lens angle expression as a number of radians.
18837 The value is clipped in the @code{[0,PI/2]} range.
18839 Default value: @code{"PI/5"}
18843 Set center coordinates expressions. Respectively @code{"w/2"} and @code{"h/2"}
18847 Set forward/backward mode.
18849 Available modes are:
18852 The larger the distance from the central point, the darker the image becomes.
18855 The larger the distance from the central point, the brighter the image becomes.
18856 This can be used to reverse a vignette effect, though there is no automatic
18857 detection to extract the lens @option{angle} and other settings (yet). It can
18858 also be used to create a burning effect.
18861 Default value is @samp{forward}.
18864 Set evaluation mode for the expressions (@option{angle}, @option{x0}, @option{y0}).
18866 It accepts the following values:
18869 Evaluate expressions only once during the filter initialization.
18872 Evaluate expressions for each incoming frame. This is way slower than the
18873 @samp{init} mode since it requires all the scalers to be re-computed, but it
18874 allows advanced dynamic expressions.
18877 Default value is @samp{init}.
18880 Set dithering to reduce the circular banding effects. Default is @code{1}
18884 Set vignette aspect. This setting allows one to adjust the shape of the vignette.
18885 Setting this value to the SAR of the input will make a rectangular vignetting
18886 following the dimensions of the video.
18888 Default is @code{1/1}.
18891 @subsection Expressions
18893 The @option{alpha}, @option{x0} and @option{y0} expressions can contain the
18894 following parameters.
18899 input width and height
18902 the number of input frame, starting from 0
18905 the PTS (Presentation TimeStamp) time of the filtered video frame, expressed in
18906 @var{TB} units, NAN if undefined
18909 frame rate of the input video, NAN if the input frame rate is unknown
18912 the PTS (Presentation TimeStamp) of the filtered video frame,
18913 expressed in seconds, NAN if undefined
18916 time base of the input video
18920 @subsection Examples
18924 Apply simple strong vignetting effect:
18930 Make a flickering vignetting:
18932 vignette='PI/4+random(1)*PI/50':eval=frame
18937 @section vmafmotion
18939 Obtain the average vmaf motion score of a video.
18940 It is one of the component filters of VMAF.
18942 The obtained average motion score is printed through the logging system.
18944 In the below example the input file @file{ref.mpg} is being processed and score
18948 ffmpeg -i ref.mpg -lavfi vmafmotion -f null -
18952 Stack input videos vertically.
18954 All streams must be of same pixel format and of same width.
18956 Note that this filter is faster than using @ref{overlay} and @ref{pad} filter
18957 to create same output.
18959 The filter accepts the following options:
18963 Set number of input streams. Default is 2.
18966 If set to 1, force the output to terminate when the shortest input
18967 terminates. Default value is 0.
18972 Deinterlace the input video ("w3fdif" stands for "Weston 3 Field
18973 Deinterlacing Filter").
18975 Based on the process described by Martin Weston for BBC R&D, and
18976 implemented based on the de-interlace algorithm written by Jim
18977 Easterbrook for BBC R&D, the Weston 3 field deinterlacing filter
18978 uses filter coefficients calculated by BBC R&D.
18980 This filter uses field-dominance information in frame to decide which
18981 of each pair of fields to place first in the output.
18982 If it gets it wrong use @ref{setfield} filter before @code{w3fdif} filter.
18984 There are two sets of filter coefficients, so called "simple"
18985 and "complex". Which set of filter coefficients is used can
18986 be set by passing an optional parameter:
18990 Set the interlacing filter coefficients. Accepts one of the following values:
18994 Simple filter coefficient set.
18996 More-complex filter coefficient set.
18998 Default value is @samp{complex}.
19001 Specify which frames to deinterlace. Accepts one of the following values:
19005 Deinterlace all frames,
19007 Only deinterlace frames marked as interlaced.
19010 Default value is @samp{all}.
19014 Video waveform monitor.
19016 The waveform monitor plots color component intensity. By default luminance
19017 only. Each column of the waveform corresponds to a column of pixels in the
19020 It accepts the following options:
19024 Can be either @code{row}, or @code{column}. Default is @code{column}.
19025 In row mode, the graph on the left side represents color component value 0 and
19026 the right side represents value = 255. In column mode, the top side represents
19027 color component value = 0 and bottom side represents value = 255.
19030 Set intensity. Smaller values are useful to find out how many values of the same
19031 luminance are distributed across input rows/columns.
19032 Default value is @code{0.04}. Allowed range is [0, 1].
19035 Set mirroring mode. @code{0} means unmirrored, @code{1} means mirrored.
19036 In mirrored mode, higher values will be represented on the left
19037 side for @code{row} mode and at the top for @code{column} mode. Default is
19038 @code{1} (mirrored).
19042 It accepts the following values:
19045 Presents information identical to that in the @code{parade}, except
19046 that the graphs representing color components are superimposed directly
19049 This display mode makes it easier to spot relative differences or similarities
19050 in overlapping areas of the color components that are supposed to be identical,
19051 such as neutral whites, grays, or blacks.
19054 Display separate graph for the color components side by side in
19055 @code{row} mode or one below the other in @code{column} mode.
19058 Display separate graph for the color components side by side in
19059 @code{column} mode or one below the other in @code{row} mode.
19061 Using this display mode makes it easy to spot color casts in the highlights
19062 and shadows of an image, by comparing the contours of the top and the bottom
19063 graphs of each waveform. Since whites, grays, and blacks are characterized
19064 by exactly equal amounts of red, green, and blue, neutral areas of the picture
19065 should display three waveforms of roughly equal width/height. If not, the
19066 correction is easy to perform by making level adjustments the three waveforms.
19068 Default is @code{stack}.
19070 @item components, c
19071 Set which color components to display. Default is 1, which means only luminance
19072 or red color component if input is in RGB colorspace. If is set for example to
19073 7 it will display all 3 (if) available color components.
19078 No envelope, this is default.
19081 Instant envelope, minimum and maximum values presented in graph will be easily
19082 visible even with small @code{step} value.
19085 Hold minimum and maximum values presented in graph across time. This way you
19086 can still spot out of range values without constantly looking at waveforms.
19089 Peak and instant envelope combined together.
19095 No filtering, this is default.
19098 Luma and chroma combined together.
19101 Similar as above, but shows difference between blue and red chroma.
19104 Similar as above, but use different colors.
19107 Similar as above, but again with different colors.
19110 Displays only chroma.
19113 Displays actual color value on waveform.
19116 Similar as above, but with luma showing frequency of chroma values.
19120 Set which graticule to display.
19124 Do not display graticule.
19127 Display green graticule showing legal broadcast ranges.
19130 Display orange graticule showing legal broadcast ranges.
19133 Display invert graticule showing legal broadcast ranges.
19137 Set graticule opacity.
19140 Set graticule flags.
19144 Draw numbers above lines. By default enabled.
19147 Draw dots instead of lines.
19151 Set scale used for displaying graticule.
19158 Default is digital.
19161 Set background opacity.
19164 @section weave, doubleweave
19166 The @code{weave} takes a field-based video input and join
19167 each two sequential fields into single frame, producing a new double
19168 height clip with half the frame rate and half the frame count.
19170 The @code{doubleweave} works same as @code{weave} but without
19171 halving frame rate and frame count.
19173 It accepts the following option:
19177 Set first field. Available values are:
19181 Set the frame as top-field-first.
19184 Set the frame as bottom-field-first.
19188 @subsection Examples
19192 Interlace video using @ref{select} and @ref{separatefields} filter:
19194 separatefields,select=eq(mod(n,4),0)+eq(mod(n,4),3),weave
19199 Apply the xBR high-quality magnification filter which is designed for pixel
19200 art. It follows a set of edge-detection rules, see
19201 @url{https://forums.libretro.com/t/xbr-algorithm-tutorial/123}.
19203 It accepts the following option:
19207 Set the scaling dimension: @code{2} for @code{2xBR}, @code{3} for
19208 @code{3xBR} and @code{4} for @code{4xBR}.
19209 Default is @code{3}.
19213 Pick median pixels from several input videos.
19215 The filter accepts the following options:
19219 Set number of inputs.
19220 Default is 3. Allowed range is from 3 to 255.
19221 If number of inputs is even number, than result will be mean value between two median values.
19224 Set which planes to filter. Default value is @code{15}, by which all planes are processed.
19228 Stack video inputs into custom layout.
19230 All streams must be of same pixel format.
19232 The filter accepts the following options:
19236 Set number of input streams. Default is 2.
19239 Specify layout of inputs.
19240 This option requires the desired layout configuration to be explicitly set by the user.
19241 This sets position of each video input in output. Each input
19242 is separated by '|'.
19243 The first number represents the column, and the second number represents the row.
19244 Numbers start at 0 and are separated by '_'. Optionally one can use wX and hX,
19245 where X is video input from which to take width or height.
19246 Multiple values can be used when separated by '+'. In such
19247 case values are summed together.
19249 Note that if inputs are of different sizes gaps may appear, as not all of
19250 the output video frame will be filled. Similarly, videos can overlap each
19251 other if their position doesn't leave enough space for the full frame of
19254 For 2 inputs, a default layout of @code{0_0|w0_0} is set. In all other cases,
19255 a layout must be set by the user.
19258 If set to 1, force the output to terminate when the shortest input
19259 terminates. Default value is 0.
19262 @subsection Examples
19266 Display 4 inputs into 2x2 grid.
19270 input1(0, 0) | input3(w0, 0)
19271 input2(0, h0) | input4(w0, h0)
19275 xstack=inputs=4:layout=0_0|0_h0|w0_0|w0_h0
19278 Note that if inputs are of different sizes, gaps or overlaps may occur.
19281 Display 4 inputs into 1x4 grid.
19288 input4(0, h0+h1+h2)
19292 xstack=inputs=4:layout=0_0|0_h0|0_h0+h1|0_h0+h1+h2
19295 Note that if inputs are of different widths, unused space will appear.
19298 Display 9 inputs into 3x3 grid.
19302 input1(0, 0) | input4(w0, 0) | input7(w0+w3, 0)
19303 input2(0, h0) | input5(w0, h0) | input8(w0+w3, h0)
19304 input3(0, h0+h1) | input6(w0, h0+h1) | input9(w0+w3, h0+h1)
19308 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
19311 Note that if inputs are of different sizes, gaps or overlaps may occur.
19314 Display 16 inputs into 4x4 grid.
19318 input1(0, 0) | input5(w0, 0) | input9 (w0+w4, 0) | input13(w0+w4+w8, 0)
19319 input2(0, h0) | input6(w0, h0) | input10(w0+w4, h0) | input14(w0+w4+w8, h0)
19320 input3(0, h0+h1) | input7(w0, h0+h1) | input11(w0+w4, h0+h1) | input15(w0+w4+w8, h0+h1)
19321 input4(0, h0+h1+h2)| input8(w0, h0+h1+h2)| input12(w0+w4, h0+h1+h2)| input16(w0+w4+w8, h0+h1+h2)
19325 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|
19326 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
19329 Note that if inputs are of different sizes, gaps or overlaps may occur.
19336 Deinterlace the input video ("yadif" means "yet another deinterlacing
19339 It accepts the following parameters:
19345 The interlacing mode to adopt. It accepts one of the following values:
19348 @item 0, send_frame
19349 Output one frame for each frame.
19350 @item 1, send_field
19351 Output one frame for each field.
19352 @item 2, send_frame_nospatial
19353 Like @code{send_frame}, but it skips the spatial interlacing check.
19354 @item 3, send_field_nospatial
19355 Like @code{send_field}, but it skips the spatial interlacing check.
19358 The default value is @code{send_frame}.
19361 The picture field parity assumed for the input interlaced video. It accepts one
19362 of the following values:
19366 Assume the top field is first.
19368 Assume the bottom field is first.
19370 Enable automatic detection of field parity.
19373 The default value is @code{auto}.
19374 If the interlacing is unknown or the decoder does not export this information,
19375 top field first will be assumed.
19378 Specify which frames to deinterlace. Accepts one of the following
19383 Deinterlace all frames.
19384 @item 1, interlaced
19385 Only deinterlace frames marked as interlaced.
19388 The default value is @code{all}.
19391 @section yadif_cuda
19393 Deinterlace the input video using the @ref{yadif} algorithm, but implemented
19394 in CUDA so that it can work as part of a GPU accelerated pipeline with nvdec
19397 It accepts the following parameters:
19403 The interlacing mode to adopt. It accepts one of the following values:
19406 @item 0, send_frame
19407 Output one frame for each frame.
19408 @item 1, send_field
19409 Output one frame for each field.
19410 @item 2, send_frame_nospatial
19411 Like @code{send_frame}, but it skips the spatial interlacing check.
19412 @item 3, send_field_nospatial
19413 Like @code{send_field}, but it skips the spatial interlacing check.
19416 The default value is @code{send_frame}.
19419 The picture field parity assumed for the input interlaced video. It accepts one
19420 of the following values:
19424 Assume the top field is first.
19426 Assume the bottom field is first.
19428 Enable automatic detection of field parity.
19431 The default value is @code{auto}.
19432 If the interlacing is unknown or the decoder does not export this information,
19433 top field first will be assumed.
19436 Specify which frames to deinterlace. Accepts one of the following
19441 Deinterlace all frames.
19442 @item 1, interlaced
19443 Only deinterlace frames marked as interlaced.
19446 The default value is @code{all}.
19451 Apply Zoom & Pan effect.
19453 This filter accepts the following options:
19457 Set the zoom expression. Range is 1-10. Default is 1.
19461 Set the x and y expression. Default is 0.
19464 Set the duration expression in number of frames.
19465 This sets for how many number of frames effect will last for
19466 single input image.
19469 Set the output image size, default is 'hd720'.
19472 Set the output frame rate, default is '25'.
19475 Each expression can contain the following constants:
19494 Output frame count.
19498 Last calculated 'x' and 'y' position from 'x' and 'y' expression
19499 for current input frame.
19503 'x' and 'y' of last output frame of previous input frame or 0 when there was
19504 not yet such frame (first input frame).
19507 Last calculated zoom from 'z' expression for current input frame.
19510 Last calculated zoom of last output frame of previous input frame.
19513 Number of output frames for current input frame. Calculated from 'd' expression
19514 for each input frame.
19517 number of output frames created for previous input frame
19520 Rational number: input width / input height
19523 sample aspect ratio
19526 display aspect ratio
19530 @subsection Examples
19534 Zoom-in up to 1.5 and pan at same time to some spot near center of picture:
19536 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
19540 Zoom-in up to 1.5 and pan always at center of picture:
19542 zoompan=z='min(zoom+0.0015,1.5)':d=700:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
19546 Same as above but without pausing:
19548 zoompan=z='min(max(zoom,pzoom)+0.0015,1.5)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
19554 Scale (resize) the input video, using the z.lib library:
19555 @url{https://github.com/sekrit-twc/zimg}. To enable compilation of this
19556 filter, you need to configure FFmpeg with @code{--enable-libzimg}.
19558 The zscale filter forces the output display aspect ratio to be the same
19559 as the input, by changing the output sample aspect ratio.
19561 If the input image format is different from the format requested by
19562 the next filter, the zscale filter will convert the input to the
19565 @subsection Options
19566 The filter accepts the following options.
19571 Set the output video dimension expression. Default value is the input
19574 If the @var{width} or @var{w} value is 0, the input width is used for
19575 the output. If the @var{height} or @var{h} value is 0, the input height
19576 is used for the output.
19578 If one and only one of the values is -n with n >= 1, the zscale filter
19579 will use a value that maintains the aspect ratio of the input image,
19580 calculated from the other specified dimension. After that it will,
19581 however, make sure that the calculated dimension is divisible by n and
19582 adjust the value if necessary.
19584 If both values are -n with n >= 1, the behavior will be identical to
19585 both values being set to 0 as previously detailed.
19587 See below for the list of accepted constants for use in the dimension
19591 Set the video size. For the syntax of this option, check the
19592 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
19595 Set the dither type.
19597 Possible values are:
19602 @item error_diffusion
19608 Set the resize filter type.
19610 Possible values are:
19620 Default is bilinear.
19623 Set the color range.
19625 Possible values are:
19632 Default is same as input.
19635 Set the color primaries.
19637 Possible values are:
19647 Default is same as input.
19650 Set the transfer characteristics.
19652 Possible values are:
19666 Default is same as input.
19669 Set the colorspace matrix.
19671 Possible value are:
19682 Default is same as input.
19685 Set the input color range.
19687 Possible values are:
19694 Default is same as input.
19696 @item primariesin, pin
19697 Set the input color primaries.
19699 Possible values are:
19709 Default is same as input.
19711 @item transferin, tin
19712 Set the input transfer characteristics.
19714 Possible values are:
19725 Default is same as input.
19727 @item matrixin, min
19728 Set the input colorspace matrix.
19730 Possible value are:
19742 Set the output chroma location.
19744 Possible values are:
19755 @item chromalin, cin
19756 Set the input chroma location.
19758 Possible values are:
19770 Set the nominal peak luminance.
19773 The values of the @option{w} and @option{h} options are expressions
19774 containing the following constants:
19779 The input width and height
19783 These are the same as @var{in_w} and @var{in_h}.
19787 The output (scaled) width and height
19791 These are the same as @var{out_w} and @var{out_h}
19794 The same as @var{iw} / @var{ih}
19797 input sample aspect ratio
19800 The input display aspect ratio. Calculated from @code{(iw / ih) * sar}.
19804 horizontal and vertical input chroma subsample values. For example for the
19805 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
19809 horizontal and vertical output chroma subsample values. For example for the
19810 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
19816 @c man end VIDEO FILTERS
19818 @chapter OpenCL Video Filters
19819 @c man begin OPENCL VIDEO FILTERS
19821 Below is a description of the currently available OpenCL video filters.
19823 To enable compilation of these filters you need to configure FFmpeg with
19824 @code{--enable-opencl}.
19826 Running OpenCL filters requires you to initialize a hardware device and to pass that device to all filters in any filter graph.
19829 @item -init_hw_device opencl[=@var{name}][:@var{device}[,@var{key=value}...]]
19830 Initialise a new hardware device of type @var{opencl} called @var{name}, using the
19831 given device parameters.
19833 @item -filter_hw_device @var{name}
19834 Pass the hardware device called @var{name} to all filters in any filter graph.
19838 For more detailed information see @url{https://www.ffmpeg.org/ffmpeg.html#Advanced-Video-options}
19842 Example of choosing the first device on the second platform and running avgblur_opencl filter with default parameters on it.
19844 -init_hw_device opencl=gpu:1.0 -filter_hw_device gpu -i INPUT -vf "hwupload, avgblur_opencl, hwdownload" OUTPUT
19848 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.
19850 @section avgblur_opencl
19852 Apply average blur filter.
19854 The filter accepts the following options:
19858 Set horizontal radius size.
19859 Range is @code{[1, 1024]} and default value is @code{1}.
19862 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
19865 Set vertical radius size. Range is @code{[1, 1024]} and default value is @code{0}. If zero, @code{sizeX} value will be used.
19868 @subsection Example
19872 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.
19874 -i INPUT -vf "hwupload, avgblur_opencl=3, hwdownload" OUTPUT
19878 @section boxblur_opencl
19880 Apply a boxblur algorithm to the input video.
19882 It accepts the following parameters:
19886 @item luma_radius, lr
19887 @item luma_power, lp
19888 @item chroma_radius, cr
19889 @item chroma_power, cp
19890 @item alpha_radius, ar
19891 @item alpha_power, ap
19895 A description of the accepted options follows.
19898 @item luma_radius, lr
19899 @item chroma_radius, cr
19900 @item alpha_radius, ar
19901 Set an expression for the box radius in pixels used for blurring the
19902 corresponding input plane.
19904 The radius value must be a non-negative number, and must not be
19905 greater than the value of the expression @code{min(w,h)/2} for the
19906 luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma
19909 Default value for @option{luma_radius} is "2". If not specified,
19910 @option{chroma_radius} and @option{alpha_radius} default to the
19911 corresponding value set for @option{luma_radius}.
19913 The expressions can contain the following constants:
19917 The input width and height in pixels.
19921 The input chroma image width and height in pixels.
19925 The horizontal and vertical chroma subsample values. For example, for the
19926 pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1.
19929 @item luma_power, lp
19930 @item chroma_power, cp
19931 @item alpha_power, ap
19932 Specify how many times the boxblur filter is applied to the
19933 corresponding plane.
19935 Default value for @option{luma_power} is 2. If not specified,
19936 @option{chroma_power} and @option{alpha_power} default to the
19937 corresponding value set for @option{luma_power}.
19939 A value of 0 will disable the effect.
19942 @subsection Examples
19944 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.
19948 Apply a boxblur filter with the luma, chroma, and alpha radius
19949 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.
19951 -i INPUT -vf "hwupload, boxblur_opencl=luma_radius=2:luma_power=3, hwdownload" OUTPUT
19952 -i INPUT -vf "hwupload, boxblur_opencl=2:3, hwdownload" OUTPUT
19956 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.
19958 For the luma plane, a 2x2 box radius will be run once.
19960 For the chroma plane, a 4x4 box radius will be run 5 times.
19962 For the alpha plane, a 3x3 box radius will be run 7 times.
19964 -i INPUT -vf "hwupload, boxblur_opencl=2:1:4:5:3:7, hwdownload" OUTPUT
19968 @section convolution_opencl
19970 Apply convolution of 3x3, 5x5, 7x7 matrix.
19972 The filter accepts the following options:
19979 Set matrix for each plane.
19980 Matrix is sequence of 9, 25 or 49 signed numbers.
19981 Default value for each plane is @code{0 0 0 0 1 0 0 0 0}.
19987 Set multiplier for calculated value for each plane.
19988 If unset or 0, it will be sum of all matrix elements.
19989 The option value must be a float number greater or equal to @code{0.0}. Default value is @code{1.0}.
19995 Set bias for each plane. This value is added to the result of the multiplication.
19996 Useful for making the overall image brighter or darker.
19997 The option value must be a float number greater or equal to @code{0.0}. Default value is @code{0.0}.
20001 @subsection Examples
20007 -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
20013 -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
20017 Apply edge enhance:
20019 -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
20025 -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
20029 Apply laplacian edge detector which includes diagonals:
20031 -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
20037 -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
20041 @section dilation_opencl
20043 Apply dilation effect to the video.
20045 This filter replaces the pixel by the local(3x3) maximum.
20047 It accepts the following options:
20054 Limit the maximum change for each plane. Range is @code{[0, 65535]} and default value is @code{65535}.
20055 If @code{0}, plane will remain unchanged.
20058 Flag which specifies the pixel to refer to.
20059 Range is @code{[0, 255]} and default value is @code{255}, i.e. all eight pixels are used.
20061 Flags to local 3x3 coordinates region centered on @code{x}:
20070 @subsection Example
20074 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.
20076 -i INPUT -vf "hwupload, dilation_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT
20080 @section erosion_opencl
20082 Apply erosion effect to the video.
20084 This filter replaces the pixel by the local(3x3) minimum.
20086 It accepts the following options:
20093 Limit the maximum change for each plane. Range is @code{[0, 65535]} and default value is @code{65535}.
20094 If @code{0}, plane will remain unchanged.
20097 Flag which specifies the pixel to refer to.
20098 Range is @code{[0, 255]} and default value is @code{255}, i.e. all eight pixels are used.
20100 Flags to local 3x3 coordinates region centered on @code{x}:
20109 @subsection Example
20113 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.
20115 -i INPUT -vf "hwupload, erosion_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT
20119 @section colorkey_opencl
20120 RGB colorspace color keying.
20122 The filter accepts the following options:
20126 The color which will be replaced with transparency.
20129 Similarity percentage with the key color.
20131 0.01 matches only the exact key color, while 1.0 matches everything.
20136 0.0 makes pixels either fully transparent, or not transparent at all.
20138 Higher values result in semi-transparent pixels, with a higher transparency
20139 the more similar the pixels color is to the key color.
20142 @subsection Examples
20146 Make every semi-green pixel in the input transparent with some slight blending:
20148 -i INPUT -vf "hwupload, colorkey_opencl=green:0.3:0.1, hwdownload" OUTPUT
20152 @section deshake_opencl
20153 Feature-point based video stabilization filter.
20155 The filter accepts the following options:
20159 Simulates a tripod by preventing any camera movement whatsoever from the original frame. Defaults to @code{0}.
20162 Whether or not additional debug info should be displayed, both in the processed output and in the console.
20164 Note that in order to see console debug output you will also need to pass @code{-v verbose} to ffmpeg.
20166 Viewing point matches in the output video is only supported for RGB input.
20168 Defaults to @code{0}.
20170 @item adaptive_crop
20171 Whether or not to do a tiny bit of cropping at the borders to cut down on the amount of mirrored pixels.
20173 Defaults to @code{1}.
20175 @item refine_features
20176 Whether or not feature points should be refined at a sub-pixel level.
20178 This can be turned off for a slight performance gain at the cost of precision.
20180 Defaults to @code{1}.
20182 @item smooth_strength
20183 The strength of the smoothing applied to the camera path from @code{0.0} to @code{1.0}.
20185 @code{1.0} is the maximum smoothing strength while values less than that result in less smoothing.
20187 @code{0.0} causes the filter to adaptively choose a smoothing strength on a per-frame basis.
20189 Defaults to @code{0.0}.
20191 @item smooth_window_multiplier
20192 Controls the size of the smoothing window (the number of frames buffered to determine motion information from).
20194 The size of the smoothing window is determined by multiplying the framerate of the video by this number.
20196 Acceptable values range from @code{0.1} to @code{10.0}.
20198 Larger values increase the amount of motion data available for determining how to smooth the camera path,
20199 potentially improving smoothness, but also increase latency and memory usage.
20201 Defaults to @code{2.0}.
20205 @subsection Examples
20209 Stabilize a video with a fixed, medium smoothing strength:
20211 -i INPUT -vf "hwupload, deshake_opencl=smooth_strength=0.5, hwdownload" OUTPUT
20215 Stabilize a video with debugging (both in console and in rendered video):
20217 -i INPUT -filter_complex "[0:v]format=rgba, hwupload, deshake_opencl=debug=1, hwdownload, format=rgba, format=yuv420p" -v verbose OUTPUT
20221 @section nlmeans_opencl
20223 Non-local Means denoise filter through OpenCL, this filter accepts same options as @ref{nlmeans}.
20225 @section overlay_opencl
20227 Overlay one video on top of another.
20229 It takes two inputs and has one output. The first input is the "main" video on which the second input is overlaid.
20230 This filter requires same memory layout for all the inputs. So, format conversion may be needed.
20232 The filter accepts the following options:
20237 Set the x coordinate of the overlaid video on the main video.
20238 Default value is @code{0}.
20241 Set the x coordinate of the overlaid video on the main video.
20242 Default value is @code{0}.
20246 @subsection Examples
20250 Overlay an image LOGO at the top-left corner of the INPUT video. Both inputs are yuv420p format.
20252 -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuv420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT
20255 The inputs have same memory layout for color channels , the overlay has additional alpha plane, like INPUT is yuv420p, and the LOGO is yuva420p.
20257 -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuva420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT
20262 @section prewitt_opencl
20264 Apply the Prewitt operator (@url{https://en.wikipedia.org/wiki/Prewitt_operator}) to input video stream.
20266 The filter accepts the following option:
20270 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
20273 Set value which will be multiplied with filtered result.
20274 Range is @code{[0.0, 65535]} and default value is @code{1.0}.
20277 Set value which will be added to filtered result.
20278 Range is @code{[-65535, 65535]} and default value is @code{0.0}.
20281 @subsection Example
20285 Apply the Prewitt operator with scale set to 2 and delta set to 10.
20287 -i INPUT -vf "hwupload, prewitt_opencl=scale=2:delta=10, hwdownload" OUTPUT
20291 @section roberts_opencl
20292 Apply the Roberts cross operator (@url{https://en.wikipedia.org/wiki/Roberts_cross}) to input video stream.
20294 The filter accepts the following option:
20298 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
20301 Set value which will be multiplied with filtered result.
20302 Range is @code{[0.0, 65535]} and default value is @code{1.0}.
20305 Set value which will be added to filtered result.
20306 Range is @code{[-65535, 65535]} and default value is @code{0.0}.
20309 @subsection Example
20313 Apply the Roberts cross operator with scale set to 2 and delta set to 10
20315 -i INPUT -vf "hwupload, roberts_opencl=scale=2:delta=10, hwdownload" OUTPUT
20319 @section sobel_opencl
20321 Apply the Sobel operator (@url{https://en.wikipedia.org/wiki/Sobel_operator}) to input video stream.
20323 The filter accepts the following option:
20327 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
20330 Set value which will be multiplied with filtered result.
20331 Range is @code{[0.0, 65535]} and default value is @code{1.0}.
20334 Set value which will be added to filtered result.
20335 Range is @code{[-65535, 65535]} and default value is @code{0.0}.
20338 @subsection Example
20342 Apply sobel operator with scale set to 2 and delta set to 10
20344 -i INPUT -vf "hwupload, sobel_opencl=scale=2:delta=10, hwdownload" OUTPUT
20348 @section tonemap_opencl
20350 Perform HDR(PQ/HLG) to SDR conversion with tone-mapping.
20352 It accepts the following parameters:
20356 Specify the tone-mapping operator to be used. Same as tonemap option in @ref{tonemap}.
20359 Tune the tone mapping algorithm. same as param option in @ref{tonemap}.
20362 Apply desaturation for highlights that exceed this level of brightness. The
20363 higher the parameter, the more color information will be preserved. This
20364 setting helps prevent unnaturally blown-out colors for super-highlights, by
20365 (smoothly) turning into white instead. This makes images feel more natural,
20366 at the cost of reducing information about out-of-range colors.
20368 The default value is 0.5, and the algorithm here is a little different from
20369 the cpu version tonemap currently. A setting of 0.0 disables this option.
20372 The tonemapping algorithm parameters is fine-tuned per each scene. And a threshold
20373 is used to detect whether the scene has changed or not. If the distance between
20374 the current frame average brightness and the current running average exceeds
20375 a threshold value, we would re-calculate scene average and peak brightness.
20376 The default value is 0.2.
20379 Specify the output pixel format.
20381 Currently supported formats are:
20388 Set the output color range.
20390 Possible values are:
20396 Default is same as input.
20399 Set the output color primaries.
20401 Possible values are:
20407 Default is same as input.
20410 Set the output transfer characteristics.
20412 Possible values are:
20421 Set the output colorspace matrix.
20423 Possible value are:
20429 Default is same as input.
20433 @subsection Example
20437 Convert HDR(PQ/HLG) video to bt2020-transfer-characteristic p010 format using linear operator.
20439 -i INPUT -vf "format=p010,hwupload,tonemap_opencl=t=bt2020:tonemap=linear:format=p010,hwdownload,format=p010" OUTPUT
20443 @section unsharp_opencl
20445 Sharpen or blur the input video.
20447 It accepts the following parameters:
20450 @item luma_msize_x, lx
20451 Set the luma matrix horizontal size.
20452 Range is @code{[1, 23]} and default value is @code{5}.
20454 @item luma_msize_y, ly
20455 Set the luma matrix vertical size.
20456 Range is @code{[1, 23]} and default value is @code{5}.
20458 @item luma_amount, la
20459 Set the luma effect strength.
20460 Range is @code{[-10, 10]} and default value is @code{1.0}.
20462 Negative values will blur the input video, while positive values will
20463 sharpen it, a value of zero will disable the effect.
20465 @item chroma_msize_x, cx
20466 Set the chroma matrix horizontal size.
20467 Range is @code{[1, 23]} and default value is @code{5}.
20469 @item chroma_msize_y, cy
20470 Set the chroma matrix vertical size.
20471 Range is @code{[1, 23]} and default value is @code{5}.
20473 @item chroma_amount, ca
20474 Set the chroma effect strength.
20475 Range is @code{[-10, 10]} and default value is @code{0.0}.
20477 Negative values will blur the input video, while positive values will
20478 sharpen it, a value of zero will disable the effect.
20482 All parameters are optional and default to the equivalent of the
20483 string '5:5:1.0:5:5:0.0'.
20485 @subsection Examples
20489 Apply strong luma sharpen effect:
20491 -i INPUT -vf "hwupload, unsharp_opencl=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5, hwdownload" OUTPUT
20495 Apply a strong blur of both luma and chroma parameters:
20497 -i INPUT -vf "hwupload, unsharp_opencl=7:7:-2:7:7:-2, hwdownload" OUTPUT
20501 @c man end OPENCL VIDEO FILTERS
20503 @chapter Video Sources
20504 @c man begin VIDEO SOURCES
20506 Below is a description of the currently available video sources.
20510 Buffer video frames, and make them available to the filter chain.
20512 This source is mainly intended for a programmatic use, in particular
20513 through the interface defined in @file{libavfilter/vsrc_buffer.h}.
20515 It accepts the following parameters:
20520 Specify the size (width and height) of the buffered video frames. For the
20521 syntax of this option, check the
20522 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
20525 The input video width.
20528 The input video height.
20531 A string representing the pixel format of the buffered video frames.
20532 It may be a number corresponding to a pixel format, or a pixel format
20536 Specify the timebase assumed by the timestamps of the buffered frames.
20539 Specify the frame rate expected for the video stream.
20541 @item pixel_aspect, sar
20542 The sample (pixel) aspect ratio of the input video.
20545 Specify the optional parameters to be used for the scale filter which
20546 is automatically inserted when an input change is detected in the
20547 input size or format.
20549 @item hw_frames_ctx
20550 When using a hardware pixel format, this should be a reference to an
20551 AVHWFramesContext describing input frames.
20556 buffer=width=320:height=240:pix_fmt=yuv410p:time_base=1/24:sar=1
20559 will instruct the source to accept video frames with size 320x240 and
20560 with format "yuv410p", assuming 1/24 as the timestamps timebase and
20561 square pixels (1:1 sample aspect ratio).
20562 Since the pixel format with name "yuv410p" corresponds to the number 6
20563 (check the enum AVPixelFormat definition in @file{libavutil/pixfmt.h}),
20564 this example corresponds to:
20566 buffer=size=320x240:pixfmt=6:time_base=1/24:pixel_aspect=1/1
20569 Alternatively, the options can be specified as a flat string, but this
20570 syntax is deprecated:
20572 @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}]
20576 Create a pattern generated by an elementary cellular automaton.
20578 The initial state of the cellular automaton can be defined through the
20579 @option{filename} and @option{pattern} options. If such options are
20580 not specified an initial state is created randomly.
20582 At each new frame a new row in the video is filled with the result of
20583 the cellular automaton next generation. The behavior when the whole
20584 frame is filled is defined by the @option{scroll} option.
20586 This source accepts the following options:
20590 Read the initial cellular automaton state, i.e. the starting row, from
20591 the specified file.
20592 In the file, each non-whitespace character is considered an alive
20593 cell, a newline will terminate the row, and further characters in the
20594 file will be ignored.
20597 Read the initial cellular automaton state, i.e. the starting row, from
20598 the specified string.
20600 Each non-whitespace character in the string is considered an alive
20601 cell, a newline will terminate the row, and further characters in the
20602 string will be ignored.
20605 Set the video rate, that is the number of frames generated per second.
20608 @item random_fill_ratio, ratio
20609 Set the random fill ratio for the initial cellular automaton row. It
20610 is a floating point number value ranging from 0 to 1, defaults to
20613 This option is ignored when a file or a pattern is specified.
20615 @item random_seed, seed
20616 Set the seed for filling randomly the initial row, must be an integer
20617 included between 0 and UINT32_MAX. If not specified, or if explicitly
20618 set to -1, the filter will try to use a good random seed on a best
20622 Set the cellular automaton rule, it is a number ranging from 0 to 255.
20623 Default value is 110.
20626 Set the size of the output video. For the syntax of this option, check the
20627 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
20629 If @option{filename} or @option{pattern} is specified, the size is set
20630 by default to the width of the specified initial state row, and the
20631 height is set to @var{width} * PHI.
20633 If @option{size} is set, it must contain the width of the specified
20634 pattern string, and the specified pattern will be centered in the
20637 If a filename or a pattern string is not specified, the size value
20638 defaults to "320x518" (used for a randomly generated initial state).
20641 If set to 1, scroll the output upward when all the rows in the output
20642 have been already filled. If set to 0, the new generated row will be
20643 written over the top row just after the bottom row is filled.
20646 @item start_full, full
20647 If set to 1, completely fill the output with generated rows before
20648 outputting the first frame.
20649 This is the default behavior, for disabling set the value to 0.
20652 If set to 1, stitch the left and right row edges together.
20653 This is the default behavior, for disabling set the value to 0.
20656 @subsection Examples
20660 Read the initial state from @file{pattern}, and specify an output of
20663 cellauto=f=pattern:s=200x400
20667 Generate a random initial row with a width of 200 cells, with a fill
20670 cellauto=ratio=2/3:s=200x200
20674 Create a pattern generated by rule 18 starting by a single alive cell
20675 centered on an initial row with width 100:
20677 cellauto=p=@@:s=100x400:full=0:rule=18
20681 Specify a more elaborated initial pattern:
20683 cellauto=p='@@@@ @@ @@@@':s=100x400:full=0:rule=18
20688 @anchor{coreimagesrc}
20689 @section coreimagesrc
20690 Video source generated on GPU using Apple's CoreImage API on OSX.
20692 This video source is a specialized version of the @ref{coreimage} video filter.
20693 Use a core image generator at the beginning of the applied filterchain to
20694 generate the content.
20696 The coreimagesrc video source accepts the following options:
20698 @item list_generators
20699 List all available generators along with all their respective options as well as
20700 possible minimum and maximum values along with the default values.
20702 list_generators=true
20706 Specify the size of the sourced video. For the syntax of this option, check the
20707 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
20708 The default value is @code{320x240}.
20711 Specify the frame rate of the sourced video, as the number of frames
20712 generated per second. It has to be a string in the format
20713 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
20714 number or a valid video frame rate abbreviation. The default value is
20718 Set the sample aspect ratio of the sourced video.
20721 Set the duration of the sourced video. See
20722 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
20723 for the accepted syntax.
20725 If not specified, or the expressed duration is negative, the video is
20726 supposed to be generated forever.
20729 Additionally, all options of the @ref{coreimage} video filter are accepted.
20730 A complete filterchain can be used for further processing of the
20731 generated input without CPU-HOST transfer. See @ref{coreimage} documentation
20732 and examples for details.
20734 @subsection Examples
20739 Use CIQRCodeGenerator to create a QR code for the FFmpeg homepage,
20740 given as complete and escaped command-line for Apple's standard bash shell:
20742 ffmpeg -f lavfi -i coreimagesrc=s=100x100:filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png
20744 This example is equivalent to the QRCode example of @ref{coreimage} without the
20745 need for a nullsrc video source.
20749 @section mandelbrot
20751 Generate a Mandelbrot set fractal, and progressively zoom towards the
20752 point specified with @var{start_x} and @var{start_y}.
20754 This source accepts the following options:
20759 Set the terminal pts value. Default value is 400.
20762 Set the terminal scale value.
20763 Must be a floating point value. Default value is 0.3.
20766 Set the inner coloring mode, that is the algorithm used to draw the
20767 Mandelbrot fractal internal region.
20769 It shall assume one of the following values:
20774 Show time until convergence.
20776 Set color based on point closest to the origin of the iterations.
20781 Default value is @var{mincol}.
20784 Set the bailout value. Default value is 10.0.
20787 Set the maximum of iterations performed by the rendering
20788 algorithm. Default value is 7189.
20791 Set outer coloring mode.
20792 It shall assume one of following values:
20794 @item iteration_count
20795 Set iteration count mode.
20796 @item normalized_iteration_count
20797 set normalized iteration count mode.
20799 Default value is @var{normalized_iteration_count}.
20802 Set frame rate, expressed as number of frames per second. Default
20806 Set frame size. For the syntax of this option, check the @ref{video size syntax,,"Video
20807 size" section in the ffmpeg-utils manual,ffmpeg-utils}. Default value is "640x480".
20810 Set the initial scale value. Default value is 3.0.
20813 Set the initial x position. Must be a floating point value between
20814 -100 and 100. Default value is -0.743643887037158704752191506114774.
20817 Set the initial y position. Must be a floating point value between
20818 -100 and 100. Default value is -0.131825904205311970493132056385139.
20823 Generate various test patterns, as generated by the MPlayer test filter.
20825 The size of the generated video is fixed, and is 256x256.
20826 This source is useful in particular for testing encoding features.
20828 This source accepts the following options:
20833 Specify the frame rate of the sourced video, as the number of frames
20834 generated per second. It has to be a string in the format
20835 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
20836 number or a valid video frame rate abbreviation. The default value is
20840 Set the duration of the sourced video. See
20841 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
20842 for the accepted syntax.
20844 If not specified, or the expressed duration is negative, the video is
20845 supposed to be generated forever.
20849 Set the number or the name of the test to perform. Supported tests are:
20865 Default value is "all", which will cycle through the list of all tests.
20870 mptestsrc=t=dc_luma
20873 will generate a "dc_luma" test pattern.
20875 @section frei0r_src
20877 Provide a frei0r source.
20879 To enable compilation of this filter you need to install the frei0r
20880 header and configure FFmpeg with @code{--enable-frei0r}.
20882 This source accepts the following parameters:
20887 The size of the video to generate. For the syntax of this option, check the
20888 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
20891 The framerate of the generated video. It may be a string of the form
20892 @var{num}/@var{den} or a frame rate abbreviation.
20895 The name to the frei0r source to load. For more information regarding frei0r and
20896 how to set the parameters, read the @ref{frei0r} section in the video filters
20899 @item filter_params
20900 A '|'-separated list of parameters to pass to the frei0r source.
20904 For example, to generate a frei0r partik0l source with size 200x200
20905 and frame rate 10 which is overlaid on the overlay filter main input:
20907 frei0r_src=size=200x200:framerate=10:filter_name=partik0l:filter_params=1234 [overlay]; [in][overlay] overlay
20912 Generate a life pattern.
20914 This source is based on a generalization of John Conway's life game.
20916 The sourced input represents a life grid, each pixel represents a cell
20917 which can be in one of two possible states, alive or dead. Every cell
20918 interacts with its eight neighbours, which are the cells that are
20919 horizontally, vertically, or diagonally adjacent.
20921 At each interaction the grid evolves according to the adopted rule,
20922 which specifies the number of neighbor alive cells which will make a
20923 cell stay alive or born. The @option{rule} option allows one to specify
20926 This source accepts the following options:
20930 Set the file from which to read the initial grid state. In the file,
20931 each non-whitespace character is considered an alive cell, and newline
20932 is used to delimit the end of each row.
20934 If this option is not specified, the initial grid is generated
20938 Set the video rate, that is the number of frames generated per second.
20941 @item random_fill_ratio, ratio
20942 Set the random fill ratio for the initial random grid. It is a
20943 floating point number value ranging from 0 to 1, defaults to 1/PHI.
20944 It is ignored when a file is specified.
20946 @item random_seed, seed
20947 Set the seed for filling the initial random grid, must be an integer
20948 included between 0 and UINT32_MAX. If not specified, or if explicitly
20949 set to -1, the filter will try to use a good random seed on a best
20955 A rule can be specified with a code of the kind "S@var{NS}/B@var{NB}",
20956 where @var{NS} and @var{NB} are sequences of numbers in the range 0-8,
20957 @var{NS} specifies the number of alive neighbor cells which make a
20958 live cell stay alive, and @var{NB} the number of alive neighbor cells
20959 which make a dead cell to become alive (i.e. to "born").
20960 "s" and "b" can be used in place of "S" and "B", respectively.
20962 Alternatively a rule can be specified by an 18-bits integer. The 9
20963 high order bits are used to encode the next cell state if it is alive
20964 for each number of neighbor alive cells, the low order bits specify
20965 the rule for "borning" new cells. Higher order bits encode for an
20966 higher number of neighbor cells.
20967 For example the number 6153 = @code{(12<<9)+9} specifies a stay alive
20968 rule of 12 and a born rule of 9, which corresponds to "S23/B03".
20970 Default value is "S23/B3", which is the original Conway's game of life
20971 rule, and will keep a cell alive if it has 2 or 3 neighbor alive
20972 cells, and will born a new cell if there are three alive cells around
20976 Set the size of the output video. For the syntax of this option, check the
20977 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
20979 If @option{filename} is specified, the size is set by default to the
20980 same size of the input file. If @option{size} is set, it must contain
20981 the size specified in the input file, and the initial grid defined in
20982 that file is centered in the larger resulting area.
20984 If a filename is not specified, the size value defaults to "320x240"
20985 (used for a randomly generated initial grid).
20988 If set to 1, stitch the left and right grid edges together, and the
20989 top and bottom edges also. Defaults to 1.
20992 Set cell mold speed. If set, a dead cell will go from @option{death_color} to
20993 @option{mold_color} with a step of @option{mold}. @option{mold} can have a
20994 value from 0 to 255.
20997 Set the color of living (or new born) cells.
21000 Set the color of dead cells. If @option{mold} is set, this is the first color
21001 used to represent a dead cell.
21004 Set mold color, for definitely dead and moldy cells.
21006 For the syntax of these 3 color options, check the @ref{color syntax,,"Color" section in the
21007 ffmpeg-utils manual,ffmpeg-utils}.
21010 @subsection Examples
21014 Read a grid from @file{pattern}, and center it on a grid of size
21017 life=f=pattern:s=300x300
21021 Generate a random grid of size 200x200, with a fill ratio of 2/3:
21023 life=ratio=2/3:s=200x200
21027 Specify a custom rule for evolving a randomly generated grid:
21033 Full example with slow death effect (mold) using @command{ffplay}:
21035 ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16
21042 @anchor{haldclutsrc}
21045 @anchor{pal100bars}
21046 @anchor{rgbtestsrc}
21048 @anchor{smptehdbars}
21051 @anchor{yuvtestsrc}
21052 @section allrgb, allyuv, color, haldclutsrc, nullsrc, pal75bars, pal100bars, rgbtestsrc, smptebars, smptehdbars, testsrc, testsrc2, yuvtestsrc
21054 The @code{allrgb} source returns frames of size 4096x4096 of all rgb colors.
21056 The @code{allyuv} source returns frames of size 4096x4096 of all yuv colors.
21058 The @code{color} source provides an uniformly colored input.
21060 The @code{haldclutsrc} source provides an identity Hald CLUT. See also
21061 @ref{haldclut} filter.
21063 The @code{nullsrc} source returns unprocessed video frames. It is
21064 mainly useful to be employed in analysis / debugging tools, or as the
21065 source for filters which ignore the input data.
21067 The @code{pal75bars} source generates a color bars pattern, based on
21068 EBU PAL recommendations with 75% color levels.
21070 The @code{pal100bars} source generates a color bars pattern, based on
21071 EBU PAL recommendations with 100% color levels.
21073 The @code{rgbtestsrc} source generates an RGB test pattern useful for
21074 detecting RGB vs BGR issues. You should see a red, green and blue
21075 stripe from top to bottom.
21077 The @code{smptebars} source generates a color bars pattern, based on
21078 the SMPTE Engineering Guideline EG 1-1990.
21080 The @code{smptehdbars} source generates a color bars pattern, based on
21081 the SMPTE RP 219-2002.
21083 The @code{testsrc} source generates a test video pattern, showing a
21084 color pattern, a scrolling gradient and a timestamp. This is mainly
21085 intended for testing purposes.
21087 The @code{testsrc2} source is similar to testsrc, but supports more
21088 pixel formats instead of just @code{rgb24}. This allows using it as an
21089 input for other tests without requiring a format conversion.
21091 The @code{yuvtestsrc} source generates an YUV test pattern. You should
21092 see a y, cb and cr stripe from top to bottom.
21094 The sources accept the following parameters:
21099 Specify the level of the Hald CLUT, only available in the @code{haldclutsrc}
21100 source. A level of @code{N} generates a picture of @code{N*N*N} by @code{N*N*N}
21101 pixels to be used as identity matrix for 3D lookup tables. Each component is
21102 coded on a @code{1/(N*N)} scale.
21105 Specify the color of the source, only available in the @code{color}
21106 source. For the syntax of this option, check the
21107 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
21110 Specify the size of the sourced video. For the syntax of this option, check the
21111 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
21112 The default value is @code{320x240}.
21114 This option is not available with the @code{allrgb}, @code{allyuv}, and
21115 @code{haldclutsrc} filters.
21118 Specify the frame rate of the sourced video, as the number of frames
21119 generated per second. It has to be a string in the format
21120 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
21121 number or a valid video frame rate abbreviation. The default value is
21125 Set the duration of the sourced video. See
21126 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
21127 for the accepted syntax.
21129 If not specified, or the expressed duration is negative, the video is
21130 supposed to be generated forever.
21133 Set the sample aspect ratio of the sourced video.
21136 Specify the alpha (opacity) of the background, only available in the
21137 @code{testsrc2} source. The value must be between 0 (fully transparent) and
21138 255 (fully opaque, the default).
21141 Set the number of decimals to show in the timestamp, only available in the
21142 @code{testsrc} source.
21144 The displayed timestamp value will correspond to the original
21145 timestamp value multiplied by the power of 10 of the specified
21146 value. Default value is 0.
21149 @subsection Examples
21153 Generate a video with a duration of 5.3 seconds, with size
21154 176x144 and a frame rate of 10 frames per second:
21156 testsrc=duration=5.3:size=qcif:rate=10
21160 The following graph description will generate a red source
21161 with an opacity of 0.2, with size "qcif" and a frame rate of 10
21164 color=c=red@@0.2:s=qcif:r=10
21168 If the input content is to be ignored, @code{nullsrc} can be used. The
21169 following command generates noise in the luminance plane by employing
21170 the @code{geq} filter:
21172 nullsrc=s=256x256, geq=random(1)*255:128:128
21176 @subsection Commands
21178 The @code{color} source supports the following commands:
21182 Set the color of the created image. Accepts the same syntax of the
21183 corresponding @option{color} option.
21188 Generate video using an OpenCL program.
21193 OpenCL program source file.
21196 Kernel name in program.
21199 Size of frames to generate. This must be set.
21202 Pixel format to use for the generated frames. This must be set.
21205 Number of frames generated every second. Default value is '25'.
21209 For details of how the program loading works, see the @ref{program_opencl}
21216 Generate a colour ramp by setting pixel values from the position of the pixel
21217 in the output image. (Note that this will work with all pixel formats, but
21218 the generated output will not be the same.)
21220 __kernel void ramp(__write_only image2d_t dst,
21221 unsigned int index)
21223 int2 loc = (int2)(get_global_id(0), get_global_id(1));
21226 val.xy = val.zw = convert_float2(loc) / convert_float2(get_image_dim(dst));
21228 write_imagef(dst, loc, val);
21233 Generate a Sierpinski carpet pattern, panning by a single pixel each frame.
21235 __kernel void sierpinski_carpet(__write_only image2d_t dst,
21236 unsigned int index)
21238 int2 loc = (int2)(get_global_id(0), get_global_id(1));
21240 float4 value = 0.0f;
21241 int x = loc.x + index;
21242 int y = loc.y + index;
21243 while (x > 0 || y > 0) {
21244 if (x % 3 == 1 && y % 3 == 1) {
21252 write_imagef(dst, loc, value);
21258 @section sierpinski
21260 Generate a Sierpinski carpet/triangle fractal, and randomly pan around.
21262 This source accepts the following options:
21266 Set frame size. For the syntax of this option, check the @ref{video size syntax,,"Video
21267 size" section in the ffmpeg-utils manual,ffmpeg-utils}. Default value is "640x480".
21270 Set frame rate, expressed as number of frames per second. Default
21274 Set seed which is used for random panning.
21277 Set max jump for single pan destination. Allowed range is from 1 to 10000.
21280 Set fractal type, can be default @code{carpet} or @code{triangle}.
21283 @c man end VIDEO SOURCES
21285 @chapter Video Sinks
21286 @c man begin VIDEO SINKS
21288 Below is a description of the currently available video sinks.
21290 @section buffersink
21292 Buffer video frames, and make them available to the end of the filter
21295 This sink is mainly intended for programmatic use, in particular
21296 through the interface defined in @file{libavfilter/buffersink.h}
21297 or the options system.
21299 It accepts a pointer to an AVBufferSinkContext structure, which
21300 defines the incoming buffers' formats, to be passed as the opaque
21301 parameter to @code{avfilter_init_filter} for initialization.
21305 Null video sink: do absolutely nothing with the input video. It is
21306 mainly useful as a template and for use in analysis / debugging
21309 @c man end VIDEO SINKS
21311 @chapter Multimedia Filters
21312 @c man begin MULTIMEDIA FILTERS
21314 Below is a description of the currently available multimedia filters.
21318 Convert input audio to a video output, displaying the audio bit scope.
21320 The filter accepts the following options:
21324 Set frame rate, expressed as number of frames per second. Default
21328 Specify the video size for the output. For the syntax of this option, check the
21329 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
21330 Default value is @code{1024x256}.
21333 Specify list of colors separated by space or by '|' which will be used to
21334 draw channels. Unrecognized or missing colors will be replaced
21338 @section ahistogram
21340 Convert input audio to a video output, displaying the volume histogram.
21342 The filter accepts the following options:
21346 Specify how histogram is calculated.
21348 It accepts the following values:
21351 Use single histogram for all channels.
21353 Use separate histogram for each channel.
21355 Default is @code{single}.
21358 Set frame rate, expressed as number of frames per second. Default
21362 Specify the video size for the output. For the syntax of this option, check the
21363 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
21364 Default value is @code{hd720}.
21369 It accepts the following values:
21380 reverse logarithmic
21382 Default is @code{log}.
21385 Set amplitude scale.
21387 It accepts the following values:
21394 Default is @code{log}.
21397 Set how much frames to accumulate in histogram.
21398 Default is 1. Setting this to -1 accumulates all frames.
21401 Set histogram ratio of window height.
21404 Set sonogram sliding.
21406 It accepts the following values:
21409 replace old rows with new ones.
21411 scroll from top to bottom.
21413 Default is @code{replace}.
21416 @section aphasemeter
21418 Measures phase of input audio, which is exported as metadata @code{lavfi.aphasemeter.phase},
21419 representing mean phase of current audio frame. A video output can also be produced and is
21420 enabled by default. The audio is passed through as first output.
21422 Audio will be rematrixed to stereo if it has a different channel layout. Phase value is in
21423 range @code{[-1, 1]} where @code{-1} means left and right channels are completely out of phase
21424 and @code{1} means channels are in phase.
21426 The filter accepts the following options, all related to its video output:
21430 Set the output frame rate. Default value is @code{25}.
21433 Set the video size for the output. For the syntax of this option, check the
21434 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
21435 Default value is @code{800x400}.
21440 Specify the red, green, blue contrast. Default values are @code{2},
21441 @code{7} and @code{1}.
21442 Allowed range is @code{[0, 255]}.
21445 Set color which will be used for drawing median phase. If color is
21446 @code{none} which is default, no median phase value will be drawn.
21449 Enable video output. Default is enabled.
21452 @section avectorscope
21454 Convert input audio to a video output, representing the audio vector
21457 The filter is used to measure the difference between channels of stereo
21458 audio stream. A monaural signal, consisting of identical left and right
21459 signal, results in straight vertical line. Any stereo separation is visible
21460 as a deviation from this line, creating a Lissajous figure.
21461 If the straight (or deviation from it) but horizontal line appears this
21462 indicates that the left and right channels are out of phase.
21464 The filter accepts the following options:
21468 Set the vectorscope mode.
21470 Available values are:
21473 Lissajous rotated by 45 degrees.
21476 Same as above but not rotated.
21479 Shape resembling half of circle.
21482 Default value is @samp{lissajous}.
21485 Set the video size for the output. For the syntax of this option, check the
21486 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
21487 Default value is @code{400x400}.
21490 Set the output frame rate. Default value is @code{25}.
21496 Specify the red, green, blue and alpha contrast. Default values are @code{40},
21497 @code{160}, @code{80} and @code{255}.
21498 Allowed range is @code{[0, 255]}.
21504 Specify the red, green, blue and alpha fade. Default values are @code{15},
21505 @code{10}, @code{5} and @code{5}.
21506 Allowed range is @code{[0, 255]}.
21509 Set the zoom factor. Default value is @code{1}. Allowed range is @code{[0, 10]}.
21510 Values lower than @var{1} will auto adjust zoom factor to maximal possible value.
21513 Set the vectorscope drawing mode.
21515 Available values are:
21518 Draw dot for each sample.
21521 Draw line between previous and current sample.
21524 Default value is @samp{dot}.
21527 Specify amplitude scale of audio samples.
21529 Available values are:
21545 Swap left channel axis with right channel axis.
21555 Mirror only x axis.
21558 Mirror only y axis.
21566 @subsection Examples
21570 Complete example using @command{ffplay}:
21572 ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
21573 [a] avectorscope=zoom=1.3:rc=2:gc=200:bc=10:rf=1:gf=8:bf=7 [out0]'
21577 @section bench, abench
21579 Benchmark part of a filtergraph.
21581 The filter accepts the following options:
21585 Start or stop a timer.
21587 Available values are:
21590 Get the current time, set it as frame metadata (using the key
21591 @code{lavfi.bench.start_time}), and forward the frame to the next filter.
21594 Get the current time and fetch the @code{lavfi.bench.start_time} metadata from
21595 the input frame metadata to get the time difference. Time difference, average,
21596 maximum and minimum time (respectively @code{t}, @code{avg}, @code{max} and
21597 @code{min}) are then printed. The timestamps are expressed in seconds.
21601 @subsection Examples
21605 Benchmark @ref{selectivecolor} filter:
21607 bench=start,selectivecolor=reds=-.2 .12 -.49,bench=stop
21613 Concatenate audio and video streams, joining them together one after the
21616 The filter works on segments of synchronized video and audio streams. All
21617 segments must have the same number of streams of each type, and that will
21618 also be the number of streams at output.
21620 The filter accepts the following options:
21625 Set the number of segments. Default is 2.
21628 Set the number of output video streams, that is also the number of video
21629 streams in each segment. Default is 1.
21632 Set the number of output audio streams, that is also the number of audio
21633 streams in each segment. Default is 0.
21636 Activate unsafe mode: do not fail if segments have a different format.
21640 The filter has @var{v}+@var{a} outputs: first @var{v} video outputs, then
21641 @var{a} audio outputs.
21643 There are @var{n}x(@var{v}+@var{a}) inputs: first the inputs for the first
21644 segment, in the same order as the outputs, then the inputs for the second
21647 Related streams do not always have exactly the same duration, for various
21648 reasons including codec frame size or sloppy authoring. For that reason,
21649 related synchronized streams (e.g. a video and its audio track) should be
21650 concatenated at once. The concat filter will use the duration of the longest
21651 stream in each segment (except the last one), and if necessary pad shorter
21652 audio streams with silence.
21654 For this filter to work correctly, all segments must start at timestamp 0.
21656 All corresponding streams must have the same parameters in all segments; the
21657 filtering system will automatically select a common pixel format for video
21658 streams, and a common sample format, sample rate and channel layout for
21659 audio streams, but other settings, such as resolution, must be converted
21660 explicitly by the user.
21662 Different frame rates are acceptable but will result in variable frame rate
21663 at output; be sure to configure the output file to handle it.
21665 @subsection Examples
21669 Concatenate an opening, an episode and an ending, all in bilingual version
21670 (video in stream 0, audio in streams 1 and 2):
21672 ffmpeg -i opening.mkv -i episode.mkv -i ending.mkv -filter_complex \
21673 '[0:0] [0:1] [0:2] [1:0] [1:1] [1:2] [2:0] [2:1] [2:2]
21674 concat=n=3:v=1:a=2 [v] [a1] [a2]' \
21675 -map '[v]' -map '[a1]' -map '[a2]' output.mkv
21679 Concatenate two parts, handling audio and video separately, using the
21680 (a)movie sources, and adjusting the resolution:
21682 movie=part1.mp4, scale=512:288 [v1] ; amovie=part1.mp4 [a1] ;
21683 movie=part2.mp4, scale=512:288 [v2] ; amovie=part2.mp4 [a2] ;
21684 [v1] [v2] concat [outv] ; [a1] [a2] concat=v=0:a=1 [outa]
21686 Note that a desync will happen at the stitch if the audio and video streams
21687 do not have exactly the same duration in the first file.
21691 @subsection Commands
21693 This filter supports the following commands:
21696 Close the current segment and step to the next one
21699 @section drawgraph, adrawgraph
21701 Draw a graph using input video or audio metadata.
21703 It accepts the following parameters:
21707 Set 1st frame metadata key from which metadata values will be used to draw a graph.
21710 Set 1st foreground color expression.
21713 Set 2nd frame metadata key from which metadata values will be used to draw a graph.
21716 Set 2nd foreground color expression.
21719 Set 3rd frame metadata key from which metadata values will be used to draw a graph.
21722 Set 3rd foreground color expression.
21725 Set 4th frame metadata key from which metadata values will be used to draw a graph.
21728 Set 4th foreground color expression.
21731 Set minimal value of metadata value.
21734 Set maximal value of metadata value.
21737 Set graph background color. Default is white.
21742 Available values for mode is:
21749 Default is @code{line}.
21754 Available values for slide is:
21757 Draw new frame when right border is reached.
21760 Replace old columns with new ones.
21763 Scroll from right to left.
21766 Scroll from left to right.
21769 Draw single picture.
21772 Default is @code{frame}.
21775 Set size of graph video. For the syntax of this option, check the
21776 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
21777 The default value is @code{900x256}.
21779 The foreground color expressions can use the following variables:
21782 Minimal value of metadata value.
21785 Maximal value of metadata value.
21788 Current metadata key value.
21791 The color is defined as 0xAABBGGRR.
21794 Example using metadata from @ref{signalstats} filter:
21796 signalstats,drawgraph=lavfi.signalstats.YAVG:min=0:max=255
21799 Example using metadata from @ref{ebur128} filter:
21801 ebur128=metadata=1,adrawgraph=lavfi.r128.M:min=-120:max=5
21807 EBU R128 scanner filter. This filter takes an audio stream and analyzes its loudness
21808 level. By default, it logs a message at a frequency of 10Hz with the
21809 Momentary loudness (identified by @code{M}), Short-term loudness (@code{S}),
21810 Integrated loudness (@code{I}) and Loudness Range (@code{LRA}).
21812 The filter can only analyze streams which have a sampling rate of 48000 Hz and whose
21813 sample format is double-precision floating point. The input stream will be converted to
21814 this specification, if needed. Users may need to insert aformat and/or aresample filters
21815 after this filter to obtain the original parameters.
21817 The filter also has a video output (see the @var{video} option) with a real
21818 time graph to observe the loudness evolution. The graphic contains the logged
21819 message mentioned above, so it is not printed anymore when this option is set,
21820 unless the verbose logging is set. The main graphing area contains the
21821 short-term loudness (3 seconds of analysis), and the gauge on the right is for
21822 the momentary loudness (400 milliseconds), but can optionally be configured
21823 to instead display short-term loudness (see @var{gauge}).
21825 The green area marks a +/- 1LU target range around the target loudness
21826 (-23LUFS by default, unless modified through @var{target}).
21828 More information about the Loudness Recommendation EBU R128 on
21829 @url{http://tech.ebu.ch/loudness}.
21831 The filter accepts the following options:
21836 Activate the video output. The audio stream is passed unchanged whether this
21837 option is set or no. The video stream will be the first output stream if
21838 activated. Default is @code{0}.
21841 Set the video size. This option is for video only. For the syntax of this
21843 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
21844 Default and minimum resolution is @code{640x480}.
21847 Set the EBU scale meter. Default is @code{9}. Common values are @code{9} and
21848 @code{18}, respectively for EBU scale meter +9 and EBU scale meter +18. Any
21849 other integer value between this range is allowed.
21852 Set metadata injection. If set to @code{1}, the audio input will be segmented
21853 into 100ms output frames, each of them containing various loudness information
21854 in metadata. All the metadata keys are prefixed with @code{lavfi.r128.}.
21856 Default is @code{0}.
21859 Force the frame logging level.
21861 Available values are:
21864 information logging level
21866 verbose logging level
21869 By default, the logging level is set to @var{info}. If the @option{video} or
21870 the @option{metadata} options are set, it switches to @var{verbose}.
21875 Available modes can be cumulated (the option is a @code{flag} type). Possible
21879 Disable any peak mode (default).
21881 Enable sample-peak mode.
21883 Simple peak mode looking for the higher sample value. It logs a message
21884 for sample-peak (identified by @code{SPK}).
21886 Enable true-peak mode.
21888 If enabled, the peak lookup is done on an over-sampled version of the input
21889 stream for better peak accuracy. It logs a message for true-peak.
21890 (identified by @code{TPK}) and true-peak per frame (identified by @code{FTPK}).
21891 This mode requires a build with @code{libswresample}.
21895 Treat mono input files as "dual mono". If a mono file is intended for playback
21896 on a stereo system, its EBU R128 measurement will be perceptually incorrect.
21897 If set to @code{true}, this option will compensate for this effect.
21898 Multi-channel input files are not affected by this option.
21901 Set a specific pan law to be used for the measurement of dual mono files.
21902 This parameter is optional, and has a default value of -3.01dB.
21905 Set a specific target level (in LUFS) used as relative zero in the visualization.
21906 This parameter is optional and has a default value of -23LUFS as specified
21907 by EBU R128. However, material published online may prefer a level of -16LUFS
21908 (e.g. for use with podcasts or video platforms).
21911 Set the value displayed by the gauge. Valid values are @code{momentary} and s
21912 @code{shortterm}. By default the momentary value will be used, but in certain
21913 scenarios it may be more useful to observe the short term value instead (e.g.
21917 Sets the display scale for the loudness. Valid parameters are @code{absolute}
21918 (in LUFS) or @code{relative} (LU) relative to the target. This only affects the
21919 video output, not the summary or continuous log output.
21922 @subsection Examples
21926 Real-time graph using @command{ffplay}, with a EBU scale meter +18:
21928 ffplay -f lavfi -i "amovie=input.mp3,ebur128=video=1:meter=18 [out0][out1]"
21932 Run an analysis with @command{ffmpeg}:
21934 ffmpeg -nostats -i input.mp3 -filter_complex ebur128 -f null -
21938 @section interleave, ainterleave
21940 Temporally interleave frames from several inputs.
21942 @code{interleave} works with video inputs, @code{ainterleave} with audio.
21944 These filters read frames from several inputs and send the oldest
21945 queued frame to the output.
21947 Input streams must have well defined, monotonically increasing frame
21950 In order to submit one frame to output, these filters need to enqueue
21951 at least one frame for each input, so they cannot work in case one
21952 input is not yet terminated and will not receive incoming frames.
21954 For example consider the case when one input is a @code{select} filter
21955 which always drops input frames. The @code{interleave} filter will keep
21956 reading from that input, but it will never be able to send new frames
21957 to output until the input sends an end-of-stream signal.
21959 Also, depending on inputs synchronization, the filters will drop
21960 frames in case one input receives more frames than the other ones, and
21961 the queue is already filled.
21963 These filters accept the following options:
21967 Set the number of different inputs, it is 2 by default.
21970 @subsection Examples
21974 Interleave frames belonging to different streams using @command{ffmpeg}:
21976 ffmpeg -i bambi.avi -i pr0n.mkv -filter_complex "[0:v][1:v] interleave" out.avi
21980 Add flickering blur effect:
21982 select='if(gt(random(0), 0.2), 1, 2)':n=2 [tmp], boxblur=2:2, [tmp] interleave
21986 @section metadata, ametadata
21988 Manipulate frame metadata.
21990 This filter accepts the following options:
21994 Set mode of operation of the filter.
21996 Can be one of the following:
22000 If both @code{value} and @code{key} is set, select frames
22001 which have such metadata. If only @code{key} is set, select
22002 every frame that has such key in metadata.
22005 Add new metadata @code{key} and @code{value}. If key is already available
22009 Modify value of already present key.
22012 If @code{value} is set, delete only keys that have such value.
22013 Otherwise, delete key. If @code{key} is not set, delete all metadata values in
22017 Print key and its value if metadata was found. If @code{key} is not set print all
22018 metadata values available in frame.
22022 Set key used with all modes. Must be set for all modes except @code{print} and @code{delete}.
22025 Set metadata value which will be used. This option is mandatory for
22026 @code{modify} and @code{add} mode.
22029 Which function to use when comparing metadata value and @code{value}.
22031 Can be one of following:
22035 Values are interpreted as strings, returns true if metadata value is same as @code{value}.
22038 Values are interpreted as strings, returns true if metadata value starts with
22039 the @code{value} option string.
22042 Values are interpreted as floats, returns true if metadata value is less than @code{value}.
22045 Values are interpreted as floats, returns true if @code{value} is equal with metadata value.
22048 Values are interpreted as floats, returns true if metadata value is greater than @code{value}.
22051 Values are interpreted as floats, returns true if expression from option @code{expr}
22055 Values are interpreted as strings, returns true if metadata value ends with
22056 the @code{value} option string.
22060 Set expression which is used when @code{function} is set to @code{expr}.
22061 The expression is evaluated through the eval API and can contain the following
22066 Float representation of @code{value} from metadata key.
22069 Float representation of @code{value} as supplied by user in @code{value} option.
22073 If specified in @code{print} mode, output is written to the named file. Instead of
22074 plain filename any writable url can be specified. Filename ``-'' is a shorthand
22075 for standard output. If @code{file} option is not set, output is written to the log
22076 with AV_LOG_INFO loglevel.
22080 @subsection Examples
22084 Print all metadata values for frames with key @code{lavfi.signalstats.YDIF} with values
22087 signalstats,metadata=print:key=lavfi.signalstats.YDIF:value=0:function=expr:expr='between(VALUE1,0,1)'
22090 Print silencedetect output to file @file{metadata.txt}.
22092 silencedetect,ametadata=mode=print:file=metadata.txt
22095 Direct all metadata to a pipe with file descriptor 4.
22097 metadata=mode=print:file='pipe\:4'
22101 @section perms, aperms
22103 Set read/write permissions for the output frames.
22105 These filters are mainly aimed at developers to test direct path in the
22106 following filter in the filtergraph.
22108 The filters accept the following options:
22112 Select the permissions mode.
22114 It accepts the following values:
22117 Do nothing. This is the default.
22119 Set all the output frames read-only.
22121 Set all the output frames directly writable.
22123 Make the frame read-only if writable, and writable if read-only.
22125 Set each output frame read-only or writable randomly.
22129 Set the seed for the @var{random} mode, must be an integer included between
22130 @code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to
22131 @code{-1}, the filter will try to use a good random seed on a best effort
22135 Note: in case of auto-inserted filter between the permission filter and the
22136 following one, the permission might not be received as expected in that
22137 following filter. Inserting a @ref{format} or @ref{aformat} filter before the
22138 perms/aperms filter can avoid this problem.
22140 @section realtime, arealtime
22142 Slow down filtering to match real time approximately.
22144 These filters will pause the filtering for a variable amount of time to
22145 match the output rate with the input timestamps.
22146 They are similar to the @option{re} option to @code{ffmpeg}.
22148 They accept the following options:
22152 Time limit for the pauses. Any pause longer than that will be considered
22153 a timestamp discontinuity and reset the timer. Default is 2 seconds.
22155 Speed factor for processing. The value must be a float larger than zero.
22156 Values larger than 1.0 will result in faster than realtime processing,
22157 smaller will slow processing down. The @var{limit} is automatically adapted
22158 accordingly. Default is 1.0.
22160 A processing speed faster than what is possible without these filters cannot
22165 @section select, aselect
22167 Select frames to pass in output.
22169 This filter accepts the following options:
22174 Set expression, which is evaluated for each input frame.
22176 If the expression is evaluated to zero, the frame is discarded.
22178 If the evaluation result is negative or NaN, the frame is sent to the
22179 first output; otherwise it is sent to the output with index
22180 @code{ceil(val)-1}, assuming that the input index starts from 0.
22182 For example a value of @code{1.2} corresponds to the output with index
22183 @code{ceil(1.2)-1 = 2-1 = 1}, that is the second output.
22186 Set the number of outputs. The output to which to send the selected
22187 frame is based on the result of the evaluation. Default value is 1.
22190 The expression can contain the following constants:
22194 The (sequential) number of the filtered frame, starting from 0.
22197 The (sequential) number of the selected frame, starting from 0.
22199 @item prev_selected_n
22200 The sequential number of the last selected frame. It's NAN if undefined.
22203 The timebase of the input timestamps.
22206 The PTS (Presentation TimeStamp) of the filtered video frame,
22207 expressed in @var{TB} units. It's NAN if undefined.
22210 The PTS of the filtered video frame,
22211 expressed in seconds. It's NAN if undefined.
22214 The PTS of the previously filtered video frame. It's NAN if undefined.
22216 @item prev_selected_pts
22217 The PTS of the last previously filtered video frame. It's NAN if undefined.
22219 @item prev_selected_t
22220 The PTS of the last previously selected video frame, expressed in seconds. It's NAN if undefined.
22223 The PTS of the first video frame in the video. It's NAN if undefined.
22226 The time of the first video frame in the video. It's NAN if undefined.
22228 @item pict_type @emph{(video only)}
22229 The type of the filtered frame. It can assume one of the following
22241 @item interlace_type @emph{(video only)}
22242 The frame interlace type. It can assume one of the following values:
22245 The frame is progressive (not interlaced).
22247 The frame is top-field-first.
22249 The frame is bottom-field-first.
22252 @item consumed_sample_n @emph{(audio only)}
22253 the number of selected samples before the current frame
22255 @item samples_n @emph{(audio only)}
22256 the number of samples in the current frame
22258 @item sample_rate @emph{(audio only)}
22259 the input sample rate
22262 This is 1 if the filtered frame is a key-frame, 0 otherwise.
22265 the position in the file of the filtered frame, -1 if the information
22266 is not available (e.g. for synthetic video)
22268 @item scene @emph{(video only)}
22269 value between 0 and 1 to indicate a new scene; a low value reflects a low
22270 probability for the current frame to introduce a new scene, while a higher
22271 value means the current frame is more likely to be one (see the example below)
22273 @item concatdec_select
22274 The concat demuxer can select only part of a concat input file by setting an
22275 inpoint and an outpoint, but the output packets may not be entirely contained
22276 in the selected interval. By using this variable, it is possible to skip frames
22277 generated by the concat demuxer which are not exactly contained in the selected
22280 This works by comparing the frame pts against the @var{lavf.concat.start_time}
22281 and the @var{lavf.concat.duration} packet metadata values which are also
22282 present in the decoded frames.
22284 The @var{concatdec_select} variable is -1 if the frame pts is at least
22285 start_time and either the duration metadata is missing or the frame pts is less
22286 than start_time + duration, 0 otherwise, and NaN if the start_time metadata is
22289 That basically means that an input frame is selected if its pts is within the
22290 interval set by the concat demuxer.
22294 The default value of the select expression is "1".
22296 @subsection Examples
22300 Select all frames in input:
22305 The example above is the same as:
22317 Select only I-frames:
22319 select='eq(pict_type\,I)'
22323 Select one frame every 100:
22325 select='not(mod(n\,100))'
22329 Select only frames contained in the 10-20 time interval:
22331 select=between(t\,10\,20)
22335 Select only I-frames contained in the 10-20 time interval:
22337 select=between(t\,10\,20)*eq(pict_type\,I)
22341 Select frames with a minimum distance of 10 seconds:
22343 select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)'
22347 Use aselect to select only audio frames with samples number > 100:
22349 aselect='gt(samples_n\,100)'
22353 Create a mosaic of the first scenes:
22355 ffmpeg -i video.avi -vf select='gt(scene\,0.4)',scale=160:120,tile -frames:v 1 preview.png
22358 Comparing @var{scene} against a value between 0.3 and 0.5 is generally a sane
22362 Send even and odd frames to separate outputs, and compose them:
22364 select=n=2:e='mod(n, 2)+1' [odd][even]; [odd] pad=h=2*ih [tmp]; [tmp][even] overlay=y=h
22368 Select useful frames from an ffconcat file which is using inpoints and
22369 outpoints but where the source files are not intra frame only.
22371 ffmpeg -copyts -vsync 0 -segment_time_metadata 1 -i input.ffconcat -vf select=concatdec_select -af aselect=concatdec_select output.avi
22375 @section sendcmd, asendcmd
22377 Send commands to filters in the filtergraph.
22379 These filters read commands to be sent to other filters in the
22382 @code{sendcmd} must be inserted between two video filters,
22383 @code{asendcmd} must be inserted between two audio filters, but apart
22384 from that they act the same way.
22386 The specification of commands can be provided in the filter arguments
22387 with the @var{commands} option, or in a file specified by the
22388 @var{filename} option.
22390 These filters accept the following options:
22393 Set the commands to be read and sent to the other filters.
22395 Set the filename of the commands to be read and sent to the other
22399 @subsection Commands syntax
22401 A commands description consists of a sequence of interval
22402 specifications, comprising a list of commands to be executed when a
22403 particular event related to that interval occurs. The occurring event
22404 is typically the current frame time entering or leaving a given time
22407 An interval is specified by the following syntax:
22409 @var{START}[-@var{END}] @var{COMMANDS};
22412 The time interval is specified by the @var{START} and @var{END} times.
22413 @var{END} is optional and defaults to the maximum time.
22415 The current frame time is considered within the specified interval if
22416 it is included in the interval [@var{START}, @var{END}), that is when
22417 the time is greater or equal to @var{START} and is lesser than
22420 @var{COMMANDS} consists of a sequence of one or more command
22421 specifications, separated by ",", relating to that interval. The
22422 syntax of a command specification is given by:
22424 [@var{FLAGS}] @var{TARGET} @var{COMMAND} @var{ARG}
22427 @var{FLAGS} is optional and specifies the type of events relating to
22428 the time interval which enable sending the specified command, and must
22429 be a non-null sequence of identifier flags separated by "+" or "|" and
22430 enclosed between "[" and "]".
22432 The following flags are recognized:
22435 The command is sent when the current frame timestamp enters the
22436 specified interval. In other words, the command is sent when the
22437 previous frame timestamp was not in the given interval, and the
22441 The command is sent when the current frame timestamp leaves the
22442 specified interval. In other words, the command is sent when the
22443 previous frame timestamp was in the given interval, and the
22447 If @var{FLAGS} is not specified, a default value of @code{[enter]} is
22450 @var{TARGET} specifies the target of the command, usually the name of
22451 the filter class or a specific filter instance name.
22453 @var{COMMAND} specifies the name of the command for the target filter.
22455 @var{ARG} is optional and specifies the optional list of argument for
22456 the given @var{COMMAND}.
22458 Between one interval specification and another, whitespaces, or
22459 sequences of characters starting with @code{#} until the end of line,
22460 are ignored and can be used to annotate comments.
22462 A simplified BNF description of the commands specification syntax
22465 @var{COMMAND_FLAG} ::= "enter" | "leave"
22466 @var{COMMAND_FLAGS} ::= @var{COMMAND_FLAG} [(+|"|")@var{COMMAND_FLAG}]
22467 @var{COMMAND} ::= ["[" @var{COMMAND_FLAGS} "]"] @var{TARGET} @var{COMMAND} [@var{ARG}]
22468 @var{COMMANDS} ::= @var{COMMAND} [,@var{COMMANDS}]
22469 @var{INTERVAL} ::= @var{START}[-@var{END}] @var{COMMANDS}
22470 @var{INTERVALS} ::= @var{INTERVAL}[;@var{INTERVALS}]
22473 @subsection Examples
22477 Specify audio tempo change at second 4:
22479 asendcmd=c='4.0 atempo tempo 1.5',atempo
22483 Target a specific filter instance:
22485 asendcmd=c='4.0 atempo@@my tempo 1.5',atempo@@my
22489 Specify a list of drawtext and hue commands in a file.
22491 # show text in the interval 5-10
22492 5.0-10.0 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=hello world',
22493 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=';
22495 # desaturate the image in the interval 15-20
22496 15.0-20.0 [enter] hue s 0,
22497 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=nocolor',
22499 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=color';
22501 # apply an exponential saturation fade-out effect, starting from time 25
22502 25 [enter] hue s exp(25-t)
22505 A filtergraph allowing to read and process the above command list
22506 stored in a file @file{test.cmd}, can be specified with:
22508 sendcmd=f=test.cmd,drawtext=fontfile=FreeSerif.ttf:text='',hue
22513 @section setpts, asetpts
22515 Change the PTS (presentation timestamp) of the input frames.
22517 @code{setpts} works on video frames, @code{asetpts} on audio frames.
22519 This filter accepts the following options:
22524 The expression which is evaluated for each frame to construct its timestamp.
22528 The expression is evaluated through the eval API and can contain the following
22532 @item FRAME_RATE, FR
22533 frame rate, only defined for constant frame-rate video
22536 The presentation timestamp in input
22539 The count of the input frame for video or the number of consumed samples,
22540 not including the current frame for audio, starting from 0.
22542 @item NB_CONSUMED_SAMPLES
22543 The number of consumed samples, not including the current frame (only
22546 @item NB_SAMPLES, S
22547 The number of samples in the current frame (only audio)
22549 @item SAMPLE_RATE, SR
22550 The audio sample rate.
22553 The PTS of the first frame.
22556 the time in seconds of the first frame
22559 State whether the current frame is interlaced.
22562 the time in seconds of the current frame
22565 original position in the file of the frame, or undefined if undefined
22566 for the current frame
22569 The previous input PTS.
22572 previous input time in seconds
22575 The previous output PTS.
22578 previous output time in seconds
22581 The wallclock (RTC) time in microseconds. This is deprecated, use time(0)
22585 The wallclock (RTC) time at the start of the movie in microseconds.
22588 The timebase of the input timestamps.
22592 @subsection Examples
22596 Start counting PTS from zero
22598 setpts=PTS-STARTPTS
22602 Apply fast motion effect:
22608 Apply slow motion effect:
22614 Set fixed rate of 25 frames per second:
22620 Set fixed rate 25 fps with some jitter:
22622 setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
22626 Apply an offset of 10 seconds to the input PTS:
22632 Generate timestamps from a "live source" and rebase onto the current timebase:
22634 setpts='(RTCTIME - RTCSTART) / (TB * 1000000)'
22638 Generate timestamps by counting samples:
22647 Force color range for the output video frame.
22649 The @code{setrange} filter marks the color range property for the
22650 output frames. It does not change the input frame, but only sets the
22651 corresponding property, which affects how the frame is treated by
22654 The filter accepts the following options:
22659 Available values are:
22663 Keep the same color range property.
22665 @item unspecified, unknown
22666 Set the color range as unspecified.
22668 @item limited, tv, mpeg
22669 Set the color range as limited.
22671 @item full, pc, jpeg
22672 Set the color range as full.
22676 @section settb, asettb
22678 Set the timebase to use for the output frames timestamps.
22679 It is mainly useful for testing timebase configuration.
22681 It accepts the following parameters:
22686 The expression which is evaluated into the output timebase.
22690 The value for @option{tb} is an arithmetic expression representing a
22691 rational. The expression can contain the constants "AVTB" (the default
22692 timebase), "intb" (the input timebase) and "sr" (the sample rate,
22693 audio only). Default value is "intb".
22695 @subsection Examples
22699 Set the timebase to 1/25:
22705 Set the timebase to 1/10:
22711 Set the timebase to 1001/1000:
22717 Set the timebase to 2*intb:
22723 Set the default timebase value:
22730 Convert input audio to a video output representing frequency spectrum
22731 logarithmically using Brown-Puckette constant Q transform algorithm with
22732 direct frequency domain coefficient calculation (but the transform itself
22733 is not really constant Q, instead the Q factor is actually variable/clamped),
22734 with musical tone scale, from E0 to D#10.
22736 The filter accepts the following options:
22740 Specify the video size for the output. It must be even. For the syntax of this option,
22741 check the @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
22742 Default value is @code{1920x1080}.
22745 Set the output frame rate. Default value is @code{25}.
22748 Set the bargraph height. It must be even. Default value is @code{-1} which
22749 computes the bargraph height automatically.
22752 Set the axis height. It must be even. Default value is @code{-1} which computes
22753 the axis height automatically.
22756 Set the sonogram height. It must be even. Default value is @code{-1} which
22757 computes the sonogram height automatically.
22760 Set the fullhd resolution. This option is deprecated, use @var{size}, @var{s}
22761 instead. Default value is @code{1}.
22763 @item sono_v, volume
22764 Specify the sonogram volume expression. It can contain variables:
22767 the @var{bar_v} evaluated expression
22768 @item frequency, freq, f
22769 the frequency where it is evaluated
22770 @item timeclamp, tc
22771 the value of @var{timeclamp} option
22775 @item a_weighting(f)
22776 A-weighting of equal loudness
22777 @item b_weighting(f)
22778 B-weighting of equal loudness
22779 @item c_weighting(f)
22780 C-weighting of equal loudness.
22782 Default value is @code{16}.
22784 @item bar_v, volume2
22785 Specify the bargraph volume expression. It can contain variables:
22788 the @var{sono_v} evaluated expression
22789 @item frequency, freq, f
22790 the frequency where it is evaluated
22791 @item timeclamp, tc
22792 the value of @var{timeclamp} option
22796 @item a_weighting(f)
22797 A-weighting of equal loudness
22798 @item b_weighting(f)
22799 B-weighting of equal loudness
22800 @item c_weighting(f)
22801 C-weighting of equal loudness.
22803 Default value is @code{sono_v}.
22805 @item sono_g, gamma
22806 Specify the sonogram gamma. Lower gamma makes the spectrum more contrast,
22807 higher gamma makes the spectrum having more range. Default value is @code{3}.
22808 Acceptable range is @code{[1, 7]}.
22810 @item bar_g, gamma2
22811 Specify the bargraph gamma. Default value is @code{1}. Acceptable range is
22815 Specify the bargraph transparency level. Lower value makes the bargraph sharper.
22816 Default value is @code{1}. Acceptable range is @code{[0, 1]}.
22818 @item timeclamp, tc
22819 Specify the transform timeclamp. At low frequency, there is trade-off between
22820 accuracy in time domain and frequency domain. If timeclamp is lower,
22821 event in time domain is represented more accurately (such as fast bass drum),
22822 otherwise event in frequency domain is represented more accurately
22823 (such as bass guitar). Acceptable range is @code{[0.002, 1]}. Default value is @code{0.17}.
22826 Set attack time in seconds. The default is @code{0} (disabled). Otherwise, it
22827 limits future samples by applying asymmetric windowing in time domain, useful
22828 when low latency is required. Accepted range is @code{[0, 1]}.
22831 Specify the transform base frequency. Default value is @code{20.01523126408007475},
22832 which is frequency 50 cents below E0. Acceptable range is @code{[10, 100000]}.
22835 Specify the transform end frequency. Default value is @code{20495.59681441799654},
22836 which is frequency 50 cents above D#10. Acceptable range is @code{[10, 100000]}.
22839 This option is deprecated and ignored.
22842 Specify the transform length in time domain. Use this option to control accuracy
22843 trade-off between time domain and frequency domain at every frequency sample.
22844 It can contain variables:
22846 @item frequency, freq, f
22847 the frequency where it is evaluated
22848 @item timeclamp, tc
22849 the value of @var{timeclamp} option.
22851 Default value is @code{384*tc/(384+tc*f)}.
22854 Specify the transform count for every video frame. Default value is @code{6}.
22855 Acceptable range is @code{[1, 30]}.
22858 Specify the transform count for every single pixel. Default value is @code{0},
22859 which makes it computed automatically. Acceptable range is @code{[0, 10]}.
22862 Specify font file for use with freetype to draw the axis. If not specified,
22863 use embedded font. Note that drawing with font file or embedded font is not
22864 implemented with custom @var{basefreq} and @var{endfreq}, use @var{axisfile}
22868 Specify fontconfig pattern. This has lower priority than @var{fontfile}. The
22869 @code{:} in the pattern may be replaced by @code{|} to avoid unnecessary
22873 Specify font color expression. This is arithmetic expression that should return
22874 integer value 0xRRGGBB. It can contain variables:
22876 @item frequency, freq, f
22877 the frequency where it is evaluated
22878 @item timeclamp, tc
22879 the value of @var{timeclamp} option
22884 midi number of frequency f, some midi numbers: E0(16), C1(24), C2(36), A4(69)
22885 @item r(x), g(x), b(x)
22886 red, green, and blue value of intensity x.
22888 Default value is @code{st(0, (midi(f)-59.5)/12);
22889 st(1, if(between(ld(0),0,1), 0.5-0.5*cos(2*PI*ld(0)), 0));
22890 r(1-ld(1)) + b(ld(1))}.
22893 Specify image file to draw the axis. This option override @var{fontfile} and
22894 @var{fontcolor} option.
22897 Enable/disable drawing text to the axis. If it is set to @code{0}, drawing to
22898 the axis is disabled, ignoring @var{fontfile} and @var{axisfile} option.
22899 Default value is @code{1}.
22902 Set colorspace. The accepted values are:
22905 Unspecified (default)
22914 BT.470BG or BT.601-6 625
22917 SMPTE-170M or BT.601-6 525
22923 BT.2020 with non-constant luminance
22928 Set spectrogram color scheme. This is list of floating point values with format
22929 @code{left_r|left_g|left_b|right_r|right_g|right_b}.
22930 The default is @code{1|0.5|0|0|0.5|1}.
22934 @subsection Examples
22938 Playing audio while showing the spectrum:
22940 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt [out0]'
22944 Same as above, but with frame rate 30 fps:
22946 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fps=30:count=5 [out0]'
22950 Playing at 1280x720:
22952 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=s=1280x720:count=4 [out0]'
22956 Disable sonogram display:
22962 A1 and its harmonics: A1, A2, (near)E3, A3:
22964 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),
22965 asplit[a][out1]; [a] showcqt [out0]'
22969 Same as above, but with more accuracy in frequency domain:
22971 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),
22972 asplit[a][out1]; [a] showcqt=timeclamp=0.5 [out0]'
22978 bar_v=10:sono_v=bar_v*a_weighting(f)
22982 Custom gamma, now spectrum is linear to the amplitude.
22988 Custom tlength equation:
22990 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)))'
22994 Custom fontcolor and fontfile, C-note is colored green, others are colored blue:
22996 fontcolor='if(mod(floor(midi(f)+0.5),12), 0x0000FF, g(1))':fontfile=myfont.ttf
23000 Custom font using fontconfig:
23002 font='Courier New,Monospace,mono|bold'
23006 Custom frequency range with custom axis using image file:
23008 axisfile=myaxis.png:basefreq=40:endfreq=10000
23014 Convert input audio to video output representing the audio power spectrum.
23015 Audio amplitude is on Y-axis while frequency is on X-axis.
23017 The filter accepts the following options:
23021 Specify size of video. For the syntax of this option, check the
23022 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23023 Default is @code{1024x512}.
23027 This set how each frequency bin will be represented.
23029 It accepts the following values:
23035 Default is @code{bar}.
23038 Set amplitude scale.
23040 It accepts the following values:
23054 Default is @code{log}.
23057 Set frequency scale.
23059 It accepts the following values:
23068 Reverse logarithmic scale.
23070 Default is @code{lin}.
23073 Set window size. Allowed range is from 16 to 65536.
23075 Default is @code{2048}
23078 Set windowing function.
23080 It accepts the following values:
23103 Default is @code{hanning}.
23106 Set window overlap. In range @code{[0, 1]}. Default is @code{1},
23107 which means optimal overlap for selected window function will be picked.
23110 Set time averaging. Setting this to 0 will display current maximal peaks.
23111 Default is @code{1}, which means time averaging is disabled.
23114 Specify list of colors separated by space or by '|' which will be used to
23115 draw channel frequencies. Unrecognized or missing colors will be replaced
23119 Set channel display mode.
23121 It accepts the following values:
23126 Default is @code{combined}.
23129 Set minimum amplitude used in @code{log} amplitude scaler.
23133 @section showspatial
23135 Convert stereo input audio to a video output, representing the spatial relationship
23136 between two channels.
23138 The filter accepts the following options:
23142 Specify the video size for the output. For the syntax of this option, check the
23143 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23144 Default value is @code{512x512}.
23147 Set window size. Allowed range is from @var{1024} to @var{65536}. Default size is @var{4096}.
23150 Set window function.
23152 It accepts the following values:
23177 Default value is @code{hann}.
23180 Set ratio of overlap window. Default value is @code{0.5}.
23181 When value is @code{1} overlap is set to recommended size for specific
23182 window function currently used.
23185 @anchor{showspectrum}
23186 @section showspectrum
23188 Convert input audio to a video output, representing the audio frequency
23191 The filter accepts the following options:
23195 Specify the video size for the output. For the syntax of this option, check the
23196 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23197 Default value is @code{640x512}.
23200 Specify how the spectrum should slide along the window.
23202 It accepts the following values:
23205 the samples start again on the left when they reach the right
23207 the samples scroll from right to left
23209 frames are only produced when the samples reach the right
23211 the samples scroll from left to right
23214 Default value is @code{replace}.
23217 Specify display mode.
23219 It accepts the following values:
23222 all channels are displayed in the same row
23224 all channels are displayed in separate rows
23227 Default value is @samp{combined}.
23230 Specify display color mode.
23232 It accepts the following values:
23235 each channel is displayed in a separate color
23237 each channel is displayed using the same color scheme
23239 each channel is displayed using the rainbow color scheme
23241 each channel is displayed using the moreland color scheme
23243 each channel is displayed using the nebulae color scheme
23245 each channel is displayed using the fire color scheme
23247 each channel is displayed using the fiery color scheme
23249 each channel is displayed using the fruit color scheme
23251 each channel is displayed using the cool color scheme
23253 each channel is displayed using the magma color scheme
23255 each channel is displayed using the green color scheme
23257 each channel is displayed using the viridis color scheme
23259 each channel is displayed using the plasma color scheme
23261 each channel is displayed using the cividis color scheme
23263 each channel is displayed using the terrain color scheme
23266 Default value is @samp{channel}.
23269 Specify scale used for calculating intensity color values.
23271 It accepts the following values:
23276 square root, default
23287 Default value is @samp{sqrt}.
23290 Specify frequency scale.
23292 It accepts the following values:
23300 Default value is @samp{lin}.
23303 Set saturation modifier for displayed colors. Negative values provide
23304 alternative color scheme. @code{0} is no saturation at all.
23305 Saturation must be in [-10.0, 10.0] range.
23306 Default value is @code{1}.
23309 Set window function.
23311 It accepts the following values:
23336 Default value is @code{hann}.
23339 Set orientation of time vs frequency axis. Can be @code{vertical} or
23340 @code{horizontal}. Default is @code{vertical}.
23343 Set ratio of overlap window. Default value is @code{0}.
23344 When value is @code{1} overlap is set to recommended size for specific
23345 window function currently used.
23348 Set scale gain for calculating intensity color values.
23349 Default value is @code{1}.
23352 Set which data to display. Can be @code{magnitude}, default or @code{phase}.
23355 Set color rotation, must be in [-1.0, 1.0] range.
23356 Default value is @code{0}.
23359 Set start frequency from which to display spectrogram. Default is @code{0}.
23362 Set stop frequency to which to display spectrogram. Default is @code{0}.
23365 Set upper frame rate limit. Default is @code{auto}, unlimited.
23368 Draw time and frequency axes and legends. Default is disabled.
23371 The usage is very similar to the showwaves filter; see the examples in that
23374 @subsection Examples
23378 Large window with logarithmic color scaling:
23380 showspectrum=s=1280x480:scale=log
23384 Complete example for a colored and sliding spectrum per channel using @command{ffplay}:
23386 ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
23387 [a] showspectrum=mode=separate:color=intensity:slide=1:scale=cbrt [out0]'
23391 @section showspectrumpic
23393 Convert input audio to a single video frame, representing the audio frequency
23396 The filter accepts the following options:
23400 Specify the video size for the output. For the syntax of this option, check the
23401 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23402 Default value is @code{4096x2048}.
23405 Specify display mode.
23407 It accepts the following values:
23410 all channels are displayed in the same row
23412 all channels are displayed in separate rows
23414 Default value is @samp{combined}.
23417 Specify display color mode.
23419 It accepts the following values:
23422 each channel is displayed in a separate color
23424 each channel is displayed using the same color scheme
23426 each channel is displayed using the rainbow color scheme
23428 each channel is displayed using the moreland color scheme
23430 each channel is displayed using the nebulae color scheme
23432 each channel is displayed using the fire color scheme
23434 each channel is displayed using the fiery color scheme
23436 each channel is displayed using the fruit color scheme
23438 each channel is displayed using the cool color scheme
23440 each channel is displayed using the magma color scheme
23442 each channel is displayed using the green color scheme
23444 each channel is displayed using the viridis color scheme
23446 each channel is displayed using the plasma color scheme
23448 each channel is displayed using the cividis color scheme
23450 each channel is displayed using the terrain color scheme
23452 Default value is @samp{intensity}.
23455 Specify scale used for calculating intensity color values.
23457 It accepts the following values:
23462 square root, default
23472 Default value is @samp{log}.
23475 Specify frequency scale.
23477 It accepts the following values:
23485 Default value is @samp{lin}.
23488 Set saturation modifier for displayed colors. Negative values provide
23489 alternative color scheme. @code{0} is no saturation at all.
23490 Saturation must be in [-10.0, 10.0] range.
23491 Default value is @code{1}.
23494 Set window function.
23496 It accepts the following values:
23520 Default value is @code{hann}.
23523 Set orientation of time vs frequency axis. Can be @code{vertical} or
23524 @code{horizontal}. Default is @code{vertical}.
23527 Set scale gain for calculating intensity color values.
23528 Default value is @code{1}.
23531 Draw time and frequency axes and legends. Default is enabled.
23534 Set color rotation, must be in [-1.0, 1.0] range.
23535 Default value is @code{0}.
23538 Set start frequency from which to display spectrogram. Default is @code{0}.
23541 Set stop frequency to which to display spectrogram. Default is @code{0}.
23544 @subsection Examples
23548 Extract an audio spectrogram of a whole audio track
23549 in a 1024x1024 picture using @command{ffmpeg}:
23551 ffmpeg -i audio.flac -lavfi showspectrumpic=s=1024x1024 spectrogram.png
23555 @section showvolume
23557 Convert input audio volume to a video output.
23559 The filter accepts the following options:
23566 Set border width, allowed range is [0, 5]. Default is 1.
23569 Set channel width, allowed range is [80, 8192]. Default is 400.
23572 Set channel height, allowed range is [1, 900]. Default is 20.
23575 Set fade, allowed range is [0, 1]. Default is 0.95.
23578 Set volume color expression.
23580 The expression can use the following variables:
23584 Current max volume of channel in dB.
23590 Current channel number, starting from 0.
23594 If set, displays channel names. Default is enabled.
23597 If set, displays volume values. Default is enabled.
23600 Set orientation, can be horizontal: @code{h} or vertical: @code{v},
23601 default is @code{h}.
23604 Set step size, allowed range is [0, 5]. Default is 0, which means
23608 Set background opacity, allowed range is [0, 1]. Default is 0.
23611 Set metering mode, can be peak: @code{p} or rms: @code{r},
23612 default is @code{p}.
23615 Set display scale, can be linear: @code{lin} or log: @code{log},
23616 default is @code{lin}.
23620 If set to > 0., display a line for the max level
23621 in the previous seconds.
23622 default is disabled: @code{0.}
23625 The color of the max line. Use when @code{dm} option is set to > 0.
23626 default is: @code{orange}
23631 Convert input audio to a video output, representing the samples waves.
23633 The filter accepts the following options:
23637 Specify the video size for the output. For the syntax of this option, check the
23638 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23639 Default value is @code{600x240}.
23644 Available values are:
23647 Draw a point for each sample.
23650 Draw a vertical line for each sample.
23653 Draw a point for each sample and a line between them.
23656 Draw a centered vertical line for each sample.
23659 Default value is @code{point}.
23662 Set the number of samples which are printed on the same column. A
23663 larger value will decrease the frame rate. Must be a positive
23664 integer. This option can be set only if the value for @var{rate}
23665 is not explicitly specified.
23668 Set the (approximate) output frame rate. This is done by setting the
23669 option @var{n}. Default value is "25".
23671 @item split_channels
23672 Set if channels should be drawn separately or overlap. Default value is 0.
23675 Set colors separated by '|' which are going to be used for drawing of each channel.
23678 Set amplitude scale.
23680 Available values are:
23698 Set the draw mode. This is mostly useful to set for high @var{n}.
23700 Available values are:
23703 Scale pixel values for each drawn sample.
23706 Draw every sample directly.
23709 Default value is @code{scale}.
23712 @subsection Examples
23716 Output the input file audio and the corresponding video representation
23719 amovie=a.mp3,asplit[out0],showwaves[out1]
23723 Create a synthetic signal and show it with showwaves, forcing a
23724 frame rate of 30 frames per second:
23726 aevalsrc=sin(1*2*PI*t)*sin(880*2*PI*t):cos(2*PI*200*t),asplit[out0],showwaves=r=30[out1]
23730 @section showwavespic
23732 Convert input audio to a single video frame, representing the samples waves.
23734 The filter accepts the following options:
23738 Specify the video size for the output. For the syntax of this option, check the
23739 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23740 Default value is @code{600x240}.
23742 @item split_channels
23743 Set if channels should be drawn separately or overlap. Default value is 0.
23746 Set colors separated by '|' which are going to be used for drawing of each channel.
23749 Set amplitude scale.
23751 Available values are:
23771 Available values are:
23774 Scale pixel values for each drawn sample.
23777 Draw every sample directly.
23780 Default value is @code{scale}.
23783 @subsection Examples
23787 Extract a channel split representation of the wave form of a whole audio track
23788 in a 1024x800 picture using @command{ffmpeg}:
23790 ffmpeg -i audio.flac -lavfi showwavespic=split_channels=1:s=1024x800 waveform.png
23794 @section sidedata, asidedata
23796 Delete frame side data, or select frames based on it.
23798 This filter accepts the following options:
23802 Set mode of operation of the filter.
23804 Can be one of the following:
23808 Select every frame with side data of @code{type}.
23811 Delete side data of @code{type}. If @code{type} is not set, delete all side
23817 Set side data type used with all modes. Must be set for @code{select} mode. For
23818 the list of frame side data types, refer to the @code{AVFrameSideDataType} enum
23819 in @file{libavutil/frame.h}. For example, to choose
23820 @code{AV_FRAME_DATA_PANSCAN} side data, you must specify @code{PANSCAN}.
23824 @section spectrumsynth
23826 Synthesize audio from 2 input video spectrums, first input stream represents
23827 magnitude across time and second represents phase across time.
23828 The filter will transform from frequency domain as displayed in videos back
23829 to time domain as presented in audio output.
23831 This filter is primarily created for reversing processed @ref{showspectrum}
23832 filter outputs, but can synthesize sound from other spectrograms too.
23833 But in such case results are going to be poor if the phase data is not
23834 available, because in such cases phase data need to be recreated, usually
23835 it's just recreated from random noise.
23836 For best results use gray only output (@code{channel} color mode in
23837 @ref{showspectrum} filter) and @code{log} scale for magnitude video and
23838 @code{lin} scale for phase video. To produce phase, for 2nd video, use
23839 @code{data} option. Inputs videos should generally use @code{fullframe}
23840 slide mode as that saves resources needed for decoding video.
23842 The filter accepts the following options:
23846 Specify sample rate of output audio, the sample rate of audio from which
23847 spectrum was generated may differ.
23850 Set number of channels represented in input video spectrums.
23853 Set scale which was used when generating magnitude input spectrum.
23854 Can be @code{lin} or @code{log}. Default is @code{log}.
23857 Set slide which was used when generating inputs spectrums.
23858 Can be @code{replace}, @code{scroll}, @code{fullframe} or @code{rscroll}.
23859 Default is @code{fullframe}.
23862 Set window function used for resynthesis.
23865 Set window overlap. In range @code{[0, 1]}. Default is @code{1},
23866 which means optimal overlap for selected window function will be picked.
23869 Set orientation of input videos. Can be @code{vertical} or @code{horizontal}.
23870 Default is @code{vertical}.
23873 @subsection Examples
23877 First create magnitude and phase videos from audio, assuming audio is stereo with 44100 sample rate,
23878 then resynthesize videos back to audio with spectrumsynth:
23880 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
23881 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
23882 ffmpeg -i magnitude.nut -i phase.nut -lavfi spectrumsynth=channels=2:sample_rate=44100:win_func=hann:overlap=0.875:slide=fullframe output.flac
23886 @section split, asplit
23888 Split input into several identical outputs.
23890 @code{asplit} works with audio input, @code{split} with video.
23892 The filter accepts a single parameter which specifies the number of outputs. If
23893 unspecified, it defaults to 2.
23895 @subsection Examples
23899 Create two separate outputs from the same input:
23901 [in] split [out0][out1]
23905 To create 3 or more outputs, you need to specify the number of
23908 [in] asplit=3 [out0][out1][out2]
23912 Create two separate outputs from the same input, one cropped and
23915 [in] split [splitout1][splitout2];
23916 [splitout1] crop=100:100:0:0 [cropout];
23917 [splitout2] pad=200:200:100:100 [padout];
23921 Create 5 copies of the input audio with @command{ffmpeg}:
23923 ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT
23929 Receive commands sent through a libzmq client, and forward them to
23930 filters in the filtergraph.
23932 @code{zmq} and @code{azmq} work as a pass-through filters. @code{zmq}
23933 must be inserted between two video filters, @code{azmq} between two
23934 audio filters. Both are capable to send messages to any filter type.
23936 To enable these filters you need to install the libzmq library and
23937 headers and configure FFmpeg with @code{--enable-libzmq}.
23939 For more information about libzmq see:
23940 @url{http://www.zeromq.org/}
23942 The @code{zmq} and @code{azmq} filters work as a libzmq server, which
23943 receives messages sent through a network interface defined by the
23944 @option{bind_address} (or the abbreviation "@option{b}") option.
23945 Default value of this option is @file{tcp://localhost:5555}. You may
23946 want to alter this value to your needs, but do not forget to escape any
23947 ':' signs (see @ref{filtergraph escaping}).
23949 The received message must be in the form:
23951 @var{TARGET} @var{COMMAND} [@var{ARG}]
23954 @var{TARGET} specifies the target of the command, usually the name of
23955 the filter class or a specific filter instance name. The default
23956 filter instance name uses the pattern @samp{Parsed_<filter_name>_<index>},
23957 but you can override this by using the @samp{filter_name@@id} syntax
23958 (see @ref{Filtergraph syntax}).
23960 @var{COMMAND} specifies the name of the command for the target filter.
23962 @var{ARG} is optional and specifies the optional argument list for the
23963 given @var{COMMAND}.
23965 Upon reception, the message is processed and the corresponding command
23966 is injected into the filtergraph. Depending on the result, the filter
23967 will send a reply to the client, adopting the format:
23969 @var{ERROR_CODE} @var{ERROR_REASON}
23973 @var{MESSAGE} is optional.
23975 @subsection Examples
23977 Look at @file{tools/zmqsend} for an example of a zmq client which can
23978 be used to send commands processed by these filters.
23980 Consider the following filtergraph generated by @command{ffplay}.
23981 In this example the last overlay filter has an instance name. All other
23982 filters will have default instance names.
23985 ffplay -dumpgraph 1 -f lavfi "
23986 color=s=100x100:c=red [l];
23987 color=s=100x100:c=blue [r];
23988 nullsrc=s=200x100, zmq [bg];
23989 [bg][l] overlay [bg+l];
23990 [bg+l][r] overlay@@my=x=100 "
23993 To change the color of the left side of the video, the following
23994 command can be used:
23996 echo Parsed_color_0 c yellow | tools/zmqsend
23999 To change the right side:
24001 echo Parsed_color_1 c pink | tools/zmqsend
24004 To change the position of the right side:
24006 echo overlay@@my x 150 | tools/zmqsend
24010 @c man end MULTIMEDIA FILTERS
24012 @chapter Multimedia Sources
24013 @c man begin MULTIMEDIA SOURCES
24015 Below is a description of the currently available multimedia sources.
24019 This is the same as @ref{movie} source, except it selects an audio
24025 Read audio and/or video stream(s) from a movie container.
24027 It accepts the following parameters:
24031 The name of the resource to read (not necessarily a file; it can also be a
24032 device or a stream accessed through some protocol).
24034 @item format_name, f
24035 Specifies the format assumed for the movie to read, and can be either
24036 the name of a container or an input device. If not specified, the
24037 format is guessed from @var{movie_name} or by probing.
24039 @item seek_point, sp
24040 Specifies the seek point in seconds. The frames will be output
24041 starting from this seek point. The parameter is evaluated with
24042 @code{av_strtod}, so the numerical value may be suffixed by an IS
24043 postfix. The default value is "0".
24046 Specifies the streams to read. Several streams can be specified,
24047 separated by "+". The source will then have as many outputs, in the
24048 same order. The syntax is explained in the @ref{Stream specifiers,,"Stream specifiers"
24049 section in the ffmpeg manual,ffmpeg}. Two special names, "dv" and "da" specify
24050 respectively the default (best suited) video and audio stream. Default
24051 is "dv", or "da" if the filter is called as "amovie".
24053 @item stream_index, si
24054 Specifies the index of the video stream to read. If the value is -1,
24055 the most suitable video stream will be automatically selected. The default
24056 value is "-1". Deprecated. If the filter is called "amovie", it will select
24057 audio instead of video.
24060 Specifies how many times to read the stream in sequence.
24061 If the value is 0, the stream will be looped infinitely.
24062 Default value is "1".
24064 Note that when the movie is looped the source timestamps are not
24065 changed, so it will generate non monotonically increasing timestamps.
24067 @item discontinuity
24068 Specifies the time difference between frames above which the point is
24069 considered a timestamp discontinuity which is removed by adjusting the later
24073 It allows overlaying a second video on top of the main input of
24074 a filtergraph, as shown in this graph:
24076 input -----------> deltapts0 --> overlay --> output
24079 movie --> scale--> deltapts1 -------+
24081 @subsection Examples
24085 Skip 3.2 seconds from the start of the AVI file in.avi, and overlay it
24086 on top of the input labelled "in":
24088 movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [over];
24089 [in] setpts=PTS-STARTPTS [main];
24090 [main][over] overlay=16:16 [out]
24094 Read from a video4linux2 device, and overlay it on top of the input
24097 movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [over];
24098 [in] setpts=PTS-STARTPTS [main];
24099 [main][over] overlay=16:16 [out]
24103 Read the first video stream and the audio stream with id 0x81 from
24104 dvd.vob; the video is connected to the pad named "video" and the audio is
24105 connected to the pad named "audio":
24107 movie=dvd.vob:s=v:0+#0x81 [video] [audio]
24111 @subsection Commands
24113 Both movie and amovie support the following commands:
24116 Perform seek using "av_seek_frame".
24117 The syntax is: seek @var{stream_index}|@var{timestamp}|@var{flags}
24120 @var{stream_index}: If stream_index is -1, a default
24121 stream is selected, and @var{timestamp} is automatically converted
24122 from AV_TIME_BASE units to the stream specific time_base.
24124 @var{timestamp}: Timestamp in AVStream.time_base units
24125 or, if no stream is specified, in AV_TIME_BASE units.
24127 @var{flags}: Flags which select direction and seeking mode.
24131 Get movie duration in AV_TIME_BASE units.
24135 @c man end MULTIMEDIA SOURCES