1 @chapter Filtering Introduction
2 @c man begin FILTERING INTRODUCTION
4 Filtering in FFmpeg is enabled through the libavfilter library.
6 In libavfilter, a filter can have multiple inputs and multiple
8 To illustrate the sorts of things that are possible, we consider the
13 input --> split ---------------------> overlay --> output
16 +-----> crop --> vflip -------+
19 This filtergraph splits the input stream in two streams, then sends one
20 stream through the crop filter and the vflip filter, before merging it
21 back with the other stream by overlaying it on top. You can use the
22 following command to achieve this:
25 ffmpeg -i INPUT -vf "split [main][tmp]; [tmp] crop=iw:ih/2:0:0, vflip [flip]; [main][flip] overlay=0:H/2" OUTPUT
28 The result will be that the top half of the video is mirrored
29 onto the bottom half of the output video.
31 Filters in the same linear chain are separated by commas, and distinct
32 linear chains of filters are separated by semicolons. In our example,
33 @var{crop,vflip} are in one linear chain, @var{split} and
34 @var{overlay} are separately in another. The points where the linear
35 chains join are labelled by names enclosed in square brackets. In the
36 example, the split filter generates two outputs that are associated to
37 the labels @var{[main]} and @var{[tmp]}.
39 The stream sent to the second output of @var{split}, labelled as
40 @var{[tmp]}, is processed through the @var{crop} filter, which crops
41 away the lower half part of the video, and then vertically flipped. The
42 @var{overlay} filter takes in input the first unchanged output of the
43 split filter (which was labelled as @var{[main]}), and overlay on its
44 lower half the output generated by the @var{crop,vflip} filterchain.
46 Some filters take in input a list of parameters: they are specified
47 after the filter name and an equal sign, and are separated from each other
50 There exist so-called @var{source filters} that do not have an
51 audio/video input, and @var{sink filters} that will not have audio/video
54 @c man end FILTERING INTRODUCTION
57 @c man begin GRAPH2DOT
59 The @file{graph2dot} program included in the FFmpeg @file{tools}
60 directory can be used to parse a filtergraph description and issue a
61 corresponding textual representation in the dot language.
68 to see how to use @file{graph2dot}.
70 You can then pass the dot description to the @file{dot} program (from
71 the graphviz suite of programs) and obtain a graphical representation
74 For example the sequence of commands:
76 echo @var{GRAPH_DESCRIPTION} | \
77 tools/graph2dot -o graph.tmp && \
78 dot -Tpng graph.tmp -o graph.png && \
82 can be used to create and display an image representing the graph
83 described by the @var{GRAPH_DESCRIPTION} string. Note that this string must be
84 a complete self-contained graph, with its inputs and outputs explicitly defined.
85 For example if your command line is of the form:
87 ffmpeg -i infile -vf scale=640:360 outfile
89 your @var{GRAPH_DESCRIPTION} string will need to be of the form:
91 nullsrc,scale=640:360,nullsink
93 you may also need to set the @var{nullsrc} parameters and add a @var{format}
94 filter in order to simulate a specific input file.
98 @chapter Filtergraph description
99 @c man begin FILTERGRAPH DESCRIPTION
101 A filtergraph is a directed graph of connected filters. It can contain
102 cycles, and there can be multiple links between a pair of
103 filters. Each link has one input pad on one side connecting it to one
104 filter from which it takes its input, and one output pad on the other
105 side connecting it to one filter accepting its output.
107 Each filter in a filtergraph is an instance of a filter class
108 registered in the application, which defines the features and the
109 number of input and output pads of the filter.
111 A filter with no input pads is called a "source", and a filter with no
112 output pads is called a "sink".
114 @anchor{Filtergraph syntax}
115 @section Filtergraph syntax
117 A filtergraph has a textual representation, which is recognized by the
118 @option{-filter}/@option{-vf}/@option{-af} and
119 @option{-filter_complex} options in @command{ffmpeg} and
120 @option{-vf}/@option{-af} in @command{ffplay}, and by the
121 @code{avfilter_graph_parse_ptr()} function defined in
122 @file{libavfilter/avfilter.h}.
124 A filterchain consists of a sequence of connected filters, each one
125 connected to the previous one in the sequence. A filterchain is
126 represented by a list of ","-separated filter descriptions.
128 A filtergraph consists of a sequence of filterchains. A sequence of
129 filterchains is represented by a list of ";"-separated filterchain
132 A filter is represented by a string of the form:
133 [@var{in_link_1}]...[@var{in_link_N}]@var{filter_name}@@@var{id}=@var{arguments}[@var{out_link_1}]...[@var{out_link_M}]
135 @var{filter_name} is the name of the filter class of which the
136 described filter is an instance of, and has to be the name of one of
137 the filter classes registered in the program optionally followed by "@@@var{id}".
138 The name of the filter class is optionally followed by a string
141 @var{arguments} is a string which contains the parameters used to
142 initialize the filter instance. It may have one of two forms:
146 A ':'-separated list of @var{key=value} pairs.
149 A ':'-separated list of @var{value}. In this case, the keys are assumed to be
150 the option names in the order they are declared. E.g. the @code{fade} filter
151 declares three options in this order -- @option{type}, @option{start_frame} and
152 @option{nb_frames}. Then the parameter list @var{in:0:30} means that the value
153 @var{in} is assigned to the option @option{type}, @var{0} to
154 @option{start_frame} and @var{30} to @option{nb_frames}.
157 A ':'-separated list of mixed direct @var{value} and long @var{key=value}
158 pairs. The direct @var{value} must precede the @var{key=value} pairs, and
159 follow the same constraints order of the previous point. The following
160 @var{key=value} pairs can be set in any preferred order.
164 If the option value itself is a list of items (e.g. the @code{format} filter
165 takes a list of pixel formats), the items in the list are usually separated by
168 The list of arguments can be quoted using the character @samp{'} as initial
169 and ending mark, and the character @samp{\} for escaping the characters
170 within the quoted text; otherwise the argument string is considered
171 terminated when the next special character (belonging to the set
172 @samp{[]=;,}) is encountered.
174 The name and arguments of the filter are optionally preceded and
175 followed by a list of link labels.
176 A link label allows one to name a link and associate it to a filter output
177 or input pad. The preceding labels @var{in_link_1}
178 ... @var{in_link_N}, are associated to the filter input pads,
179 the following labels @var{out_link_1} ... @var{out_link_M}, are
180 associated to the output pads.
182 When two link labels with the same name are found in the
183 filtergraph, a link between the corresponding input and output pad is
186 If an output pad is not labelled, it is linked by default to the first
187 unlabelled input pad of the next filter in the filterchain.
188 For example in the filterchain
190 nullsrc, split[L1], [L2]overlay, nullsink
192 the split filter instance has two output pads, and the overlay filter
193 instance two input pads. The first output pad of split is labelled
194 "L1", the first input pad of overlay is labelled "L2", and the second
195 output pad of split is linked to the second input pad of overlay,
196 which are both unlabelled.
198 In a filter description, if the input label of the first filter is not
199 specified, "in" is assumed; if the output label of the last filter is not
200 specified, "out" is assumed.
202 In a complete filterchain all the unlabelled filter input and output
203 pads must be connected. A filtergraph is considered valid if all the
204 filter input and output pads of all the filterchains are connected.
206 Libavfilter will automatically insert @ref{scale} filters where format
207 conversion is required. It is possible to specify swscale flags
208 for those automatically inserted scalers by prepending
209 @code{sws_flags=@var{flags};}
210 to the filtergraph description.
212 Here is a BNF description of the filtergraph syntax:
214 @var{NAME} ::= sequence of alphanumeric characters and '_'
215 @var{FILTER_NAME} ::= @var{NAME}["@@"@var{NAME}]
216 @var{LINKLABEL} ::= "[" @var{NAME} "]"
217 @var{LINKLABELS} ::= @var{LINKLABEL} [@var{LINKLABELS}]
218 @var{FILTER_ARGUMENTS} ::= sequence of chars (possibly quoted)
219 @var{FILTER} ::= [@var{LINKLABELS}] @var{FILTER_NAME} ["=" @var{FILTER_ARGUMENTS}] [@var{LINKLABELS}]
220 @var{FILTERCHAIN} ::= @var{FILTER} [,@var{FILTERCHAIN}]
221 @var{FILTERGRAPH} ::= [sws_flags=@var{flags};] @var{FILTERCHAIN} [;@var{FILTERGRAPH}]
224 @anchor{filtergraph escaping}
225 @section Notes on filtergraph escaping
227 Filtergraph description composition entails several levels of
228 escaping. See @ref{quoting_and_escaping,,the "Quoting and escaping"
229 section in the ffmpeg-utils(1) manual,ffmpeg-utils} for more
230 information about the employed escaping procedure.
232 A first level escaping affects the content of each filter option
233 value, which may contain the special character @code{:} used to
234 separate values, or one of the escaping characters @code{\'}.
236 A second level escaping affects the whole filter description, which
237 may contain the escaping characters @code{\'} or the special
238 characters @code{[],;} used by the filtergraph description.
240 Finally, when you specify a filtergraph on a shell commandline, you
241 need to perform a third level escaping for the shell special
242 characters contained within it.
244 For example, consider the following string to be embedded in
245 the @ref{drawtext} filter description @option{text} value:
247 this is a 'string': may contain one, or more, special characters
250 This string contains the @code{'} special escaping character, and the
251 @code{:} special character, so it needs to be escaped in this way:
253 text=this is a \'string\'\: may contain one, or more, special characters
256 A second level of escaping is required when embedding the filter
257 description in a filtergraph description, in order to escape all the
258 filtergraph special characters. Thus the example above becomes:
260 drawtext=text=this is a \\\'string\\\'\\: may contain one\, or more\, special characters
262 (note that in addition to the @code{\'} escaping special characters,
263 also @code{,} needs to be escaped).
265 Finally an additional level of escaping is needed when writing the
266 filtergraph description in a shell command, which depends on the
267 escaping rules of the adopted shell. For example, assuming that
268 @code{\} is special and needs to be escaped with another @code{\}, the
269 previous string will finally result in:
271 -vf "drawtext=text=this is a \\\\\\'string\\\\\\'\\\\: may contain one\\, or more\\, special characters"
274 @chapter Timeline editing
276 Some filters support a generic @option{enable} option. For the filters
277 supporting timeline editing, this option can be set to an expression which is
278 evaluated before sending a frame to the filter. If the evaluation is non-zero,
279 the filter will be enabled, otherwise the frame will be sent unchanged to the
280 next filter in the filtergraph.
282 The expression accepts the following values:
285 timestamp expressed in seconds, NAN if the input timestamp is unknown
288 sequential number of the input frame, starting from 0
291 the position in the file of the input frame, NAN if unknown
295 width and height of the input frame if video
298 Additionally, these filters support an @option{enable} command that can be used
299 to re-define the expression.
301 Like any other filtering option, the @option{enable} option follows the same
304 For example, to enable a blur filter (@ref{smartblur}) from 10 seconds to 3
305 minutes, and a @ref{curves} filter starting at 3 seconds:
307 smartblur = enable='between(t,10,3*60)',
308 curves = enable='gte(t,3)' : preset=cross_process
311 See @code{ffmpeg -filters} to view which filters have timeline support.
313 @c man end FILTERGRAPH DESCRIPTION
316 @chapter Changing options at runtime with a command
318 Some options can be changed during the operation of the filter using
319 a command. These options are marked 'T' on the output of
320 @command{ffmpeg} @option{-h filter=<name of filter>}.
321 The name of the command is the name of the option and the argument is
325 @chapter Options for filters with several inputs (framesync)
326 @c man begin OPTIONS FOR FILTERS WITH SEVERAL INPUTS
328 Some filters with several inputs support a common set of options.
329 These options can only be set by name, not with the short notation.
333 The action to take when EOF is encountered on the secondary input; it accepts
334 one of the following values:
338 Repeat the last frame (the default).
342 Pass the main input through.
346 If set to 1, force the output to terminate when the shortest input
347 terminates. Default value is 0.
350 If set to 1, force the filter to extend the last frame of secondary streams
351 until the end of the primary stream. A value of 0 disables this behavior.
355 @c man end OPTIONS FOR FILTERS WITH SEVERAL INPUTS
357 @chapter Audio Filters
358 @c man begin AUDIO FILTERS
360 When you configure your FFmpeg build, you can disable any of the
361 existing filters using @code{--disable-filters}.
362 The configure output will show the audio filters included in your
365 Below is a description of the currently available audio filters.
369 A compressor is mainly used to reduce the dynamic range of a signal.
370 Especially modern music is mostly compressed at a high ratio to
371 improve the overall loudness. It's done to get the highest attention
372 of a listener, "fatten" the sound and bring more "power" to the track.
373 If a signal is compressed too much it may sound dull or "dead"
374 afterwards or it may start to "pump" (which could be a powerful effect
375 but can also destroy a track completely).
376 The right compression is the key to reach a professional sound and is
377 the high art of mixing and mastering. Because of its complex settings
378 it may take a long time to get the right feeling for this kind of effect.
380 Compression is done by detecting the volume above a chosen level
381 @code{threshold} and dividing it by the factor set with @code{ratio}.
382 So if you set the threshold to -12dB and your signal reaches -6dB a ratio
383 of 2:1 will result in a signal at -9dB. Because an exact manipulation of
384 the signal would cause distortion of the waveform the reduction can be
385 levelled over the time. This is done by setting "Attack" and "Release".
386 @code{attack} determines how long the signal has to rise above the threshold
387 before any reduction will occur and @code{release} sets the time the signal
388 has to fall below the threshold to reduce the reduction again. Shorter signals
389 than the chosen attack time will be left untouched.
390 The overall reduction of the signal can be made up afterwards with the
391 @code{makeup} setting. So compressing the peaks of a signal about 6dB and
392 raising the makeup to this level results in a signal twice as loud than the
393 source. To gain a softer entry in the compression the @code{knee} flattens the
394 hard edge at the threshold in the range of the chosen decibels.
396 The filter accepts the following options:
400 Set input gain. Default is 1. Range is between 0.015625 and 64.
403 Set mode of compressor operation. Can be @code{upward} or @code{downward}.
404 Default is @code{downward}.
407 If a signal of stream rises above this level it will affect the gain
409 By default it is 0.125. Range is between 0.00097563 and 1.
412 Set a ratio by which the signal is reduced. 1:2 means that if the level
413 rose 4dB above the threshold, it will be only 2dB above after the reduction.
414 Default is 2. Range is between 1 and 20.
417 Amount of milliseconds the signal has to rise above the threshold before gain
418 reduction starts. Default is 20. Range is between 0.01 and 2000.
421 Amount of milliseconds the signal has to fall below the threshold before
422 reduction is decreased again. Default is 250. Range is between 0.01 and 9000.
425 Set the amount by how much signal will be amplified after processing.
426 Default is 1. Range is from 1 to 64.
429 Curve the sharp knee around the threshold to enter gain reduction more softly.
430 Default is 2.82843. Range is between 1 and 8.
433 Choose if the @code{average} level between all channels of input stream
434 or the louder(@code{maximum}) channel of input stream affects the
435 reduction. Default is @code{average}.
438 Should the exact signal be taken in case of @code{peak} or an RMS one in case
439 of @code{rms}. Default is @code{rms} which is mostly smoother.
442 How much to use compressed signal in output. Default is 1.
443 Range is between 0 and 1.
448 This filter supports the all above options as @ref{commands}.
451 Simple audio dynamic range compression/expansion filter.
453 The filter accepts the following options:
457 Set contrast. Default is 33. Allowed range is between 0 and 100.
462 Copy the input audio source unchanged to the output. This is mainly useful for
467 Apply cross fade from one input audio stream to another input audio stream.
468 The cross fade is applied for specified duration near the end of first stream.
470 The filter accepts the following options:
474 Specify the number of samples for which the cross fade effect has to last.
475 At the end of the cross fade effect the first input audio will be completely
476 silent. Default is 44100.
479 Specify the duration of the cross fade effect. See
480 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
481 for the accepted syntax.
482 By default the duration is determined by @var{nb_samples}.
483 If set this option is used instead of @var{nb_samples}.
486 Should first stream end overlap with second stream start. Default is enabled.
489 Set curve for cross fade transition for first stream.
492 Set curve for cross fade transition for second stream.
494 For description of available curve types see @ref{afade} filter description.
501 Cross fade from one input to another:
503 ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:c1=exp:c2=exp output.flac
507 Cross fade from one input to another but without overlapping:
509 ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:o=0:c1=exp:c2=exp output.flac
514 Split audio stream into several bands.
516 This filter splits audio stream into two or more frequency ranges.
517 Summing all streams back will give flat output.
519 The filter accepts the following options:
523 Set split frequencies. Those must be positive and increasing.
526 Set filter order, can be @var{2nd}, @var{4th} or @var{8th}.
527 Default is @var{4th}.
532 Reduce audio bit resolution.
534 This filter is bit crusher with enhanced functionality. A bit crusher
535 is used to audibly reduce number of bits an audio signal is sampled
536 with. This doesn't change the bit depth at all, it just produces the
537 effect. Material reduced in bit depth sounds more harsh and "digital".
538 This filter is able to even round to continuous values instead of discrete
540 Additionally it has a D/C offset which results in different crushing of
541 the lower and the upper half of the signal.
542 An Anti-Aliasing setting is able to produce "softer" crushing sounds.
544 Another feature of this filter is the logarithmic mode.
545 This setting switches from linear distances between bits to logarithmic ones.
546 The result is a much more "natural" sounding crusher which doesn't gate low
547 signals for example. The human ear has a logarithmic perception,
548 so this kind of crushing is much more pleasant.
549 Logarithmic crushing is also able to get anti-aliased.
551 The filter accepts the following options:
567 Can be linear: @code{lin} or logarithmic: @code{log}.
576 Set sample reduction.
579 Enable LFO. By default disabled.
590 Delay audio filtering until a given wallclock timestamp. See the @ref{cue}
594 Remove impulsive noise from input audio.
596 Samples detected as impulsive noise are replaced by interpolated samples using
597 autoregressive modelling.
601 Set window size, in milliseconds. Allowed range is from @code{10} to
602 @code{100}. Default value is @code{55} milliseconds.
603 This sets size of window which will be processed at once.
606 Set window overlap, in percentage of window size. Allowed range is from
607 @code{50} to @code{95}. Default value is @code{75} percent.
608 Setting this to a very high value increases impulsive noise removal but makes
609 whole process much slower.
612 Set autoregression order, in percentage of window size. Allowed range is from
613 @code{0} to @code{25}. Default value is @code{2} percent. This option also
614 controls quality of interpolated samples using neighbour good samples.
617 Set threshold value. Allowed range is from @code{1} to @code{100}.
618 Default value is @code{2}.
619 This controls the strength of impulsive noise which is going to be removed.
620 The lower value, the more samples will be detected as impulsive noise.
623 Set burst fusion, in percentage of window size. Allowed range is @code{0} to
624 @code{10}. Default value is @code{2}.
625 If any two samples detected as noise are spaced less than this value then any
626 sample between those two samples will be also detected as noise.
631 It accepts the following values:
634 Select overlap-add method. Even not interpolated samples are slightly
635 changed with this method.
638 Select overlap-save method. Not interpolated samples remain unchanged.
641 Default value is @code{a}.
645 Remove clipped samples from input audio.
647 Samples detected as clipped are replaced by interpolated samples using
648 autoregressive modelling.
652 Set window size, in milliseconds. Allowed range is from @code{10} to @code{100}.
653 Default value is @code{55} milliseconds.
654 This sets size of window which will be processed at once.
657 Set window overlap, in percentage of window size. Allowed range is from @code{50}
658 to @code{95}. Default value is @code{75} percent.
661 Set autoregression order, in percentage of window size. Allowed range is from
662 @code{0} to @code{25}. Default value is @code{8} percent. This option also controls
663 quality of interpolated samples using neighbour good samples.
666 Set threshold value. Allowed range is from @code{1} to @code{100}.
667 Default value is @code{10}. Higher values make clip detection less aggressive.
670 Set size of histogram used to detect clips. Allowed range is from @code{100} to @code{9999}.
671 Default value is @code{1000}. Higher values make clip detection less aggressive.
676 It accepts the following values:
679 Select overlap-add method. Even not interpolated samples are slightly changed
683 Select overlap-save method. Not interpolated samples remain unchanged.
686 Default value is @code{a}.
691 Delay one or more audio channels.
693 Samples in delayed channel are filled with silence.
695 The filter accepts the following option:
699 Set list of delays in milliseconds for each channel separated by '|'.
700 Unused delays will be silently ignored. If number of given delays is
701 smaller than number of channels all remaining channels will not be delayed.
702 If you want to delay exact number of samples, append 'S' to number.
703 If you want instead to delay in seconds, append 's' to number.
706 Use last set delay for all remaining channels. By default is disabled.
707 This option if enabled changes how option @code{delays} is interpreted.
714 Delay first channel by 1.5 seconds, the third channel by 0.5 seconds and leave
715 the second channel (and any other channels that may be present) unchanged.
721 Delay second channel by 500 samples, the third channel by 700 samples and leave
722 the first channel (and any other channels that may be present) unchanged.
728 Delay all channels by same number of samples:
730 adelay=delays=64S:all=1
735 Remedy denormals in audio by adding extremely low-level noise.
737 A description of the accepted parameters follows.
741 Set level of added noise in dB. Default is @code{-351}.
742 Allowed range is from -451 to -90.
745 Set type of added noise.
758 Default is @code{dc}.
761 @section aderivative, aintegral
763 Compute derivative/integral of audio stream.
765 Applying both filters one after another produces original audio.
769 Apply echoing to the input audio.
771 Echoes are reflected sound and can occur naturally amongst mountains
772 (and sometimes large buildings) when talking or shouting; digital echo
773 effects emulate this behaviour and are often used to help fill out the
774 sound of a single instrument or vocal. The time difference between the
775 original signal and the reflection is the @code{delay}, and the
776 loudness of the reflected signal is the @code{decay}.
777 Multiple echoes can have different delays and decays.
779 A description of the accepted parameters follows.
783 Set input gain of reflected signal. Default is @code{0.6}.
786 Set output gain of reflected signal. Default is @code{0.3}.
789 Set list of time intervals in milliseconds between original signal and reflections
790 separated by '|'. Allowed range for each @code{delay} is @code{(0 - 90000.0]}.
791 Default is @code{1000}.
794 Set list of loudness of reflected signals separated by '|'.
795 Allowed range for each @code{decay} is @code{(0 - 1.0]}.
796 Default is @code{0.5}.
803 Make it sound as if there are twice as many instruments as are actually playing:
805 aecho=0.8:0.88:60:0.4
809 If delay is very short, then it sounds like a (metallic) robot playing music:
815 A longer delay will sound like an open air concert in the mountains:
817 aecho=0.8:0.9:1000:0.3
821 Same as above but with one more mountain:
823 aecho=0.8:0.9:1000|1800:0.3|0.25
828 Audio emphasis filter creates or restores material directly taken from LPs or
829 emphased CDs with different filter curves. E.g. to store music on vinyl the
830 signal has to be altered by a filter first to even out the disadvantages of
831 this recording medium.
832 Once the material is played back the inverse filter has to be applied to
833 restore the distortion of the frequency response.
835 The filter accepts the following options:
845 Set filter mode. For restoring material use @code{reproduction} mode, otherwise
846 use @code{production} mode. Default is @code{reproduction} mode.
849 Set filter type. Selects medium. Can be one of the following:
861 select Compact Disc (CD).
867 select 50µs (FM-KF).
869 select 75µs (FM-KF).
875 Modify an audio signal according to the specified expressions.
877 This filter accepts one or more expressions (one for each channel),
878 which are evaluated and used to modify a corresponding audio signal.
880 It accepts the following parameters:
884 Set the '|'-separated expressions list for each separate channel. If
885 the number of input channels is greater than the number of
886 expressions, the last specified expression is used for the remaining
889 @item channel_layout, c
890 Set output channel layout. If not specified, the channel layout is
891 specified by the number of expressions. If set to @samp{same}, it will
892 use by default the same input channel layout.
895 Each expression in @var{exprs} can contain the following constants and functions:
899 channel number of the current expression
902 number of the evaluated sample, starting from 0
908 time of the evaluated sample expressed in seconds
911 @item nb_out_channels
912 input and output number of channels
915 the value of input channel with number @var{CH}
918 Note: this filter is slow. For faster processing you should use a
927 aeval=val(ch)/2:c=same
931 Invert phase of the second channel:
940 Apply fade-in/out effect to input audio.
942 A description of the accepted parameters follows.
946 Specify the effect type, can be either @code{in} for fade-in, or
947 @code{out} for a fade-out effect. Default is @code{in}.
949 @item start_sample, ss
950 Specify the number of the start sample for starting to apply the fade
951 effect. Default is 0.
954 Specify the number of samples for which the fade effect has to last. At
955 the end of the fade-in effect the output audio will have the same
956 volume as the input audio, at the end of the fade-out transition
957 the output audio will be silence. Default is 44100.
960 Specify the start time of the fade effect. Default is 0.
961 The value must be specified as a time duration; see
962 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
963 for the accepted syntax.
964 If set this option is used instead of @var{start_sample}.
967 Specify the duration of the fade effect. See
968 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
969 for the accepted syntax.
970 At the end of the fade-in effect the output audio will have the same
971 volume as the input audio, at the end of the fade-out transition
972 the output audio will be silence.
973 By default the duration is determined by @var{nb_samples}.
974 If set this option is used instead of @var{nb_samples}.
977 Set curve for fade transition.
979 It accepts the following values:
982 select triangular, linear slope (default)
984 select quarter of sine wave
986 select half of sine wave
988 select exponential sine wave
992 select inverted parabola
1006 select inverted quarter of sine wave
1008 select inverted half of sine wave
1010 select double-exponential seat
1012 select double-exponential sigmoid
1014 select logistic sigmoid
1016 select sine cardinal function
1018 select inverted sine cardinal function
1024 @subsection Examples
1028 Fade in first 15 seconds of audio:
1030 afade=t=in:ss=0:d=15
1034 Fade out last 25 seconds of a 900 seconds audio:
1036 afade=t=out:st=875:d=25
1041 Denoise audio samples with FFT.
1043 A description of the accepted parameters follows.
1047 Set the noise reduction in dB, allowed range is 0.01 to 97.
1048 Default value is 12 dB.
1051 Set the noise floor in dB, allowed range is -80 to -20.
1052 Default value is -50 dB.
1057 It accepts the following values:
1066 Select shellac noise.
1069 Select custom noise, defined in @code{bn} option.
1071 Default value is white noise.
1075 Set custom band noise for every one of 15 bands.
1076 Bands are separated by ' ' or '|'.
1079 Set the residual floor in dB, allowed range is -80 to -20.
1080 Default value is -38 dB.
1083 Enable noise tracking. By default is disabled.
1084 With this enabled, noise floor is automatically adjusted.
1087 Enable residual tracking. By default is disabled.
1090 Set the output mode.
1092 It accepts the following values:
1095 Pass input unchanged.
1098 Pass noise filtered out.
1103 Default value is @var{o}.
1107 @subsection Commands
1109 This filter supports the following commands:
1111 @item sample_noise, sn
1112 Start or stop measuring noise profile.
1113 Syntax for the command is : "start" or "stop" string.
1114 After measuring noise profile is stopped it will be
1115 automatically applied in filtering.
1117 @item noise_reduction, nr
1118 Change noise reduction. Argument is single float number.
1119 Syntax for the command is : "@var{noise_reduction}"
1121 @item noise_floor, nf
1122 Change noise floor. Argument is single float number.
1123 Syntax for the command is : "@var{noise_floor}"
1125 @item output_mode, om
1126 Change output mode operation.
1127 Syntax for the command is : "i", "o" or "n" string.
1131 Apply arbitrary expressions to samples in frequency domain.
1135 Set frequency domain real expression for each separate channel separated
1136 by '|'. Default is "re".
1137 If the number of input channels is greater than the number of
1138 expressions, the last specified expression is used for the remaining
1142 Set frequency domain imaginary expression for each separate channel
1143 separated by '|'. Default is "im".
1145 Each expression in @var{real} and @var{imag} can contain the following
1146 constants and functions:
1153 current frequency bin number
1156 number of available bins
1159 channel number of the current expression
1168 current real part of frequency bin of current channel
1171 current imaginary part of frequency bin of current channel
1174 Return the value of real part of frequency bin at location (@var{bin},@var{channel})
1177 Return the value of imaginary part of frequency bin at location (@var{bin},@var{channel})
1181 Set window size. Allowed range is from 16 to 131072.
1182 Default is @code{4096}
1185 Set window function. Default is @code{hann}.
1188 Set window overlap. If set to 1, the recommended overlap for selected
1189 window function will be picked. Default is @code{0.75}.
1192 @subsection Examples
1196 Leave almost only low frequencies in audio:
1198 afftfilt="'real=re * (1-clip((b/nb)*b,0,1))':imag='im * (1-clip((b/nb)*b,0,1))'"
1202 Apply robotize effect:
1204 afftfilt="real='hypot(re,im)*sin(0)':imag='hypot(re,im)*cos(0)':win_size=512:overlap=0.75"
1208 Apply whisper effect:
1210 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"
1217 Apply an arbitrary Finite Impulse Response filter.
1219 This filter is designed for applying long FIR filters,
1220 up to 60 seconds long.
1222 It can be used as component for digital crossover filters,
1223 room equalization, cross talk cancellation, wavefield synthesis,
1224 auralization, ambiophonics, ambisonics and spatialization.
1226 This filter uses the streams higher than first one as FIR coefficients.
1227 If the non-first stream holds a single channel, it will be used
1228 for all input channels in the first stream, otherwise
1229 the number of channels in the non-first stream must be same as
1230 the number of channels in the first stream.
1232 It accepts the following parameters:
1236 Set dry gain. This sets input gain.
1239 Set wet gain. This sets final output gain.
1242 Set Impulse Response filter length. Default is 1, which means whole IR is processed.
1245 Enable applying gain measured from power of IR.
1247 Set which approach to use for auto gain measurement.
1251 Do not apply any gain.
1254 select peak gain, very conservative approach. This is default value.
1257 select DC gain, limited application.
1260 select gain to noise approach, this is most popular one.
1264 Set gain to be applied to IR coefficients before filtering.
1265 Allowed range is 0 to 1. This gain is applied after any gain applied with @var{gtype} option.
1268 Set format of IR stream. Can be @code{mono} or @code{input}.
1269 Default is @code{input}.
1272 Set max allowed Impulse Response filter duration in seconds. Default is 30 seconds.
1273 Allowed range is 0.1 to 60 seconds.
1276 Show IR frequency response, magnitude(magenta), phase(green) and group delay(yellow) in additional video stream.
1277 By default it is disabled.
1280 Set for which IR channel to display frequency response. By default is first channel
1281 displayed. This option is used only when @var{response} is enabled.
1284 Set video stream size. This option is used only when @var{response} is enabled.
1287 Set video stream frame rate. This option is used only when @var{response} is enabled.
1290 Set minimal partition size used for convolution. Default is @var{8192}.
1291 Allowed range is from @var{1} to @var{32768}.
1292 Lower values decreases latency at cost of higher CPU usage.
1295 Set maximal partition size used for convolution. Default is @var{8192}.
1296 Allowed range is from @var{8} to @var{32768}.
1297 Lower values may increase CPU usage.
1300 Set number of input impulse responses streams which will be switchable at runtime.
1301 Allowed range is from @var{1} to @var{32}. Default is @var{1}.
1304 Set IR stream which will be used for convolution, starting from @var{0}, should always be
1305 lower than supplied value by @code{nbirs} option. Default is @var{0}.
1306 This option can be changed at runtime via @ref{commands}.
1309 @subsection Examples
1313 Apply reverb to stream using mono IR file as second input, complete command using ffmpeg:
1315 ffmpeg -i input.wav -i middle_tunnel_1way_mono.wav -lavfi afir output.wav
1322 Set output format constraints for the input audio. The framework will
1323 negotiate the most appropriate format to minimize conversions.
1325 It accepts the following parameters:
1328 @item sample_fmts, f
1329 A '|'-separated list of requested sample formats.
1331 @item sample_rates, r
1332 A '|'-separated list of requested sample rates.
1334 @item channel_layouts, cl
1335 A '|'-separated list of requested channel layouts.
1337 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
1338 for the required syntax.
1341 If a parameter is omitted, all values are allowed.
1343 Force the output to either unsigned 8-bit or signed 16-bit stereo
1345 aformat=sample_fmts=u8|s16:channel_layouts=stereo
1349 Apply frequency shift to input audio samples.
1351 The filter accepts the following options:
1355 Specify frequency shift. Allowed range is -INT_MAX to INT_MAX.
1356 Default value is 0.0.
1359 @subsection Commands
1361 This filter supports the above option as @ref{commands}.
1365 A gate is mainly used to reduce lower parts of a signal. This kind of signal
1366 processing reduces disturbing noise between useful signals.
1368 Gating is done by detecting the volume below a chosen level @var{threshold}
1369 and dividing it by the factor set with @var{ratio}. The bottom of the noise
1370 floor is set via @var{range}. Because an exact manipulation of the signal
1371 would cause distortion of the waveform the reduction can be levelled over
1372 time. This is done by setting @var{attack} and @var{release}.
1374 @var{attack} determines how long the signal has to fall below the threshold
1375 before any reduction will occur and @var{release} sets the time the signal
1376 has to rise above the threshold to reduce the reduction again.
1377 Shorter signals than the chosen attack time will be left untouched.
1381 Set input level before filtering.
1382 Default is 1. Allowed range is from 0.015625 to 64.
1385 Set the mode of operation. Can be @code{upward} or @code{downward}.
1386 Default is @code{downward}. If set to @code{upward} mode, higher parts of signal
1387 will be amplified, expanding dynamic range in upward direction.
1388 Otherwise, in case of @code{downward} lower parts of signal will be reduced.
1391 Set the level of gain reduction when the signal is below the threshold.
1392 Default is 0.06125. Allowed range is from 0 to 1.
1393 Setting this to 0 disables reduction and then filter behaves like expander.
1396 If a signal rises above this level the gain reduction is released.
1397 Default is 0.125. Allowed range is from 0 to 1.
1400 Set a ratio by which the signal is reduced.
1401 Default is 2. Allowed range is from 1 to 9000.
1404 Amount of milliseconds the signal has to rise above the threshold before gain
1406 Default is 20 milliseconds. Allowed range is from 0.01 to 9000.
1409 Amount of milliseconds the signal has to fall below the threshold before the
1410 reduction is increased again. Default is 250 milliseconds.
1411 Allowed range is from 0.01 to 9000.
1414 Set amount of amplification of signal after processing.
1415 Default is 1. Allowed range is from 1 to 64.
1418 Curve the sharp knee around the threshold to enter gain reduction more softly.
1419 Default is 2.828427125. Allowed range is from 1 to 8.
1422 Choose if exact signal should be taken for detection or an RMS like one.
1423 Default is @code{rms}. Can be @code{peak} or @code{rms}.
1426 Choose if the average level between all channels or the louder channel affects
1428 Default is @code{average}. Can be @code{average} or @code{maximum}.
1433 Apply an arbitrary Infinite Impulse Response filter.
1435 It accepts the following parameters:
1439 Set B/numerator/zeros/reflection coefficients.
1442 Set A/denominator/poles/ladder coefficients.
1454 Set coefficients format.
1458 lattice-ladder function
1460 analog transfer function
1462 digital transfer function
1464 Z-plane zeros/poles, cartesian (default)
1466 Z-plane zeros/poles, polar radians
1468 Z-plane zeros/poles, polar degrees
1474 Set type of processing.
1486 Set filtering precision.
1490 double-precision floating-point (default)
1492 single-precision floating-point
1500 Normalize filter coefficients, by default is enabled.
1501 Enabling it will normalize magnitude response at DC to 0dB.
1504 How much to use filtered signal in output. Default is 1.
1505 Range is between 0 and 1.
1508 Show IR frequency response, magnitude(magenta), phase(green) and group delay(yellow) in additional video stream.
1509 By default it is disabled.
1512 Set for which IR channel to display frequency response. By default is first channel
1513 displayed. This option is used only when @var{response} is enabled.
1516 Set video stream size. This option is used only when @var{response} is enabled.
1519 Coefficients in @code{tf} and @code{sf} format are separated by spaces and are in ascending
1522 Coefficients in @code{zp} format are separated by spaces and order of coefficients
1523 doesn't matter. Coefficients in @code{zp} format are complex numbers with @var{i}
1526 Different coefficients and gains can be provided for every channel, in such case
1527 use '|' to separate coefficients or gains. Last provided coefficients will be
1528 used for all remaining channels.
1530 @subsection Examples
1534 Apply 2 pole elliptic notch at around 5000Hz for 48000 Hz sample rate:
1536 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
1540 Same as above but in @code{zp} format:
1542 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
1546 Apply 3-rd order analog normalized Butterworth low-pass filter, using analog transfer function format:
1548 aiir=z=1.3057 0 0 0:p=1.3057 2.3892 2.1860 1:f=sf:r=d
1554 The limiter prevents an input signal from rising over a desired threshold.
1555 This limiter uses lookahead technology to prevent your signal from distorting.
1556 It means that there is a small delay after the signal is processed. Keep in mind
1557 that the delay it produces is the attack time you set.
1559 The filter accepts the following options:
1563 Set input gain. Default is 1.
1566 Set output gain. Default is 1.
1569 Don't let signals above this level pass the limiter. Default is 1.
1572 The limiter will reach its attenuation level in this amount of time in
1573 milliseconds. Default is 5 milliseconds.
1576 Come back from limiting to attenuation 1.0 in this amount of milliseconds.
1577 Default is 50 milliseconds.
1580 When gain reduction is always needed ASC takes care of releasing to an
1581 average reduction level rather than reaching a reduction of 0 in the release
1585 Select how much the release time is affected by ASC, 0 means nearly no changes
1586 in release time while 1 produces higher release times.
1589 Auto level output signal. Default is enabled.
1590 This normalizes audio back to 0dB if enabled.
1593 Depending on picked setting it is recommended to upsample input 2x or 4x times
1594 with @ref{aresample} before applying this filter.
1598 Apply a two-pole all-pass filter with central frequency (in Hz)
1599 @var{frequency}, and filter-width @var{width}.
1600 An all-pass filter changes the audio's frequency to phase relationship
1601 without changing its frequency to amplitude relationship.
1603 The filter accepts the following options:
1607 Set frequency in Hz.
1610 Set method to specify band-width of filter.
1625 Specify the band-width of a filter in width_type units.
1628 How much to use filtered signal in output. Default is 1.
1629 Range is between 0 and 1.
1632 Specify which channels to filter, by default all available are filtered.
1635 Normalize biquad coefficients, by default is disabled.
1636 Enabling it will normalize magnitude response at DC to 0dB.
1639 Set the filter order, can be 1 or 2. Default is 2.
1642 Set transform type of IIR filter.
1651 @subsection Commands
1653 This filter supports the following commands:
1656 Change allpass frequency.
1657 Syntax for the command is : "@var{frequency}"
1660 Change allpass width_type.
1661 Syntax for the command is : "@var{width_type}"
1664 Change allpass width.
1665 Syntax for the command is : "@var{width}"
1669 Syntax for the command is : "@var{mix}"
1676 The filter accepts the following options:
1680 Set the number of loops. Setting this value to -1 will result in infinite loops.
1684 Set maximal number of samples. Default is 0.
1687 Set first sample of loop. Default is 0.
1693 Merge two or more audio streams into a single multi-channel stream.
1695 The filter accepts the following options:
1700 Set the number of inputs. Default is 2.
1704 If the channel layouts of the inputs are disjoint, and therefore compatible,
1705 the channel layout of the output will be set accordingly and the channels
1706 will be reordered as necessary. If the channel layouts of the inputs are not
1707 disjoint, the output will have all the channels of the first input then all
1708 the channels of the second input, in that order, and the channel layout of
1709 the output will be the default value corresponding to the total number of
1712 For example, if the first input is in 2.1 (FL+FR+LF) and the second input
1713 is FC+BL+BR, then the output will be in 5.1, with the channels in the
1714 following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the
1715 first input, b1 is the first channel of the second input).
1717 On the other hand, if both input are in stereo, the output channels will be
1718 in the default order: a1, a2, b1, b2, and the channel layout will be
1719 arbitrarily set to 4.0, which may or may not be the expected value.
1721 All inputs must have the same sample rate, and format.
1723 If inputs do not have the same duration, the output will stop with the
1726 @subsection Examples
1730 Merge two mono files into a stereo stream:
1732 amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge
1736 Multiple merges assuming 1 video stream and 6 audio streams in @file{input.mkv}:
1738 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
1744 Mixes multiple audio inputs into a single output.
1746 Note that this filter only supports float samples (the @var{amerge}
1747 and @var{pan} audio filters support many formats). If the @var{amix}
1748 input has integer samples then @ref{aresample} will be automatically
1749 inserted to perform the conversion to float samples.
1753 ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT
1755 will mix 3 input audio streams to a single output with the same duration as the
1756 first input and a dropout transition time of 3 seconds.
1758 It accepts the following parameters:
1762 The number of inputs. If unspecified, it defaults to 2.
1765 How to determine the end-of-stream.
1769 The duration of the longest input. (default)
1772 The duration of the shortest input.
1775 The duration of the first input.
1779 @item dropout_transition
1780 The transition time, in seconds, for volume renormalization when an input
1781 stream ends. The default value is 2 seconds.
1784 Specify weight of each input audio stream as sequence.
1785 Each weight is separated by space. By default all inputs have same weight.
1788 @subsection Commands
1790 This filter supports the following commands:
1793 Syntax is same as option with same name.
1798 Multiply first audio stream with second audio stream and store result
1799 in output audio stream. Multiplication is done by multiplying each
1800 sample from first stream with sample at same position from second stream.
1802 With this element-wise multiplication one can create amplitude fades and
1803 amplitude modulations.
1805 @section anequalizer
1807 High-order parametric multiband equalizer for each channel.
1809 It accepts the following parameters:
1813 This option string is in format:
1814 "c@var{chn} f=@var{cf} w=@var{w} g=@var{g} t=@var{f} | ..."
1815 Each equalizer band is separated by '|'.
1819 Set channel number to which equalization will be applied.
1820 If input doesn't have that channel the entry is ignored.
1823 Set central frequency for band.
1824 If input doesn't have that frequency the entry is ignored.
1827 Set band width in hertz.
1830 Set band gain in dB.
1833 Set filter type for band, optional, can be:
1837 Butterworth, this is default.
1848 With this option activated frequency response of anequalizer is displayed
1852 Set video stream size. Only useful if curves option is activated.
1855 Set max gain that will be displayed. Only useful if curves option is activated.
1856 Setting this to a reasonable value makes it possible to display gain which is derived from
1857 neighbour bands which are too close to each other and thus produce higher gain
1858 when both are activated.
1861 Set frequency scale used to draw frequency response in video output.
1862 Can be linear or logarithmic. Default is logarithmic.
1865 Set color for each channel curve which is going to be displayed in video stream.
1866 This is list of color names separated by space or by '|'.
1867 Unrecognised or missing colors will be replaced by white color.
1870 @subsection Examples
1874 Lower gain by 10 of central frequency 200Hz and width 100 Hz
1875 for first 2 channels using Chebyshev type 1 filter:
1877 anequalizer=c0 f=200 w=100 g=-10 t=1|c1 f=200 w=100 g=-10 t=1
1881 @subsection Commands
1883 This filter supports the following commands:
1886 Alter existing filter parameters.
1887 Syntax for the commands is : "@var{fN}|f=@var{freq}|w=@var{width}|g=@var{gain}"
1889 @var{fN} is existing filter number, starting from 0, if no such filter is available
1891 @var{freq} set new frequency parameter.
1892 @var{width} set new width parameter in herz.
1893 @var{gain} set new gain parameter in dB.
1895 Full filter invocation with asendcmd may look like this:
1896 asendcmd=c='4.0 anequalizer change 0|f=200|w=50|g=1',anequalizer=...
1901 Reduce broadband noise in audio samples using Non-Local Means algorithm.
1903 Each sample is adjusted by looking for other samples with similar contexts. This
1904 context similarity is defined by comparing their surrounding patches of size
1905 @option{p}. Patches are searched in an area of @option{r} around the sample.
1907 The filter accepts the following options:
1911 Set denoising strength. Allowed range is from 0.00001 to 10. Default value is 0.00001.
1914 Set patch radius duration. Allowed range is from 1 to 100 milliseconds.
1915 Default value is 2 milliseconds.
1918 Set research radius duration. Allowed range is from 2 to 300 milliseconds.
1919 Default value is 6 milliseconds.
1922 Set the output mode.
1924 It accepts the following values:
1927 Pass input unchanged.
1930 Pass noise filtered out.
1935 Default value is @var{o}.
1939 Set smooth factor. Default value is @var{11}. Allowed range is from @var{1} to @var{15}.
1942 @subsection Commands
1944 This filter supports the all above options as @ref{commands}.
1947 Apply Normalized Least-Mean-Squares algorithm to the first audio stream using the second audio stream.
1949 This adaptive filter is used to mimic a desired filter by finding the filter coefficients that
1950 relate to producing the least mean square of the error signal (difference between the desired,
1951 2nd input audio stream and the actual signal, the 1st input audio stream).
1953 A description of the accepted options follows.
1966 Set the filter leakage.
1969 It accepts the following values:
1978 Pass filtered samples.
1981 Pass difference between desired and filtered samples.
1983 Default value is @var{o}.
1987 @subsection Examples
1991 One of many usages of this filter is noise reduction, input audio is filtered
1992 with same samples that are delayed by fixed amount, one such example for stereo audio is:
1994 asplit[a][b],[a]adelay=32S|32S[a],[b][a]anlms=order=128:leakage=0.0005:mu=.5:out_mode=o
1998 @subsection Commands
2000 This filter supports the same commands as options, excluding option @code{order}.
2004 Pass the audio source unchanged to the output.
2008 Pad the end of an audio stream with silence.
2010 This can be used together with @command{ffmpeg} @option{-shortest} to
2011 extend audio streams to the same length as the video stream.
2013 A description of the accepted options follows.
2017 Set silence packet size. Default value is 4096.
2020 Set the number of samples of silence to add to the end. After the
2021 value is reached, the stream is terminated. This option is mutually
2022 exclusive with @option{whole_len}.
2025 Set the minimum total number of samples in the output audio stream. If
2026 the value is longer than the input audio length, silence is added to
2027 the end, until the value is reached. This option is mutually exclusive
2028 with @option{pad_len}.
2031 Specify the duration of samples of silence to add. See
2032 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
2033 for the accepted syntax. Used only if set to non-zero value.
2036 Specify the minimum total duration in the output audio stream. See
2037 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
2038 for the accepted syntax. Used only if set to non-zero value. If the value is longer than
2039 the input audio length, silence is added to the end, until the value is reached.
2040 This option is mutually exclusive with @option{pad_dur}
2043 If neither the @option{pad_len} nor the @option{whole_len} nor @option{pad_dur}
2044 nor @option{whole_dur} option is set, the filter will add silence to the end of
2045 the input stream indefinitely.
2047 @subsection Examples
2051 Add 1024 samples of silence to the end of the input:
2057 Make sure the audio output will contain at least 10000 samples, pad
2058 the input with silence if required:
2060 apad=whole_len=10000
2064 Use @command{ffmpeg} to pad the audio input with silence, so that the
2065 video stream will always result the shortest and will be converted
2066 until the end in the output file when using the @option{shortest}
2069 ffmpeg -i VIDEO -i AUDIO -filter_complex "[1:0]apad" -shortest OUTPUT
2074 Add a phasing effect to the input audio.
2076 A phaser filter creates series of peaks and troughs in the frequency spectrum.
2077 The position of the peaks and troughs are modulated so that they vary over time, creating a sweeping effect.
2079 A description of the accepted parameters follows.
2083 Set input gain. Default is 0.4.
2086 Set output gain. Default is 0.74
2089 Set delay in milliseconds. Default is 3.0.
2092 Set decay. Default is 0.4.
2095 Set modulation speed in Hz. Default is 0.5.
2098 Set modulation type. Default is triangular.
2100 It accepts the following values:
2107 @section aphaseshift
2108 Apply phase shift to input audio samples.
2110 The filter accepts the following options:
2114 Specify phase shift. Allowed range is from -1.0 to 1.0.
2115 Default value is 0.0.
2118 @subsection Commands
2120 This filter supports the above option as @ref{commands}.
2124 Audio pulsator is something between an autopanner and a tremolo.
2125 But it can produce funny stereo effects as well. Pulsator changes the volume
2126 of the left and right channel based on a LFO (low frequency oscillator) with
2127 different waveforms and shifted phases.
2128 This filter have the ability to define an offset between left and right
2129 channel. An offset of 0 means that both LFO shapes match each other.
2130 The left and right channel are altered equally - a conventional tremolo.
2131 An offset of 50% means that the shape of the right channel is exactly shifted
2132 in phase (or moved backwards about half of the frequency) - pulsator acts as
2133 an autopanner. At 1 both curves match again. Every setting in between moves the
2134 phase shift gapless between all stages and produces some "bypassing" sounds with
2135 sine and triangle waveforms. The more you set the offset near 1 (starting from
2136 the 0.5) the faster the signal passes from the left to the right speaker.
2138 The filter accepts the following options:
2142 Set input gain. By default it is 1. Range is [0.015625 - 64].
2145 Set output gain. By default it is 1. Range is [0.015625 - 64].
2148 Set waveform shape the LFO will use. Can be one of: sine, triangle, square,
2149 sawup or sawdown. Default is sine.
2152 Set modulation. Define how much of original signal is affected by the LFO.
2155 Set left channel offset. Default is 0. Allowed range is [0 - 1].
2158 Set right channel offset. Default is 0.5. Allowed range is [0 - 1].
2161 Set pulse width. Default is 1. Allowed range is [0 - 2].
2164 Set possible timing mode. Can be one of: bpm, ms or hz. Default is hz.
2167 Set bpm. Default is 120. Allowed range is [30 - 300]. Only used if timing
2171 Set ms. Default is 500. Allowed range is [10 - 2000]. Only used if timing
2175 Set frequency in Hz. Default is 2. Allowed range is [0.01 - 100]. Only used
2176 if timing is set to hz.
2182 Resample the input audio to the specified parameters, using the
2183 libswresample library. If none are specified then the filter will
2184 automatically convert between its input and output.
2186 This filter is also able to stretch/squeeze the audio data to make it match
2187 the timestamps or to inject silence / cut out audio to make it match the
2188 timestamps, do a combination of both or do neither.
2190 The filter accepts the syntax
2191 [@var{sample_rate}:]@var{resampler_options}, where @var{sample_rate}
2192 expresses a sample rate and @var{resampler_options} is a list of
2193 @var{key}=@var{value} pairs, separated by ":". See the
2194 @ref{Resampler Options,,"Resampler Options" section in the
2195 ffmpeg-resampler(1) manual,ffmpeg-resampler}
2196 for the complete list of supported options.
2198 @subsection Examples
2202 Resample the input audio to 44100Hz:
2208 Stretch/squeeze samples to the given timestamps, with a maximum of 1000
2209 samples per second compensation:
2211 aresample=async=1000
2217 Reverse an audio clip.
2219 Warning: This filter requires memory to buffer the entire clip, so trimming
2222 @subsection Examples
2226 Take the first 5 seconds of a clip, and reverse it.
2228 atrim=end=5,areverse
2234 Reduce noise from speech using Recurrent Neural Networks.
2236 This filter accepts the following options:
2240 Set train model file to load. This option is always required.
2243 @section asetnsamples
2245 Set the number of samples per each output audio frame.
2247 The last output packet may contain a different number of samples, as
2248 the filter will flush all the remaining samples when the input audio
2251 The filter accepts the following options:
2255 @item nb_out_samples, n
2256 Set the number of frames per each output audio frame. The number is
2257 intended as the number of samples @emph{per each channel}.
2258 Default value is 1024.
2261 If set to 1, the filter will pad the last audio frame with zeroes, so
2262 that the last frame will contain the same number of samples as the
2263 previous ones. Default value is 1.
2266 For example, to set the number of per-frame samples to 1234 and
2267 disable padding for the last frame, use:
2269 asetnsamples=n=1234:p=0
2274 Set the sample rate without altering the PCM data.
2275 This will result in a change of speed and pitch.
2277 The filter accepts the following options:
2280 @item sample_rate, r
2281 Set the output sample rate. Default is 44100 Hz.
2286 Show a line containing various information for each input audio frame.
2287 The input audio is not modified.
2289 The shown line contains a sequence of key/value pairs of the form
2290 @var{key}:@var{value}.
2292 The following values are shown in the output:
2296 The (sequential) number of the input frame, starting from 0.
2299 The presentation timestamp of the input frame, in time base units; the time base
2300 depends on the filter input pad, and is usually 1/@var{sample_rate}.
2303 The presentation timestamp of the input frame in seconds.
2306 position of the frame in the input stream, -1 if this information in
2307 unavailable and/or meaningless (for example in case of synthetic audio)
2316 The sample rate for the audio frame.
2319 The number of samples (per channel) in the frame.
2322 The Adler-32 checksum (printed in hexadecimal) of the audio data. For planar
2323 audio, the data is treated as if all the planes were concatenated.
2325 @item plane_checksums
2326 A list of Adler-32 checksums for each data plane.
2330 Apply audio soft clipping.
2332 Soft clipping is a type of distortion effect where the amplitude of a signal is saturated
2333 along a smooth curve, rather than the abrupt shape of hard-clipping.
2335 This filter accepts the following options:
2339 Set type of soft-clipping.
2341 It accepts the following values:
2355 Set additional parameter which controls sigmoid function.
2358 Set oversampling factor.
2361 @subsection Commands
2363 This filter supports the all above options as @ref{commands}.
2366 Automatic Speech Recognition
2368 This filter uses PocketSphinx for speech recognition. To enable
2369 compilation of this filter, you need to configure FFmpeg with
2370 @code{--enable-pocketsphinx}.
2372 It accepts the following options:
2376 Set sampling rate of input audio. Defaults is @code{16000}.
2377 This need to match speech models, otherwise one will get poor results.
2380 Set dictionary containing acoustic model files.
2383 Set pronunciation dictionary.
2386 Set language model file.
2389 Set language model set.
2392 Set which language model to use.
2395 Set output for log messages.
2398 The filter exports recognized speech as the frame metadata @code{lavfi.asr.text}.
2403 Display time domain statistical information about the audio channels.
2404 Statistics are calculated and displayed for each audio channel and,
2405 where applicable, an overall figure is also given.
2407 It accepts the following option:
2410 Short window length in seconds, used for peak and trough RMS measurement.
2411 Default is @code{0.05} (50 milliseconds). Allowed range is @code{[0.01 - 10]}.
2415 Set metadata injection. All the metadata keys are prefixed with @code{lavfi.astats.X},
2416 where @code{X} is channel number starting from 1 or string @code{Overall}. Default is
2419 Available keys for each channel are:
2465 For example full key look like this @code{lavfi.astats.1.DC_offset} or
2466 this @code{lavfi.astats.Overall.Peak_count}.
2468 For description what each key means read below.
2471 Set number of frame after which stats are going to be recalculated.
2472 Default is disabled.
2474 @item measure_perchannel
2475 Select the entries which need to be measured per channel. The metadata keys can
2476 be used as flags, default is @option{all} which measures everything.
2477 @option{none} disables all per channel measurement.
2479 @item measure_overall
2480 Select the entries which need to be measured overall. The metadata keys can
2481 be used as flags, default is @option{all} which measures everything.
2482 @option{none} disables all overall measurement.
2486 A description of each shown parameter follows:
2490 Mean amplitude displacement from zero.
2493 Minimal sample level.
2496 Maximal sample level.
2498 @item Min difference
2499 Minimal difference between two consecutive samples.
2501 @item Max difference
2502 Maximal difference between two consecutive samples.
2504 @item Mean difference
2505 Mean difference between two consecutive samples.
2506 The average of each difference between two consecutive samples.
2508 @item RMS difference
2509 Root Mean Square difference between two consecutive samples.
2513 Standard peak and RMS level measured in dBFS.
2517 Peak and trough values for RMS level measured over a short window.
2520 Standard ratio of peak to RMS level (note: not in dB).
2523 Flatness (i.e. consecutive samples with the same value) of the signal at its peak levels
2524 (i.e. either @var{Min level} or @var{Max level}).
2527 Number of occasions (not the number of samples) that the signal attained either
2528 @var{Min level} or @var{Max level}.
2530 @item Noise floor dB
2531 Minimum local peak measured in dBFS over a short window.
2533 @item Noise floor count
2534 Number of occasions (not the number of samples) that the signal attained
2538 Overall bit depth of audio. Number of bits used for each sample.
2541 Measured dynamic range of audio in dB.
2543 @item Zero crossings
2544 Number of points where the waveform crosses the zero level axis.
2546 @item Zero crossings rate
2547 Rate of Zero crossings and number of audio samples.
2551 Boost subwoofer frequencies.
2553 The filter accepts the following options:
2557 Set dry gain, how much of original signal is kept. Allowed range is from 0 to 1.
2558 Default value is 0.5.
2561 Set wet gain, how much of filtered signal is kept. Allowed range is from 0 to 1.
2562 Default value is 0.8.
2565 Set delay line decay gain value. Allowed range is from 0 to 1.
2566 Default value is 0.7.
2569 Set delay line feedback gain value. Allowed range is from 0 to 1.
2570 Default value is 0.5.
2573 Set cutoff frequency in herz. Allowed range is 50 to 900.
2574 Default value is 100.
2577 Set slope amount for cutoff frequency. Allowed range is 0.0001 to 1.
2578 Default value is 0.5.
2581 Set delay. Allowed range is from 1 to 100.
2582 Default value is 20.
2585 @subsection Commands
2587 This filter supports the all above options as @ref{commands}.
2593 The filter accepts exactly one parameter, the audio tempo. If not
2594 specified then the filter will assume nominal 1.0 tempo. Tempo must
2595 be in the [0.5, 100.0] range.
2597 Note that tempo greater than 2 will skip some samples rather than
2598 blend them in. If for any reason this is a concern it is always
2599 possible to daisy-chain several instances of atempo to achieve the
2600 desired product tempo.
2602 @subsection Examples
2606 Slow down audio to 80% tempo:
2612 To speed up audio to 300% tempo:
2618 To speed up audio to 300% tempo by daisy-chaining two atempo instances:
2620 atempo=sqrt(3),atempo=sqrt(3)
2624 @subsection Commands
2626 This filter supports the following commands:
2629 Change filter tempo scale factor.
2630 Syntax for the command is : "@var{tempo}"
2635 Trim the input so that the output contains one continuous subpart of the input.
2637 It accepts the following parameters:
2640 Timestamp (in seconds) of the start of the section to keep. I.e. the audio
2641 sample with the timestamp @var{start} will be the first sample in the output.
2644 Specify time of the first audio sample that will be dropped, i.e. the
2645 audio sample immediately preceding the one with the timestamp @var{end} will be
2646 the last sample in the output.
2649 Same as @var{start}, except this option sets the start timestamp in samples
2653 Same as @var{end}, except this option sets the end timestamp in samples instead
2657 The maximum duration of the output in seconds.
2660 The number of the first sample that should be output.
2663 The number of the first sample that should be dropped.
2666 @option{start}, @option{end}, and @option{duration} are expressed as time
2667 duration specifications; see
2668 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}.
2670 Note that the first two sets of the start/end options and the @option{duration}
2671 option look at the frame timestamp, while the _sample options simply count the
2672 samples that pass through the filter. So start/end_pts and start/end_sample will
2673 give different results when the timestamps are wrong, inexact or do not start at
2674 zero. Also note that this filter does not modify the timestamps. If you wish
2675 to have the output timestamps start at zero, insert the asetpts filter after the
2678 If multiple start or end options are set, this filter tries to be greedy and
2679 keep all samples that match at least one of the specified constraints. To keep
2680 only the part that matches all the constraints at once, chain multiple atrim
2683 The defaults are such that all the input is kept. So it is possible to set e.g.
2684 just the end values to keep everything before the specified time.
2689 Drop everything except the second minute of input:
2691 ffmpeg -i INPUT -af atrim=60:120
2695 Keep only the first 1000 samples:
2697 ffmpeg -i INPUT -af atrim=end_sample=1000
2702 @section axcorrelate
2703 Calculate normalized cross-correlation between two input audio streams.
2705 Resulted samples are always between -1 and 1 inclusive.
2706 If result is 1 it means two input samples are highly correlated in that selected segment.
2707 Result 0 means they are not correlated at all.
2708 If result is -1 it means two input samples are out of phase, which means they cancel each
2711 The filter accepts the following options:
2715 Set size of segment over which cross-correlation is calculated.
2716 Default is 256. Allowed range is from 2 to 131072.
2719 Set algorithm for cross-correlation. Can be @code{slow} or @code{fast}.
2720 Default is @code{slow}. Fast algorithm assumes mean values over any given segment
2721 are always zero and thus need much less calculations to make.
2722 This is generally not true, but is valid for typical audio streams.
2725 @subsection Examples
2729 Calculate correlation between channels in stereo audio stream:
2731 ffmpeg -i stereo.wav -af channelsplit,axcorrelate=size=1024:algo=fast correlation.wav
2737 Apply a two-pole Butterworth band-pass filter with central
2738 frequency @var{frequency}, and (3dB-point) band-width width.
2739 The @var{csg} option selects a constant skirt gain (peak gain = Q)
2740 instead of the default: constant 0dB peak gain.
2741 The filter roll off at 6dB per octave (20dB per decade).
2743 The filter accepts the following options:
2747 Set the filter's central frequency. Default is @code{3000}.
2750 Constant skirt gain if set to 1. Defaults to 0.
2753 Set method to specify band-width of filter.
2768 Specify the band-width of a filter in width_type units.
2771 How much to use filtered signal in output. Default is 1.
2772 Range is between 0 and 1.
2775 Specify which channels to filter, by default all available are filtered.
2778 Normalize biquad coefficients, by default is disabled.
2779 Enabling it will normalize magnitude response at DC to 0dB.
2782 Set transform type of IIR filter.
2791 @subsection Commands
2793 This filter supports the following commands:
2796 Change bandpass frequency.
2797 Syntax for the command is : "@var{frequency}"
2800 Change bandpass width_type.
2801 Syntax for the command is : "@var{width_type}"
2804 Change bandpass width.
2805 Syntax for the command is : "@var{width}"
2808 Change bandpass mix.
2809 Syntax for the command is : "@var{mix}"
2814 Apply a two-pole Butterworth band-reject filter with central
2815 frequency @var{frequency}, and (3dB-point) band-width @var{width}.
2816 The filter roll off at 6dB per octave (20dB per decade).
2818 The filter accepts the following options:
2822 Set the filter's central frequency. Default is @code{3000}.
2825 Set method to specify band-width of filter.
2840 Specify the band-width of a filter in width_type units.
2843 How much to use filtered signal in output. Default is 1.
2844 Range is between 0 and 1.
2847 Specify which channels to filter, by default all available are filtered.
2850 Normalize biquad coefficients, by default is disabled.
2851 Enabling it will normalize magnitude response at DC to 0dB.
2854 Set transform type of IIR filter.
2863 @subsection Commands
2865 This filter supports the following commands:
2868 Change bandreject frequency.
2869 Syntax for the command is : "@var{frequency}"
2872 Change bandreject width_type.
2873 Syntax for the command is : "@var{width_type}"
2876 Change bandreject width.
2877 Syntax for the command is : "@var{width}"
2880 Change bandreject mix.
2881 Syntax for the command is : "@var{mix}"
2884 @section bass, lowshelf
2886 Boost or cut the bass (lower) frequencies of the audio using a two-pole
2887 shelving filter with a response similar to that of a standard
2888 hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
2890 The filter accepts the following options:
2894 Give the gain at 0 Hz. Its useful range is about -20
2895 (for a large cut) to +20 (for a large boost).
2896 Beware of clipping when using a positive gain.
2899 Set the filter's central frequency and so can be used
2900 to extend or reduce the frequency range to be boosted or cut.
2901 The default value is @code{100} Hz.
2904 Set method to specify band-width of filter.
2919 Determine how steep is the filter's shelf transition.
2922 How much to use filtered signal in output. Default is 1.
2923 Range is between 0 and 1.
2926 Specify which channels to filter, by default all available are filtered.
2929 Normalize biquad coefficients, by default is disabled.
2930 Enabling it will normalize magnitude response at DC to 0dB.
2933 Set transform type of IIR filter.
2942 @subsection Commands
2944 This filter supports the following commands:
2947 Change bass frequency.
2948 Syntax for the command is : "@var{frequency}"
2951 Change bass width_type.
2952 Syntax for the command is : "@var{width_type}"
2956 Syntax for the command is : "@var{width}"
2960 Syntax for the command is : "@var{gain}"
2964 Syntax for the command is : "@var{mix}"
2969 Apply a biquad IIR filter with the given coefficients.
2970 Where @var{b0}, @var{b1}, @var{b2} and @var{a0}, @var{a1}, @var{a2}
2971 are the numerator and denominator coefficients respectively.
2972 and @var{channels}, @var{c} specify which channels to filter, by default all
2973 available are filtered.
2975 @subsection Commands
2977 This filter supports the following commands:
2985 Change biquad parameter.
2986 Syntax for the command is : "@var{value}"
2989 How much to use filtered signal in output. Default is 1.
2990 Range is between 0 and 1.
2993 Specify which channels to filter, by default all available are filtered.
2996 Normalize biquad coefficients, by default is disabled.
2997 Enabling it will normalize magnitude response at DC to 0dB.
3000 Set transform type of IIR filter.
3010 Bauer stereo to binaural transformation, which improves headphone listening of
3011 stereo audio records.
3013 To enable compilation of this filter you need to configure FFmpeg with
3014 @code{--enable-libbs2b}.
3016 It accepts the following parameters:
3020 Pre-defined crossfeed level.
3024 Default level (fcut=700, feed=50).
3027 Chu Moy circuit (fcut=700, feed=60).
3030 Jan Meier circuit (fcut=650, feed=95).
3035 Cut frequency (in Hz).
3044 Remap input channels to new locations.
3046 It accepts the following parameters:
3049 Map channels from input to output. The argument is a '|'-separated list of
3050 mappings, each in the @code{@var{in_channel}-@var{out_channel}} or
3051 @var{in_channel} form. @var{in_channel} can be either the name of the input
3052 channel (e.g. FL for front left) or its index in the input channel layout.
3053 @var{out_channel} is the name of the output channel or its index in the output
3054 channel layout. If @var{out_channel} is not given then it is implicitly an
3055 index, starting with zero and increasing by one for each mapping.
3057 @item channel_layout
3058 The channel layout of the output stream.
3061 If no mapping is present, the filter will implicitly map input channels to
3062 output channels, preserving indices.
3064 @subsection Examples
3068 For example, assuming a 5.1+downmix input MOV file,
3070 ffmpeg -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav
3072 will create an output WAV file tagged as stereo from the downmix channels of
3076 To fix a 5.1 WAV improperly encoded in AAC's native channel order
3078 ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:5.1' out.wav
3082 @section channelsplit
3084 Split each channel from an input audio stream into a separate output stream.
3086 It accepts the following parameters:
3088 @item channel_layout
3089 The channel layout of the input stream. The default is "stereo".
3091 A channel layout describing the channels to be extracted as separate output streams
3092 or "all" to extract each input channel as a separate stream. The default is "all".
3094 Choosing channels not present in channel layout in the input will result in an error.
3097 @subsection Examples
3101 For example, assuming a stereo input MP3 file,
3103 ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv
3105 will create an output Matroska file with two audio streams, one containing only
3106 the left channel and the other the right channel.
3109 Split a 5.1 WAV file into per-channel files:
3111 ffmpeg -i in.wav -filter_complex
3112 'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]'
3113 -map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]'
3114 front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]'
3119 Extract only LFE from a 5.1 WAV file:
3121 ffmpeg -i in.wav -filter_complex 'channelsplit=channel_layout=5.1:channels=LFE[LFE]'
3122 -map '[LFE]' lfe.wav
3127 Add a chorus effect to the audio.
3129 Can make a single vocal sound like a chorus, but can also be applied to instrumentation.
3131 Chorus resembles an echo effect with a short delay, but whereas with echo the delay is
3132 constant, with chorus, it is varied using using sinusoidal or triangular modulation.
3133 The modulation depth defines the range the modulated delay is played before or after
3134 the delay. Hence the delayed sound will sound slower or faster, that is the delayed
3135 sound tuned around the original one, like in a chorus where some vocals are slightly
3138 It accepts the following parameters:
3141 Set input gain. Default is 0.4.
3144 Set output gain. Default is 0.4.
3147 Set delays. A typical delay is around 40ms to 60ms.
3159 @subsection Examples
3165 chorus=0.7:0.9:55:0.4:0.25:2
3171 chorus=0.6:0.9:50|60:0.4|0.32:0.25|0.4:2|1.3
3175 Fuller sounding chorus with three delays:
3177 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
3182 Compress or expand the audio's dynamic range.
3184 It accepts the following parameters:
3190 A list of times in seconds for each channel over which the instantaneous level
3191 of the input signal is averaged to determine its volume. @var{attacks} refers to
3192 increase of volume and @var{decays} refers to decrease of volume. For most
3193 situations, the attack time (response to the audio getting louder) should be
3194 shorter than the decay time, because the human ear is more sensitive to sudden
3195 loud audio than sudden soft audio. A typical value for attack is 0.3 seconds and
3196 a typical value for decay is 0.8 seconds.
3197 If specified number of attacks & decays is lower than number of channels, the last
3198 set attack/decay will be used for all remaining channels.
3201 A list of points for the transfer function, specified in dB relative to the
3202 maximum possible signal amplitude. Each key points list must be defined using
3203 the following syntax: @code{x0/y0|x1/y1|x2/y2|....} or
3204 @code{x0/y0 x1/y1 x2/y2 ....}
3206 The input values must be in strictly increasing order but the transfer function
3207 does not have to be monotonically rising. The point @code{0/0} is assumed but
3208 may be overridden (by @code{0/out-dBn}). Typical values for the transfer
3209 function are @code{-70/-70|-60/-20|1/0}.
3212 Set the curve radius in dB for all joints. It defaults to 0.01.
3215 Set the additional gain in dB to be applied at all points on the transfer
3216 function. This allows for easy adjustment of the overall gain.
3220 Set an initial volume, in dB, to be assumed for each channel when filtering
3221 starts. This permits the user to supply a nominal level initially, so that, for
3222 example, a very large gain is not applied to initial signal levels before the
3223 companding has begun to operate. A typical value for audio which is initially
3224 quiet is -90 dB. It defaults to 0.
3227 Set a delay, in seconds. The input audio is analyzed immediately, but audio is
3228 delayed before being fed to the volume adjuster. Specifying a delay
3229 approximately equal to the attack/decay times allows the filter to effectively
3230 operate in predictive rather than reactive mode. It defaults to 0.
3234 @subsection Examples
3238 Make music with both quiet and loud passages suitable for listening to in a
3241 compand=.3|.3:1|1:-90/-60|-60/-40|-40/-30|-20/-20:6:0:-90:0.2
3244 Another example for audio with whisper and explosion parts:
3246 compand=0|0:1|1:-90/-900|-70/-70|-30/-9|0/-3:6:0:0:0
3250 A noise gate for when the noise is at a lower level than the signal:
3252 compand=.1|.1:.2|.2:-900/-900|-50.1/-900|-50/-50:.01:0:-90:.1
3256 Here is another noise gate, this time for when the noise is at a higher level
3257 than the signal (making it, in some ways, similar to squelch):
3259 compand=.1|.1:.1|.1:-45.1/-45.1|-45/-900|0/-900:.01:45:-90:.1
3263 2:1 compression starting at -6dB:
3265 compand=points=-80/-80|-6/-6|0/-3.8|20/3.5
3269 2:1 compression starting at -9dB:
3271 compand=points=-80/-80|-9/-9|0/-5.3|20/2.9
3275 2:1 compression starting at -12dB:
3277 compand=points=-80/-80|-12/-12|0/-6.8|20/1.9
3281 2:1 compression starting at -18dB:
3283 compand=points=-80/-80|-18/-18|0/-9.8|20/0.7
3287 3:1 compression starting at -15dB:
3289 compand=points=-80/-80|-15/-15|0/-10.8|20/-5.2
3295 compand=points=-80/-105|-62/-80|-15.4/-15.4|0/-12|20/-7.6
3301 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
3305 Hard limiter at -6dB:
3307 compand=attacks=0:points=-80/-80|-6/-6|20/-6
3311 Hard limiter at -12dB:
3313 compand=attacks=0:points=-80/-80|-12/-12|20/-12
3317 Hard noise gate at -35 dB:
3319 compand=attacks=0:points=-80/-115|-35.1/-80|-35/-35|20/20
3325 compand=attacks=0:points=-80/-80|-12.4/-12.4|-6/-8|0/-6.8|20/-2.8
3329 @section compensationdelay
3331 Compensation Delay Line is a metric based delay to compensate differing
3332 positions of microphones or speakers.
3334 For example, you have recorded guitar with two microphones placed in
3335 different locations. Because the front of sound wave has fixed speed in
3336 normal conditions, the phasing of microphones can vary and depends on
3337 their location and interposition. The best sound mix can be achieved when
3338 these microphones are in phase (synchronized). Note that a distance of
3339 ~30 cm between microphones makes one microphone capture the signal in
3340 antiphase to the other microphone. That makes the final mix sound moody.
3341 This filter helps to solve phasing problems by adding different delays
3342 to each microphone track and make them synchronized.
3344 The best result can be reached when you take one track as base and
3345 synchronize other tracks one by one with it.
3346 Remember that synchronization/delay tolerance depends on sample rate, too.
3347 Higher sample rates will give more tolerance.
3349 The filter accepts the following parameters:
3353 Set millimeters distance. This is compensation distance for fine tuning.
3357 Set cm distance. This is compensation distance for tightening distance setup.
3361 Set meters distance. This is compensation distance for hard distance setup.
3365 Set dry amount. Amount of unprocessed (dry) signal.
3369 Set wet amount. Amount of processed (wet) signal.
3373 Set temperature in degrees Celsius. This is the temperature of the environment.
3378 Apply headphone crossfeed filter.
3380 Crossfeed is the process of blending the left and right channels of stereo
3382 It is mainly used to reduce extreme stereo separation of low frequencies.
3384 The intent is to produce more speaker like sound to the listener.
3386 The filter accepts the following options:
3390 Set strength of crossfeed. Default is 0.2. Allowed range is from 0 to 1.
3391 This sets gain of low shelf filter for side part of stereo image.
3392 Default is -6dB. Max allowed is -30db when strength is set to 1.
3395 Set soundstage wideness. Default is 0.5. Allowed range is from 0 to 1.
3396 This sets cut off frequency of low shelf filter. Default is cut off near
3397 1550 Hz. With range set to 1 cut off frequency is set to 2100 Hz.
3400 Set curve slope of low shelf filter. Default is 0.5.
3401 Allowed range is from 0.01 to 1.
3404 Set input gain. Default is 0.9.
3407 Set output gain. Default is 1.
3410 @subsection Commands
3412 This filter supports the all above options as @ref{commands}.
3414 @section crystalizer
3415 Simple algorithm to expand audio dynamic range.
3417 The filter accepts the following options:
3421 Sets the intensity of effect (default: 2.0). Must be in range between 0.0
3422 (unchanged sound) to 10.0 (maximum effect).
3425 Enable clipping. By default is enabled.
3428 @subsection Commands
3430 This filter supports the all above options as @ref{commands}.
3433 Apply a DC shift to the audio.
3435 This can be useful to remove a DC offset (caused perhaps by a hardware problem
3436 in the recording chain) from the audio. The effect of a DC offset is reduced
3437 headroom and hence volume. The @ref{astats} filter can be used to determine if
3438 a signal has a DC offset.
3442 Set the DC shift, allowed range is [-1, 1]. It indicates the amount to shift
3446 Optional. It should have a value much less than 1 (e.g. 0.05 or 0.02) and is
3447 used to prevent clipping.
3452 Apply de-essing to the audio samples.
3456 Set intensity for triggering de-essing. Allowed range is from 0 to 1.
3460 Set amount of ducking on treble part of sound. Allowed range is from 0 to 1.
3464 How much of original frequency content to keep when de-essing. Allowed range is from 0 to 1.
3468 Set the output mode.
3470 It accepts the following values:
3473 Pass input unchanged.
3476 Pass ess filtered out.
3481 Default value is @var{o}.
3487 Measure audio dynamic range.
3489 DR values of 14 and higher is found in very dynamic material. DR of 8 to 13
3490 is found in transition material. And anything less that 8 have very poor dynamics
3491 and is very compressed.
3493 The filter accepts the following options:
3497 Set window length in seconds used to split audio into segments of equal length.
3498 Default is 3 seconds.
3502 Dynamic Audio Normalizer.
3504 This filter applies a certain amount of gain to the input audio in order
3505 to bring its peak magnitude to a target level (e.g. 0 dBFS). However, in
3506 contrast to more "simple" normalization algorithms, the Dynamic Audio
3507 Normalizer *dynamically* re-adjusts the gain factor to the input audio.
3508 This allows for applying extra gain to the "quiet" sections of the audio
3509 while avoiding distortions or clipping the "loud" sections. In other words:
3510 The Dynamic Audio Normalizer will "even out" the volume of quiet and loud
3511 sections, in the sense that the volume of each section is brought to the
3512 same target level. Note, however, that the Dynamic Audio Normalizer achieves
3513 this goal *without* applying "dynamic range compressing". It will retain 100%
3514 of the dynamic range *within* each section of the audio file.
3518 Set the frame length in milliseconds. In range from 10 to 8000 milliseconds.
3519 Default is 500 milliseconds.
3520 The Dynamic Audio Normalizer processes the input audio in small chunks,
3521 referred to as frames. This is required, because a peak magnitude has no
3522 meaning for just a single sample value. Instead, we need to determine the
3523 peak magnitude for a contiguous sequence of sample values. While a "standard"
3524 normalizer would simply use the peak magnitude of the complete file, the
3525 Dynamic Audio Normalizer determines the peak magnitude individually for each
3526 frame. The length of a frame is specified in milliseconds. By default, the
3527 Dynamic Audio Normalizer uses a frame length of 500 milliseconds, which has
3528 been found to give good results with most files.
3529 Note that the exact frame length, in number of samples, will be determined
3530 automatically, based on the sampling rate of the individual input audio file.
3533 Set the Gaussian filter window size. In range from 3 to 301, must be odd
3534 number. Default is 31.
3535 Probably the most important parameter of the Dynamic Audio Normalizer is the
3536 @code{window size} of the Gaussian smoothing filter. The filter's window size
3537 is specified in frames, centered around the current frame. For the sake of
3538 simplicity, this must be an odd number. Consequently, the default value of 31
3539 takes into account the current frame, as well as the 15 preceding frames and
3540 the 15 subsequent frames. Using a larger window results in a stronger
3541 smoothing effect and thus in less gain variation, i.e. slower gain
3542 adaptation. Conversely, using a smaller window results in a weaker smoothing
3543 effect and thus in more gain variation, i.e. faster gain adaptation.
3544 In other words, the more you increase this value, the more the Dynamic Audio
3545 Normalizer will behave like a "traditional" normalization filter. On the
3546 contrary, the more you decrease this value, the more the Dynamic Audio
3547 Normalizer will behave like a dynamic range compressor.
3550 Set the target peak value. This specifies the highest permissible magnitude
3551 level for the normalized audio input. This filter will try to approach the
3552 target peak magnitude as closely as possible, but at the same time it also
3553 makes sure that the normalized signal will never exceed the peak magnitude.
3554 A frame's maximum local gain factor is imposed directly by the target peak
3555 magnitude. The default value is 0.95 and thus leaves a headroom of 5%*.
3556 It is not recommended to go above this value.
3559 Set the maximum gain factor. In range from 1.0 to 100.0. Default is 10.0.
3560 The Dynamic Audio Normalizer determines the maximum possible (local) gain
3561 factor for each input frame, i.e. the maximum gain factor that does not
3562 result in clipping or distortion. The maximum gain factor is determined by
3563 the frame's highest magnitude sample. However, the Dynamic Audio Normalizer
3564 additionally bounds the frame's maximum gain factor by a predetermined
3565 (global) maximum gain factor. This is done in order to avoid excessive gain
3566 factors in "silent" or almost silent frames. By default, the maximum gain
3567 factor is 10.0, For most inputs the default value should be sufficient and
3568 it usually is not recommended to increase this value. Though, for input
3569 with an extremely low overall volume level, it may be necessary to allow even
3570 higher gain factors. Note, however, that the Dynamic Audio Normalizer does
3571 not simply apply a "hard" threshold (i.e. cut off values above the threshold).
3572 Instead, a "sigmoid" threshold function will be applied. This way, the
3573 gain factors will smoothly approach the threshold value, but never exceed that
3577 Set the target RMS. In range from 0.0 to 1.0. Default is 0.0 - disabled.
3578 By default, the Dynamic Audio Normalizer performs "peak" normalization.
3579 This means that the maximum local gain factor for each frame is defined
3580 (only) by the frame's highest magnitude sample. This way, the samples can
3581 be amplified as much as possible without exceeding the maximum signal
3582 level, i.e. without clipping. Optionally, however, the Dynamic Audio
3583 Normalizer can also take into account the frame's root mean square,
3584 abbreviated RMS. In electrical engineering, the RMS is commonly used to
3585 determine the power of a time-varying signal. It is therefore considered
3586 that the RMS is a better approximation of the "perceived loudness" than
3587 just looking at the signal's peak magnitude. Consequently, by adjusting all
3588 frames to a constant RMS value, a uniform "perceived loudness" can be
3589 established. If a target RMS value has been specified, a frame's local gain
3590 factor is defined as the factor that would result in exactly that RMS value.
3591 Note, however, that the maximum local gain factor is still restricted by the
3592 frame's highest magnitude sample, in order to prevent clipping.
3595 Enable channels coupling. By default is enabled.
3596 By default, the Dynamic Audio Normalizer will amplify all channels by the same
3597 amount. This means the same gain factor will be applied to all channels, i.e.
3598 the maximum possible gain factor is determined by the "loudest" channel.
3599 However, in some recordings, it may happen that the volume of the different
3600 channels is uneven, e.g. one channel may be "quieter" than the other one(s).
3601 In this case, this option can be used to disable the channel coupling. This way,
3602 the gain factor will be determined independently for each channel, depending
3603 only on the individual channel's highest magnitude sample. This allows for
3604 harmonizing the volume of the different channels.
3607 Enable DC bias correction. By default is disabled.
3608 An audio signal (in the time domain) is a sequence of sample values.
3609 In the Dynamic Audio Normalizer these sample values are represented in the
3610 -1.0 to 1.0 range, regardless of the original input format. Normally, the
3611 audio signal, or "waveform", should be centered around the zero point.
3612 That means if we calculate the mean value of all samples in a file, or in a
3613 single frame, then the result should be 0.0 or at least very close to that
3614 value. If, however, there is a significant deviation of the mean value from
3615 0.0, in either positive or negative direction, this is referred to as a
3616 DC bias or DC offset. Since a DC bias is clearly undesirable, the Dynamic
3617 Audio Normalizer provides optional DC bias correction.
3618 With DC bias correction enabled, the Dynamic Audio Normalizer will determine
3619 the mean value, or "DC correction" offset, of each input frame and subtract
3620 that value from all of the frame's sample values which ensures those samples
3621 are centered around 0.0 again. Also, in order to avoid "gaps" at the frame
3622 boundaries, the DC correction offset values will be interpolated smoothly
3623 between neighbouring frames.
3625 @item altboundary, b
3626 Enable alternative boundary mode. By default is disabled.
3627 The Dynamic Audio Normalizer takes into account a certain neighbourhood
3628 around each frame. This includes the preceding frames as well as the
3629 subsequent frames. However, for the "boundary" frames, located at the very
3630 beginning and at the very end of the audio file, not all neighbouring
3631 frames are available. In particular, for the first few frames in the audio
3632 file, the preceding frames are not known. And, similarly, for the last few
3633 frames in the audio file, the subsequent frames are not known. Thus, the
3634 question arises which gain factors should be assumed for the missing frames
3635 in the "boundary" region. The Dynamic Audio Normalizer implements two modes
3636 to deal with this situation. The default boundary mode assumes a gain factor
3637 of exactly 1.0 for the missing frames, resulting in a smooth "fade in" and
3638 "fade out" at the beginning and at the end of the input, respectively.
3641 Set the compress factor. In range from 0.0 to 30.0. Default is 0.0.
3642 By default, the Dynamic Audio Normalizer does not apply "traditional"
3643 compression. This means that signal peaks will not be pruned and thus the
3644 full dynamic range will be retained within each local neighbourhood. However,
3645 in some cases it may be desirable to combine the Dynamic Audio Normalizer's
3646 normalization algorithm with a more "traditional" compression.
3647 For this purpose, the Dynamic Audio Normalizer provides an optional compression
3648 (thresholding) function. If (and only if) the compression feature is enabled,
3649 all input frames will be processed by a soft knee thresholding function prior
3650 to the actual normalization process. Put simply, the thresholding function is
3651 going to prune all samples whose magnitude exceeds a certain threshold value.
3652 However, the Dynamic Audio Normalizer does not simply apply a fixed threshold
3653 value. Instead, the threshold value will be adjusted for each individual
3655 In general, smaller parameters result in stronger compression, and vice versa.
3656 Values below 3.0 are not recommended, because audible distortion may appear.
3659 Set the target threshold value. This specifies the lowest permissible
3660 magnitude level for the audio input which will be normalized.
3661 If input frame volume is above this value frame will be normalized.
3662 Otherwise frame may not be normalized at all. The default value is set
3663 to 0, which means all input frames will be normalized.
3664 This option is mostly useful if digital noise is not wanted to be amplified.
3667 @subsection Commands
3669 This filter supports the all above options as @ref{commands}.
3673 Make audio easier to listen to on headphones.
3675 This filter adds `cues' to 44.1kHz stereo (i.e. audio CD format) audio
3676 so that when listened to on headphones the stereo image is moved from
3677 inside your head (standard for headphones) to outside and in front of
3678 the listener (standard for speakers).
3684 Apply a two-pole peaking equalisation (EQ) filter. With this
3685 filter, the signal-level at and around a selected frequency can
3686 be increased or decreased, whilst (unlike bandpass and bandreject
3687 filters) that at all other frequencies is unchanged.
3689 In order to produce complex equalisation curves, this filter can
3690 be given several times, each with a different central frequency.
3692 The filter accepts the following options:
3696 Set the filter's central frequency in Hz.
3699 Set method to specify band-width of filter.
3714 Specify the band-width of a filter in width_type units.
3717 Set the required gain or attenuation in dB.
3718 Beware of clipping when using a positive gain.
3721 How much to use filtered signal in output. Default is 1.
3722 Range is between 0 and 1.
3725 Specify which channels to filter, by default all available are filtered.
3728 Normalize biquad coefficients, by default is disabled.
3729 Enabling it will normalize magnitude response at DC to 0dB.
3732 Set transform type of IIR filter.
3741 @subsection Examples
3744 Attenuate 10 dB at 1000 Hz, with a bandwidth of 200 Hz:
3746 equalizer=f=1000:t=h:width=200:g=-10
3750 Apply 2 dB gain at 1000 Hz with Q 1 and attenuate 5 dB at 100 Hz with Q 2:
3752 equalizer=f=1000:t=q:w=1:g=2,equalizer=f=100:t=q:w=2:g=-5
3756 @subsection Commands
3758 This filter supports the following commands:
3761 Change equalizer frequency.
3762 Syntax for the command is : "@var{frequency}"
3765 Change equalizer width_type.
3766 Syntax for the command is : "@var{width_type}"
3769 Change equalizer width.
3770 Syntax for the command is : "@var{width}"
3773 Change equalizer gain.
3774 Syntax for the command is : "@var{gain}"
3777 Change equalizer mix.
3778 Syntax for the command is : "@var{mix}"
3781 @section extrastereo
3783 Linearly increases the difference between left and right channels which
3784 adds some sort of "live" effect to playback.
3786 The filter accepts the following options:
3790 Sets the difference coefficient (default: 2.5). 0.0 means mono sound
3791 (average of both channels), with 1.0 sound will be unchanged, with
3792 -1.0 left and right channels will be swapped.
3795 Enable clipping. By default is enabled.
3798 @subsection Commands
3800 This filter supports the all above options as @ref{commands}.
3802 @section firequalizer
3803 Apply FIR Equalization using arbitrary frequency response.
3805 The filter accepts the following option:
3809 Set gain curve equation (in dB). The expression can contain variables:
3812 the evaluated frequency
3816 channel number, set to 0 when multichannels evaluation is disabled
3818 channel id, see libavutil/channel_layout.h, set to the first channel id when
3819 multichannels evaluation is disabled
3823 channel_layout, see libavutil/channel_layout.h
3828 @item gain_interpolate(f)
3829 interpolate gain on frequency f based on gain_entry
3830 @item cubic_interpolate(f)
3831 same as gain_interpolate, but smoother
3833 This option is also available as command. Default is @code{gain_interpolate(f)}.
3836 Set gain entry for gain_interpolate function. The expression can
3840 store gain entry at frequency f with value g
3842 This option is also available as command.
3845 Set filter delay in seconds. Higher value means more accurate.
3846 Default is @code{0.01}.
3849 Set filter accuracy in Hz. Lower value means more accurate.
3850 Default is @code{5}.
3853 Set window function. Acceptable values are:
3856 rectangular window, useful when gain curve is already smooth
3858 hann window (default)
3864 3-terms continuous 1st derivative nuttall window
3866 minimum 3-terms discontinuous nuttall window
3868 4-terms continuous 1st derivative nuttall window
3870 minimum 4-terms discontinuous nuttall (blackman-nuttall) window
3872 blackman-harris window
3878 If enabled, use fixed number of audio samples. This improves speed when
3879 filtering with large delay. Default is disabled.
3882 Enable multichannels evaluation on gain. Default is disabled.
3885 Enable zero phase mode by subtracting timestamp to compensate delay.
3886 Default is disabled.
3889 Set scale used by gain. Acceptable values are:
3892 linear frequency, linear gain
3894 linear frequency, logarithmic (in dB) gain (default)
3896 logarithmic (in octave scale where 20 Hz is 0) frequency, linear gain
3898 logarithmic frequency, logarithmic gain
3902 Set file for dumping, suitable for gnuplot.
3905 Set scale for dumpfile. Acceptable values are same with scale option.
3909 Enable 2-channel convolution using complex FFT. This improves speed significantly.
3910 Default is disabled.
3913 Enable minimum phase impulse response. Default is disabled.
3916 @subsection Examples
3921 firequalizer=gain='if(lt(f,1000), 0, -INF)'
3924 lowpass at 1000 Hz with gain_entry:
3926 firequalizer=gain_entry='entry(1000,0); entry(1001, -INF)'
3929 custom equalization:
3931 firequalizer=gain_entry='entry(100,0); entry(400, -4); entry(1000, -6); entry(2000, 0)'
3934 higher delay with zero phase to compensate delay:
3936 firequalizer=delay=0.1:fixed=on:zero_phase=on
3939 lowpass on left channel, highpass on right channel:
3941 firequalizer=gain='if(eq(chid,1), gain_interpolate(f), if(eq(chid,2), gain_interpolate(1e6+f), 0))'
3942 :gain_entry='entry(1000, 0); entry(1001,-INF); entry(1e6+1000,0)':multi=on
3947 Apply a flanging effect to the audio.
3949 The filter accepts the following options:
3953 Set base delay in milliseconds. Range from 0 to 30. Default value is 0.
3956 Set added sweep delay in milliseconds. Range from 0 to 10. Default value is 2.
3959 Set percentage regeneration (delayed signal feedback). Range from -95 to 95.
3963 Set percentage of delayed signal mixed with original. Range from 0 to 100.
3964 Default value is 71.
3967 Set sweeps per second (Hz). Range from 0.1 to 10. Default value is 0.5.
3970 Set swept wave shape, can be @var{triangular} or @var{sinusoidal}.
3971 Default value is @var{sinusoidal}.
3974 Set swept wave percentage-shift for multi channel. Range from 0 to 100.
3975 Default value is 25.
3978 Set delay-line interpolation, @var{linear} or @var{quadratic}.
3979 Default is @var{linear}.
3983 Apply Haas effect to audio.
3985 Note that this makes most sense to apply on mono signals.
3986 With this filter applied to mono signals it give some directionality and
3987 stretches its stereo image.
3989 The filter accepts the following options:
3993 Set input level. By default is @var{1}, or 0dB
3996 Set output level. By default is @var{1}, or 0dB.
3999 Set gain applied to side part of signal. By default is @var{1}.
4002 Set kind of middle source. Can be one of the following:
4012 Pick middle part signal of stereo image.
4015 Pick side part signal of stereo image.
4019 Change middle phase. By default is disabled.
4022 Set left channel delay. By default is @var{2.05} milliseconds.
4025 Set left channel balance. By default is @var{-1}.
4028 Set left channel gain. By default is @var{1}.
4031 Change left phase. By default is disabled.
4034 Set right channel delay. By defaults is @var{2.12} milliseconds.
4037 Set right channel balance. By default is @var{1}.
4040 Set right channel gain. By default is @var{1}.
4043 Change right phase. By default is enabled.
4048 Decodes High Definition Compatible Digital (HDCD) data. A 16-bit PCM stream with
4049 embedded HDCD codes is expanded into a 20-bit PCM stream.
4051 The filter supports the Peak Extend and Low-level Gain Adjustment features
4052 of HDCD, and detects the Transient Filter flag.
4055 ffmpeg -i HDCD16.flac -af hdcd OUT24.flac
4058 When using the filter with wav, note the default encoding for wav is 16-bit,
4059 so the resulting 20-bit stream will be truncated back to 16-bit. Use something
4060 like @command{-acodec pcm_s24le} after the filter to get 24-bit PCM output.
4062 ffmpeg -i HDCD16.wav -af hdcd OUT16.wav
4063 ffmpeg -i HDCD16.wav -af hdcd -c:a pcm_s24le OUT24.wav
4066 The filter accepts the following options:
4069 @item disable_autoconvert
4070 Disable any automatic format conversion or resampling in the filter graph.
4072 @item process_stereo
4073 Process the stereo channels together. If target_gain does not match between
4074 channels, consider it invalid and use the last valid target_gain.
4077 Set the code detect timer period in ms.
4080 Always extend peaks above -3dBFS even if PE isn't signaled.
4083 Replace audio with a solid tone and adjust the amplitude to signal some
4084 specific aspect of the decoding process. The output file can be loaded in
4085 an audio editor alongside the original to aid analysis.
4087 @code{analyze_mode=pe:force_pe=true} can be used to see all samples above the PE level.
4094 Gain adjustment level at each sample
4096 Samples where peak extend occurs
4098 Samples where the code detect timer is active
4100 Samples where the target gain does not match between channels
4106 Apply head-related transfer functions (HRTFs) to create virtual
4107 loudspeakers around the user for binaural listening via headphones.
4108 The HRIRs are provided via additional streams, for each channel
4109 one stereo input stream is needed.
4111 The filter accepts the following options:
4115 Set mapping of input streams for convolution.
4116 The argument is a '|'-separated list of channel names in order as they
4117 are given as additional stream inputs for filter.
4118 This also specify number of input streams. Number of input streams
4119 must be not less than number of channels in first stream plus one.
4122 Set gain applied to audio. Value is in dB. Default is 0.
4125 Set processing type. Can be @var{time} or @var{freq}. @var{time} is
4126 processing audio in time domain which is slow.
4127 @var{freq} is processing audio in frequency domain which is fast.
4128 Default is @var{freq}.
4131 Set custom gain for LFE channels. Value is in dB. Default is 0.
4134 Set size of frame in number of samples which will be processed at once.
4135 Default value is @var{1024}. Allowed range is from 1024 to 96000.
4138 Set format of hrir stream.
4139 Default value is @var{stereo}. Alternative value is @var{multich}.
4140 If value is set to @var{stereo}, number of additional streams should
4141 be greater or equal to number of input channels in first input stream.
4142 Also each additional stream should have stereo number of channels.
4143 If value is set to @var{multich}, number of additional streams should
4144 be exactly one. Also number of input channels of additional stream
4145 should be equal or greater than twice number of channels of first input
4149 @subsection Examples
4153 Full example using wav files as coefficients with amovie filters for 7.1 downmix,
4154 each amovie filter use stereo file with IR coefficients as input.
4155 The files give coefficients for each position of virtual loudspeaker:
4158 -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"
4163 Full example using wav files as coefficients with amovie filters for 7.1 downmix,
4164 but now in @var{multich} @var{hrir} format.
4166 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"
4173 Apply a high-pass filter with 3dB point frequency.
4174 The filter can be either single-pole, or double-pole (the default).
4175 The filter roll off at 6dB per pole per octave (20dB per pole per decade).
4177 The filter accepts the following options:
4181 Set frequency in Hz. Default is 3000.
4184 Set number of poles. Default is 2.
4187 Set method to specify band-width of filter.
4202 Specify the band-width of a filter in width_type units.
4203 Applies only to double-pole filter.
4204 The default is 0.707q and gives a Butterworth response.
4207 How much to use filtered signal in output. Default is 1.
4208 Range is between 0 and 1.
4211 Specify which channels to filter, by default all available are filtered.
4214 Normalize biquad coefficients, by default is disabled.
4215 Enabling it will normalize magnitude response at DC to 0dB.
4218 Set transform type of IIR filter.
4227 @subsection Commands
4229 This filter supports the following commands:
4232 Change highpass frequency.
4233 Syntax for the command is : "@var{frequency}"
4236 Change highpass width_type.
4237 Syntax for the command is : "@var{width_type}"
4240 Change highpass width.
4241 Syntax for the command is : "@var{width}"
4244 Change highpass mix.
4245 Syntax for the command is : "@var{mix}"
4250 Join multiple input streams into one multi-channel stream.
4252 It accepts the following parameters:
4256 The number of input streams. It defaults to 2.
4258 @item channel_layout
4259 The desired output channel layout. It defaults to stereo.
4262 Map channels from inputs to output. The argument is a '|'-separated list of
4263 mappings, each in the @code{@var{input_idx}.@var{in_channel}-@var{out_channel}}
4264 form. @var{input_idx} is the 0-based index of the input stream. @var{in_channel}
4265 can be either the name of the input channel (e.g. FL for front left) or its
4266 index in the specified input stream. @var{out_channel} is the name of the output
4270 The filter will attempt to guess the mappings when they are not specified
4271 explicitly. It does so by first trying to find an unused matching input channel
4272 and if that fails it picks the first unused input channel.
4274 Join 3 inputs (with properly set channel layouts):
4276 ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT
4279 Build a 5.1 output from 6 single-channel streams:
4281 ffmpeg -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex
4282 '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'
4288 Load a LADSPA (Linux Audio Developer's Simple Plugin API) plugin.
4290 To enable compilation of this filter you need to configure FFmpeg with
4291 @code{--enable-ladspa}.
4295 Specifies the name of LADSPA plugin library to load. If the environment
4296 variable @env{LADSPA_PATH} is defined, the LADSPA plugin is searched in
4297 each one of the directories specified by the colon separated list in
4298 @env{LADSPA_PATH}, otherwise in the standard LADSPA paths, which are in
4299 this order: @file{HOME/.ladspa/lib/}, @file{/usr/local/lib/ladspa/},
4300 @file{/usr/lib/ladspa/}.
4303 Specifies the plugin within the library. Some libraries contain only
4304 one plugin, but others contain many of them. If this is not set filter
4305 will list all available plugins within the specified library.
4308 Set the '|' separated list of controls which are zero or more floating point
4309 values that determine the behavior of the loaded plugin (for example delay,
4311 Controls need to be defined using the following syntax:
4312 c0=@var{value0}|c1=@var{value1}|c2=@var{value2}|..., where
4313 @var{valuei} is the value set on the @var{i}-th control.
4314 Alternatively they can be also defined using the following syntax:
4315 @var{value0}|@var{value1}|@var{value2}|..., where
4316 @var{valuei} is the value set on the @var{i}-th control.
4317 If @option{controls} is set to @code{help}, all available controls and
4318 their valid ranges are printed.
4320 @item sample_rate, s
4321 Specify the sample rate, default to 44100. Only used if plugin have
4325 Set the number of samples per channel per each output frame, default
4326 is 1024. Only used if plugin have zero inputs.
4329 Set the minimum duration of the sourced audio. See
4330 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
4331 for the accepted syntax.
4332 Note that the resulting duration may be greater than the specified duration,
4333 as the generated audio is always cut at the end of a complete frame.
4334 If not specified, or the expressed duration is negative, the audio is
4335 supposed to be generated forever.
4336 Only used if plugin have zero inputs.
4339 Enable latency compensation, by default is disabled.
4340 Only used if plugin have inputs.
4343 @subsection Examples
4347 List all available plugins within amp (LADSPA example plugin) library:
4353 List all available controls and their valid ranges for @code{vcf_notch}
4354 plugin from @code{VCF} library:
4356 ladspa=f=vcf:p=vcf_notch:c=help
4360 Simulate low quality audio equipment using @code{Computer Music Toolkit} (CMT)
4363 ladspa=file=cmt:plugin=lofi:controls=c0=22|c1=12|c2=12
4367 Add reverberation to the audio using TAP-plugins
4368 (Tom's Audio Processing plugins):
4370 ladspa=file=tap_reverb:tap_reverb
4374 Generate white noise, with 0.2 amplitude:
4376 ladspa=file=cmt:noise_source_white:c=c0=.2
4380 Generate 20 bpm clicks using plugin @code{C* Click - Metronome} from the
4381 @code{C* Audio Plugin Suite} (CAPS) library:
4383 ladspa=file=caps:Click:c=c1=20'
4387 Apply @code{C* Eq10X2 - Stereo 10-band equaliser} effect:
4389 ladspa=caps:Eq10X2:c=c0=-48|c9=-24|c3=12|c4=2
4393 Increase volume by 20dB using fast lookahead limiter from Steve Harris
4394 @code{SWH Plugins} collection:
4396 ladspa=fast_lookahead_limiter_1913:fastLookaheadLimiter:20|0|2
4400 Attenuate low frequencies using Multiband EQ from Steve Harris
4401 @code{SWH Plugins} collection:
4403 ladspa=mbeq_1197:mbeq:-24|-24|-24|0|0|0|0|0|0|0|0|0|0|0|0
4407 Reduce stereo image using @code{Narrower} from the @code{C* Audio Plugin Suite}
4410 ladspa=caps:Narrower
4414 Another white noise, now using @code{C* Audio Plugin Suite} (CAPS) library:
4416 ladspa=caps:White:.2
4420 Some fractal noise, using @code{C* Audio Plugin Suite} (CAPS) library:
4422 ladspa=caps:Fractal:c=c1=1
4426 Dynamic volume normalization using @code{VLevel} plugin:
4428 ladspa=vlevel-ladspa:vlevel_mono
4432 @subsection Commands
4434 This filter supports the following commands:
4437 Modify the @var{N}-th control value.
4439 If the specified value is not valid, it is ignored and prior one is kept.
4444 EBU R128 loudness normalization. Includes both dynamic and linear normalization modes.
4445 Support for both single pass (livestreams, files) and double pass (files) modes.
4446 This algorithm can target IL, LRA, and maximum true peak. In dynamic mode, to accurately
4447 detect true peaks, the audio stream will be upsampled to 192 kHz.
4448 Use the @code{-ar} option or @code{aresample} filter to explicitly set an output sample rate.
4450 The filter accepts the following options:
4454 Set integrated loudness target.
4455 Range is -70.0 - -5.0. Default value is -24.0.
4458 Set loudness range target.
4459 Range is 1.0 - 20.0. Default value is 7.0.
4462 Set maximum true peak.
4463 Range is -9.0 - +0.0. Default value is -2.0.
4465 @item measured_I, measured_i
4466 Measured IL of input file.
4467 Range is -99.0 - +0.0.
4469 @item measured_LRA, measured_lra
4470 Measured LRA of input file.
4471 Range is 0.0 - 99.0.
4473 @item measured_TP, measured_tp
4474 Measured true peak of input file.
4475 Range is -99.0 - +99.0.
4477 @item measured_thresh
4478 Measured threshold of input file.
4479 Range is -99.0 - +0.0.
4482 Set offset gain. Gain is applied before the true-peak limiter.
4483 Range is -99.0 - +99.0. Default is +0.0.
4486 Normalize by linearly scaling the source audio.
4487 @code{measured_I}, @code{measured_LRA}, @code{measured_TP},
4488 and @code{measured_thresh} must all be specified. Target LRA shouldn't
4489 be lower than source LRA and the change in integrated loudness shouldn't
4490 result in a true peak which exceeds the target TP. If any of these
4491 conditions aren't met, normalization mode will revert to @var{dynamic}.
4492 Options are @code{true} or @code{false}. Default is @code{true}.
4495 Treat mono input files as "dual-mono". If a mono file is intended for playback
4496 on a stereo system, its EBU R128 measurement will be perceptually incorrect.
4497 If set to @code{true}, this option will compensate for this effect.
4498 Multi-channel input files are not affected by this option.
4499 Options are true or false. Default is false.
4502 Set print format for stats. Options are summary, json, or none.
4503 Default value is none.
4508 Apply a low-pass filter with 3dB point frequency.
4509 The filter can be either single-pole or double-pole (the default).
4510 The filter roll off at 6dB per pole per octave (20dB per pole per decade).
4512 The filter accepts the following options:
4516 Set frequency in Hz. Default is 500.
4519 Set number of poles. Default is 2.
4522 Set method to specify band-width of filter.
4537 Specify the band-width of a filter in width_type units.
4538 Applies only to double-pole filter.
4539 The default is 0.707q and gives a Butterworth response.
4542 How much to use filtered signal in output. Default is 1.
4543 Range is between 0 and 1.
4546 Specify which channels to filter, by default all available are filtered.
4549 Normalize biquad coefficients, by default is disabled.
4550 Enabling it will normalize magnitude response at DC to 0dB.
4553 Set transform type of IIR filter.
4562 @subsection Examples
4565 Lowpass only LFE channel, it LFE is not present it does nothing:
4571 @subsection Commands
4573 This filter supports the following commands:
4576 Change lowpass frequency.
4577 Syntax for the command is : "@var{frequency}"
4580 Change lowpass width_type.
4581 Syntax for the command is : "@var{width_type}"
4584 Change lowpass width.
4585 Syntax for the command is : "@var{width}"
4589 Syntax for the command is : "@var{mix}"
4594 Load a LV2 (LADSPA Version 2) plugin.
4596 To enable compilation of this filter you need to configure FFmpeg with
4597 @code{--enable-lv2}.
4601 Specifies the plugin URI. You may need to escape ':'.
4604 Set the '|' separated list of controls which are zero or more floating point
4605 values that determine the behavior of the loaded plugin (for example delay,
4607 If @option{controls} is set to @code{help}, all available controls and
4608 their valid ranges are printed.
4610 @item sample_rate, s
4611 Specify the sample rate, default to 44100. Only used if plugin have
4615 Set the number of samples per channel per each output frame, default
4616 is 1024. Only used if plugin have zero inputs.
4619 Set the minimum duration of the sourced audio. See
4620 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
4621 for the accepted syntax.
4622 Note that the resulting duration may be greater than the specified duration,
4623 as the generated audio is always cut at the end of a complete frame.
4624 If not specified, or the expressed duration is negative, the audio is
4625 supposed to be generated forever.
4626 Only used if plugin have zero inputs.
4629 @subsection Examples
4633 Apply bass enhancer plugin from Calf:
4635 lv2=p=http\\\\://calf.sourceforge.net/plugins/BassEnhancer:c=amount=2
4639 Apply vinyl plugin from Calf:
4641 lv2=p=http\\\\://calf.sourceforge.net/plugins/Vinyl:c=drone=0.2|aging=0.5
4645 Apply bit crusher plugin from ArtyFX:
4647 lv2=p=http\\\\://www.openavproductions.com/artyfx#bitta:c=crush=0.3
4652 Multiband Compress or expand the audio's dynamic range.
4654 The input audio is divided into bands using 4th order Linkwitz-Riley IIRs.
4655 This is akin to the crossover of a loudspeaker, and results in flat frequency
4656 response when absent compander action.
4658 It accepts the following parameters:
4662 This option syntax is:
4663 attack,decay,[attack,decay..] soft-knee points crossover_frequency [delay [initial_volume [gain]]] | attack,decay ...
4664 For explanation of each item refer to compand filter documentation.
4670 Mix channels with specific gain levels. The filter accepts the output
4671 channel layout followed by a set of channels definitions.
4673 This filter is also designed to efficiently remap the channels of an audio
4676 The filter accepts parameters of the form:
4677 "@var{l}|@var{outdef}|@var{outdef}|..."
4681 output channel layout or number of channels
4684 output channel specification, of the form:
4685 "@var{out_name}=[@var{gain}*]@var{in_name}[(+-)[@var{gain}*]@var{in_name}...]"
4688 output channel to define, either a channel name (FL, FR, etc.) or a channel
4689 number (c0, c1, etc.)
4692 multiplicative coefficient for the channel, 1 leaving the volume unchanged
4695 input channel to use, see out_name for details; it is not possible to mix
4696 named and numbered input channels
4699 If the `=' in a channel specification is replaced by `<', then the gains for
4700 that specification will be renormalized so that the total is 1, thus
4701 avoiding clipping noise.
4703 @subsection Mixing examples
4705 For example, if you want to down-mix from stereo to mono, but with a bigger
4706 factor for the left channel:
4708 pan=1c|c0=0.9*c0+0.1*c1
4711 A customized down-mix to stereo that works automatically for 3-, 4-, 5- and
4712 7-channels surround:
4714 pan=stereo| FL < FL + 0.5*FC + 0.6*BL + 0.6*SL | FR < FR + 0.5*FC + 0.6*BR + 0.6*SR
4717 Note that @command{ffmpeg} integrates a default down-mix (and up-mix) system
4718 that should be preferred (see "-ac" option) unless you have very specific
4721 @subsection Remapping examples
4723 The channel remapping will be effective if, and only if:
4726 @item gain coefficients are zeroes or ones,
4727 @item only one input per channel output,
4730 If all these conditions are satisfied, the filter will notify the user ("Pure
4731 channel mapping detected"), and use an optimized and lossless method to do the
4734 For example, if you have a 5.1 source and want a stereo audio stream by
4735 dropping the extra channels:
4737 pan="stereo| c0=FL | c1=FR"
4740 Given the same source, you can also switch front left and front right channels
4741 and keep the input channel layout:
4743 pan="5.1| c0=c1 | c1=c0 | c2=c2 | c3=c3 | c4=c4 | c5=c5"
4746 If the input is a stereo audio stream, you can mute the front left channel (and
4747 still keep the stereo channel layout) with:
4752 Still with a stereo audio stream input, you can copy the right channel in both
4753 front left and right:
4755 pan="stereo| c0=FR | c1=FR"
4760 ReplayGain scanner filter. This filter takes an audio stream as an input and
4761 outputs it unchanged.
4762 At end of filtering it displays @code{track_gain} and @code{track_peak}.
4766 Convert the audio sample format, sample rate and channel layout. It is
4767 not meant to be used directly.
4770 Apply time-stretching and pitch-shifting with librubberband.
4772 To enable compilation of this filter, you need to configure FFmpeg with
4773 @code{--enable-librubberband}.
4775 The filter accepts the following options:
4779 Set tempo scale factor.
4782 Set pitch scale factor.
4785 Set transients detector.
4786 Possible values are:
4795 Possible values are:
4804 Possible values are:
4811 Set processing window size.
4812 Possible values are:
4821 Possible values are:
4828 Enable formant preservation when shift pitching.
4829 Possible values are:
4837 Possible values are:
4846 Possible values are:
4853 @subsection Commands
4855 This filter supports the following commands:
4858 Change filter tempo scale factor.
4859 Syntax for the command is : "@var{tempo}"
4862 Change filter pitch scale factor.
4863 Syntax for the command is : "@var{pitch}"
4866 @section sidechaincompress
4868 This filter acts like normal compressor but has the ability to compress
4869 detected signal using second input signal.
4870 It needs two input streams and returns one output stream.
4871 First input stream will be processed depending on second stream signal.
4872 The filtered signal then can be filtered with other filters in later stages of
4873 processing. See @ref{pan} and @ref{amerge} filter.
4875 The filter accepts the following options:
4879 Set input gain. Default is 1. Range is between 0.015625 and 64.
4882 Set mode of compressor operation. Can be @code{upward} or @code{downward}.
4883 Default is @code{downward}.
4886 If a signal of second stream raises above this level it will affect the gain
4887 reduction of first stream.
4888 By default is 0.125. Range is between 0.00097563 and 1.
4891 Set a ratio about which the signal is reduced. 1:2 means that if the level
4892 raised 4dB above the threshold, it will be only 2dB above after the reduction.
4893 Default is 2. Range is between 1 and 20.
4896 Amount of milliseconds the signal has to rise above the threshold before gain
4897 reduction starts. Default is 20. Range is between 0.01 and 2000.
4900 Amount of milliseconds the signal has to fall below the threshold before
4901 reduction is decreased again. Default is 250. Range is between 0.01 and 9000.
4904 Set the amount by how much signal will be amplified after processing.
4905 Default is 1. Range is from 1 to 64.
4908 Curve the sharp knee around the threshold to enter gain reduction more softly.
4909 Default is 2.82843. Range is between 1 and 8.
4912 Choose if the @code{average} level between all channels of side-chain stream
4913 or the louder(@code{maximum}) channel of side-chain stream affects the
4914 reduction. Default is @code{average}.
4917 Should the exact signal be taken in case of @code{peak} or an RMS one in case
4918 of @code{rms}. Default is @code{rms} which is mainly smoother.
4921 Set sidechain gain. Default is 1. Range is between 0.015625 and 64.
4924 How much to use compressed signal in output. Default is 1.
4925 Range is between 0 and 1.
4928 @subsection Commands
4930 This filter supports the all above options as @ref{commands}.
4932 @subsection Examples
4936 Full ffmpeg example taking 2 audio inputs, 1st input to be compressed
4937 depending on the signal of 2nd input and later compressed signal to be
4938 merged with 2nd input:
4940 ffmpeg -i main.flac -i sidechain.flac -filter_complex "[1:a]asplit=2[sc][mix];[0:a][sc]sidechaincompress[compr];[compr][mix]amerge"
4944 @section sidechaingate
4946 A sidechain gate acts like a normal (wideband) gate but has the ability to
4947 filter the detected signal before sending it to the gain reduction stage.
4948 Normally a gate uses the full range signal to detect a level above the
4950 For example: If you cut all lower frequencies from your sidechain signal
4951 the gate will decrease the volume of your track only if not enough highs
4952 appear. With this technique you are able to reduce the resonation of a
4953 natural drum or remove "rumbling" of muted strokes from a heavily distorted
4955 It needs two input streams and returns one output stream.
4956 First input stream will be processed depending on second stream signal.
4958 The filter accepts the following options:
4962 Set input level before filtering.
4963 Default is 1. Allowed range is from 0.015625 to 64.
4966 Set the mode of operation. Can be @code{upward} or @code{downward}.
4967 Default is @code{downward}. If set to @code{upward} mode, higher parts of signal
4968 will be amplified, expanding dynamic range in upward direction.
4969 Otherwise, in case of @code{downward} lower parts of signal will be reduced.
4972 Set the level of gain reduction when the signal is below the threshold.
4973 Default is 0.06125. Allowed range is from 0 to 1.
4974 Setting this to 0 disables reduction and then filter behaves like expander.
4977 If a signal rises above this level the gain reduction is released.
4978 Default is 0.125. Allowed range is from 0 to 1.
4981 Set a ratio about which the signal is reduced.
4982 Default is 2. Allowed range is from 1 to 9000.
4985 Amount of milliseconds the signal has to rise above the threshold before gain
4987 Default is 20 milliseconds. Allowed range is from 0.01 to 9000.
4990 Amount of milliseconds the signal has to fall below the threshold before the
4991 reduction is increased again. Default is 250 milliseconds.
4992 Allowed range is from 0.01 to 9000.
4995 Set amount of amplification of signal after processing.
4996 Default is 1. Allowed range is from 1 to 64.
4999 Curve the sharp knee around the threshold to enter gain reduction more softly.
5000 Default is 2.828427125. Allowed range is from 1 to 8.
5003 Choose if exact signal should be taken for detection or an RMS like one.
5004 Default is rms. Can be peak or rms.
5007 Choose if the average level between all channels or the louder channel affects
5009 Default is average. Can be average or maximum.
5012 Set sidechain gain. Default is 1. Range is from 0.015625 to 64.
5015 @section silencedetect
5017 Detect silence in an audio stream.
5019 This filter logs a message when it detects that the input audio volume is less
5020 or equal to a noise tolerance value for a duration greater or equal to the
5021 minimum detected noise duration.
5023 The printed times and duration are expressed in seconds. The
5024 @code{lavfi.silence_start} or @code{lavfi.silence_start.X} metadata key
5025 is set on the first frame whose timestamp equals or exceeds the detection
5026 duration and it contains the timestamp of the first frame of the silence.
5028 The @code{lavfi.silence_duration} or @code{lavfi.silence_duration.X}
5029 and @code{lavfi.silence_end} or @code{lavfi.silence_end.X} metadata
5030 keys are set on the first frame after the silence. If @option{mono} is
5031 enabled, and each channel is evaluated separately, the @code{.X}
5032 suffixed keys are used, and @code{X} corresponds to the channel number.
5034 The filter accepts the following options:
5038 Set noise tolerance. Can be specified in dB (in case "dB" is appended to the
5039 specified value) or amplitude ratio. Default is -60dB, or 0.001.
5042 Set silence duration until notification (default is 2 seconds). See
5043 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
5044 for the accepted syntax.
5047 Process each channel separately, instead of combined. By default is disabled.
5050 @subsection Examples
5054 Detect 5 seconds of silence with -50dB noise tolerance:
5056 silencedetect=n=-50dB:d=5
5060 Complete example with @command{ffmpeg} to detect silence with 0.0001 noise
5061 tolerance in @file{silence.mp3}:
5063 ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null -
5067 @section silenceremove
5069 Remove silence from the beginning, middle or end of the audio.
5071 The filter accepts the following options:
5075 This value is used to indicate if audio should be trimmed at beginning of
5076 the audio. A value of zero indicates no silence should be trimmed from the
5077 beginning. When specifying a non-zero value, it trims audio up until it
5078 finds non-silence. Normally, when trimming silence from beginning of audio
5079 the @var{start_periods} will be @code{1} but it can be increased to higher
5080 values to trim all audio up to specific count of non-silence periods.
5081 Default value is @code{0}.
5083 @item start_duration
5084 Specify the amount of time that non-silence must be detected before it stops
5085 trimming audio. By increasing the duration, bursts of noises can be treated
5086 as silence and trimmed off. Default value is @code{0}.
5088 @item start_threshold
5089 This indicates what sample value should be treated as silence. For digital
5090 audio, a value of @code{0} may be fine but for audio recorded from analog,
5091 you may wish to increase the value to account for background noise.
5092 Can be specified in dB (in case "dB" is appended to the specified value)
5093 or amplitude ratio. Default value is @code{0}.
5096 Specify max duration of silence at beginning that will be kept after
5097 trimming. Default is 0, which is equal to trimming all samples detected
5101 Specify mode of detection of silence end in start of multi-channel audio.
5102 Can be @var{any} or @var{all}. Default is @var{any}.
5103 With @var{any}, any sample that is detected as non-silence will cause
5104 stopped trimming of silence.
5105 With @var{all}, only if all channels are detected as non-silence will cause
5106 stopped trimming of silence.
5109 Set the count for trimming silence from the end of audio.
5110 To remove silence from the middle of a file, specify a @var{stop_periods}
5111 that is negative. This value is then treated as a positive value and is
5112 used to indicate the effect should restart processing as specified by
5113 @var{start_periods}, making it suitable for removing periods of silence
5114 in the middle of the audio.
5115 Default value is @code{0}.
5118 Specify a duration of silence that must exist before audio is not copied any
5119 more. By specifying a higher duration, silence that is wanted can be left in
5121 Default value is @code{0}.
5123 @item stop_threshold
5124 This is the same as @option{start_threshold} but for trimming silence from
5126 Can be specified in dB (in case "dB" is appended to the specified value)
5127 or amplitude ratio. Default value is @code{0}.
5130 Specify max duration of silence at end that will be kept after
5131 trimming. Default is 0, which is equal to trimming all samples detected
5135 Specify mode of detection of silence start in end of multi-channel audio.
5136 Can be @var{any} or @var{all}. Default is @var{any}.
5137 With @var{any}, any sample that is detected as non-silence will cause
5138 stopped trimming of silence.
5139 With @var{all}, only if all channels are detected as non-silence will cause
5140 stopped trimming of silence.
5143 Set how is silence detected. Can be @code{rms} or @code{peak}. Second is faster
5144 and works better with digital silence which is exactly 0.
5145 Default value is @code{rms}.
5148 Set duration in number of seconds used to calculate size of window in number
5149 of samples for detecting silence.
5150 Default value is @code{0.02}. Allowed range is from @code{0} to @code{10}.
5153 @subsection Examples
5157 The following example shows how this filter can be used to start a recording
5158 that does not contain the delay at the start which usually occurs between
5159 pressing the record button and the start of the performance:
5161 silenceremove=start_periods=1:start_duration=5:start_threshold=0.02
5165 Trim all silence encountered from beginning to end where there is more than 1
5166 second of silence in audio:
5168 silenceremove=stop_periods=-1:stop_duration=1:stop_threshold=-90dB
5172 Trim all digital silence samples, using peak detection, from beginning to end
5173 where there is more than 0 samples of digital silence in audio and digital
5174 silence is detected in all channels at same positions in stream:
5176 silenceremove=window=0:detection=peak:stop_mode=all:start_mode=all:stop_periods=-1:stop_threshold=0
5182 SOFAlizer uses head-related transfer functions (HRTFs) to create virtual
5183 loudspeakers around the user for binaural listening via headphones (audio
5184 formats up to 9 channels supported).
5185 The HRTFs are stored in SOFA files (see @url{http://www.sofacoustics.org/} for a database).
5186 SOFAlizer is developed at the Acoustics Research Institute (ARI) of the
5187 Austrian Academy of Sciences.
5189 To enable compilation of this filter you need to configure FFmpeg with
5190 @code{--enable-libmysofa}.
5192 The filter accepts the following options:
5196 Set the SOFA file used for rendering.
5199 Set gain applied to audio. Value is in dB. Default is 0.
5202 Set rotation of virtual loudspeakers in deg. Default is 0.
5205 Set elevation of virtual speakers in deg. Default is 0.
5208 Set distance in meters between loudspeakers and the listener with near-field
5209 HRTFs. Default is 1.
5212 Set processing type. Can be @var{time} or @var{freq}. @var{time} is
5213 processing audio in time domain which is slow.
5214 @var{freq} is processing audio in frequency domain which is fast.
5215 Default is @var{freq}.
5218 Set custom positions of virtual loudspeakers. Syntax for this option is:
5219 <CH> <AZIM> <ELEV>[|<CH> <AZIM> <ELEV>|...].
5220 Each virtual loudspeaker is described with short channel name following with
5221 azimuth and elevation in degrees.
5222 Each virtual loudspeaker description is separated by '|'.
5223 For example to override front left and front right channel positions use:
5224 'speakers=FL 45 15|FR 345 15'.
5225 Descriptions with unrecognised channel names are ignored.
5228 Set custom gain for LFE channels. Value is in dB. Default is 0.
5231 Set custom frame size in number of samples. Default is 1024.
5232 Allowed range is from 1024 to 96000. Only used if option @samp{type}
5233 is set to @var{freq}.
5236 Should all IRs be normalized upon importing SOFA file.
5237 By default is enabled.
5240 Should nearest IRs be interpolated with neighbor IRs if exact position
5241 does not match. By default is disabled.
5244 Minphase all IRs upon loading of SOFA file. By default is disabled.
5247 Set neighbor search angle step. Only used if option @var{interpolate} is enabled.
5250 Set neighbor search radius step. Only used if option @var{interpolate} is enabled.
5253 @subsection Examples
5257 Using ClubFritz6 sofa file:
5259 sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=1
5263 Using ClubFritz12 sofa file and bigger radius with small rotation:
5265 sofalizer=sofa=/path/to/ClubFritz12.sofa:type=freq:radius=2:rotation=5
5269 Similar as above but with custom speaker positions for front left, front right, back left and back right
5270 and also with custom gain:
5272 "sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=2:speakers=FL 45|FR 315|BL 135|BR 225:gain=28"
5279 This filter expands or compresses each half-cycle of audio samples
5280 (local set of samples all above or all below zero and between two nearest zero crossings) depending
5281 on threshold value, so audio reaches target peak value under conditions controlled by below options.
5283 The filter accepts the following options:
5287 Set the expansion target peak value. This specifies the highest allowed absolute amplitude
5288 level for the normalized audio input. Default value is 0.95. Allowed range is from 0.0 to 1.0.
5291 Set the maximum expansion factor. Allowed range is from 1.0 to 50.0. Default value is 2.0.
5292 This option controls maximum local half-cycle of samples expansion. The maximum expansion
5293 would be such that local peak value reaches target peak value but never to surpass it and that
5294 ratio between new and previous peak value does not surpass this option value.
5296 @item compression, c
5297 Set the maximum compression factor. Allowed range is from 1.0 to 50.0. Default value is 2.0.
5298 This option controls maximum local half-cycle of samples compression. This option is used
5299 only if @option{threshold} option is set to value greater than 0.0, then in such cases
5300 when local peak is lower or same as value set by @option{threshold} all samples belonging to
5301 that peak's half-cycle will be compressed by current compression factor.
5304 Set the threshold value. Default value is 0.0. Allowed range is from 0.0 to 1.0.
5305 This option specifies which half-cycles of samples will be compressed and which will be expanded.
5306 Any half-cycle samples with their local peak value below or same as this option value will be
5307 compressed by current compression factor, otherwise, if greater than threshold value they will be
5308 expanded with expansion factor so that it could reach peak target value but never surpass it.
5311 Set the expansion raising amount per each half-cycle of samples. Default value is 0.001.
5312 Allowed range is from 0.0 to 1.0. This controls how fast expansion factor is raised per
5313 each new half-cycle until it reaches @option{expansion} value.
5314 Setting this options too high may lead to distortions.
5317 Set the compression raising amount per each half-cycle of samples. Default value is 0.001.
5318 Allowed range is from 0.0 to 1.0. This controls how fast compression factor is raised per
5319 each new half-cycle until it reaches @option{compression} value.
5322 Specify which channels to filter, by default all available channels are filtered.
5325 Enable inverted filtering, by default is disabled. This inverts interpretation of @option{threshold}
5326 option. When enabled any half-cycle of samples with their local peak value below or same as
5327 @option{threshold} option will be expanded otherwise it will be compressed.
5330 Link channels when calculating gain applied to each filtered channel sample, by default is disabled.
5331 When disabled each filtered channel gain calculation is independent, otherwise when this option
5332 is enabled the minimum of all possible gains for each filtered channel is used.
5335 @subsection Commands
5337 This filter supports the all above options as @ref{commands}.
5339 @section stereotools
5341 This filter has some handy utilities to manage stereo signals, for converting
5342 M/S stereo recordings to L/R signal while having control over the parameters
5343 or spreading the stereo image of master track.
5345 The filter accepts the following options:
5349 Set input level before filtering for both channels. Defaults is 1.
5350 Allowed range is from 0.015625 to 64.
5353 Set output level after filtering for both channels. Defaults is 1.
5354 Allowed range is from 0.015625 to 64.
5357 Set input balance between both channels. Default is 0.
5358 Allowed range is from -1 to 1.
5361 Set output balance between both channels. Default is 0.
5362 Allowed range is from -1 to 1.
5365 Enable softclipping. Results in analog distortion instead of harsh digital 0dB
5366 clipping. Disabled by default.
5369 Mute the left channel. Disabled by default.
5372 Mute the right channel. Disabled by default.
5375 Change the phase of the left channel. Disabled by default.
5378 Change the phase of the right channel. Disabled by default.
5381 Set stereo mode. Available values are:
5385 Left/Right to Left/Right, this is default.
5388 Left/Right to Mid/Side.
5391 Mid/Side to Left/Right.
5394 Left/Right to Left/Left.
5397 Left/Right to Right/Right.
5400 Left/Right to Left + Right.
5403 Left/Right to Right/Left.
5406 Mid/Side to Left/Left.
5409 Mid/Side to Right/Right.
5413 Set level of side signal. Default is 1.
5414 Allowed range is from 0.015625 to 64.
5417 Set balance of side signal. Default is 0.
5418 Allowed range is from -1 to 1.
5421 Set level of the middle signal. Default is 1.
5422 Allowed range is from 0.015625 to 64.
5425 Set middle signal pan. Default is 0. Allowed range is from -1 to 1.
5428 Set stereo base between mono and inversed channels. Default is 0.
5429 Allowed range is from -1 to 1.
5432 Set delay in milliseconds how much to delay left from right channel and
5433 vice versa. Default is 0. Allowed range is from -20 to 20.
5436 Set S/C level. Default is 1. Allowed range is from 1 to 100.
5439 Set the stereo phase in degrees. Default is 0. Allowed range is from 0 to 360.
5441 @item bmode_in, bmode_out
5442 Set balance mode for balance_in/balance_out option.
5444 Can be one of the following:
5448 Classic balance mode. Attenuate one channel at time.
5449 Gain is raised up to 1.
5452 Similar as classic mode above but gain is raised up to 2.
5455 Equal power distribution, from -6dB to +6dB range.
5459 @subsection Examples
5463 Apply karaoke like effect:
5465 stereotools=mlev=0.015625
5469 Convert M/S signal to L/R:
5471 "stereotools=mode=ms>lr"
5475 @section stereowiden
5477 This filter enhance the stereo effect by suppressing signal common to both
5478 channels and by delaying the signal of left into right and vice versa,
5479 thereby widening the stereo effect.
5481 The filter accepts the following options:
5485 Time in milliseconds of the delay of left signal into right and vice versa.
5486 Default is 20 milliseconds.
5489 Amount of gain in delayed signal into right and vice versa. Gives a delay
5490 effect of left signal in right output and vice versa which gives widening
5491 effect. Default is 0.3.
5494 Cross feed of left into right with inverted phase. This helps in suppressing
5495 the mono. If the value is 1 it will cancel all the signal common to both
5496 channels. Default is 0.3.
5499 Set level of input signal of original channel. Default is 0.8.
5502 @subsection Commands
5504 This filter supports the all above options except @code{delay} as @ref{commands}.
5506 @section superequalizer
5507 Apply 18 band equalizer.
5509 The filter accepts the following options:
5516 Set 131Hz band gain.
5518 Set 185Hz band gain.
5520 Set 262Hz band gain.
5522 Set 370Hz band gain.
5524 Set 523Hz band gain.
5526 Set 740Hz band gain.
5528 Set 1047Hz band gain.
5530 Set 1480Hz band gain.
5532 Set 2093Hz band gain.
5534 Set 2960Hz band gain.
5536 Set 4186Hz band gain.
5538 Set 5920Hz band gain.
5540 Set 8372Hz band gain.
5542 Set 11840Hz band gain.
5544 Set 16744Hz band gain.
5546 Set 20000Hz band gain.
5550 Apply audio surround upmix filter.
5552 This filter allows to produce multichannel output from audio stream.
5554 The filter accepts the following options:
5558 Set output channel layout. By default, this is @var{5.1}.
5560 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
5561 for the required syntax.
5564 Set input channel layout. By default, this is @var{stereo}.
5566 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
5567 for the required syntax.
5570 Set input volume level. By default, this is @var{1}.
5573 Set output volume level. By default, this is @var{1}.
5576 Enable LFE channel output if output channel layout has it. By default, this is enabled.
5579 Set LFE low cut off frequency. By default, this is @var{128} Hz.
5582 Set LFE high cut off frequency. By default, this is @var{256} Hz.
5585 Set LFE mode, can be @var{add} or @var{sub}. Default is @var{add}.
5586 In @var{add} mode, LFE channel is created from input audio and added to output.
5587 In @var{sub} mode, LFE channel is created from input audio and added to output but
5588 also all non-LFE output channels are subtracted with output LFE channel.
5591 Set angle of stereo surround transform, Allowed range is from @var{0} to @var{360}.
5592 Default is @var{90}.
5595 Set front center input volume. By default, this is @var{1}.
5598 Set front center output volume. By default, this is @var{1}.
5601 Set front left input volume. By default, this is @var{1}.
5604 Set front left output volume. By default, this is @var{1}.
5607 Set front right input volume. By default, this is @var{1}.
5610 Set front right output volume. By default, this is @var{1}.
5613 Set side left input volume. By default, this is @var{1}.
5616 Set side left output volume. By default, this is @var{1}.
5619 Set side right input volume. By default, this is @var{1}.
5622 Set side right output volume. By default, this is @var{1}.
5625 Set back left input volume. By default, this is @var{1}.
5628 Set back left output volume. By default, this is @var{1}.
5631 Set back right input volume. By default, this is @var{1}.
5634 Set back right output volume. By default, this is @var{1}.
5637 Set back center input volume. By default, this is @var{1}.
5640 Set back center output volume. By default, this is @var{1}.
5643 Set LFE input volume. By default, this is @var{1}.
5646 Set LFE output volume. By default, this is @var{1}.
5649 Set spread usage of stereo image across X axis for all channels.
5652 Set spread usage of stereo image across Y axis for all channels.
5654 @item fcx, flx, frx, blx, brx, slx, srx, bcx
5655 Set spread usage of stereo image across X axis for each channel.
5657 @item fcy, fly, fry, bly, bry, sly, sry, bcy
5658 Set spread usage of stereo image across Y axis for each channel.
5661 Set window size. Allowed range is from @var{1024} to @var{65536}. Default size is @var{4096}.
5664 Set window function.
5666 It accepts the following values:
5689 Default is @code{hann}.
5692 Set window overlap. If set to 1, the recommended overlap for selected
5693 window function will be picked. Default is @code{0.5}.
5696 @section treble, highshelf
5698 Boost or cut treble (upper) frequencies of the audio using a two-pole
5699 shelving filter with a response similar to that of a standard
5700 hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
5702 The filter accepts the following options:
5706 Give the gain at whichever is the lower of ~22 kHz and the
5707 Nyquist frequency. Its useful range is about -20 (for a large cut)
5708 to +20 (for a large boost). Beware of clipping when using a positive gain.
5711 Set the filter's central frequency and so can be used
5712 to extend or reduce the frequency range to be boosted or cut.
5713 The default value is @code{3000} Hz.
5716 Set method to specify band-width of filter.
5731 Determine how steep is the filter's shelf transition.
5734 How much to use filtered signal in output. Default is 1.
5735 Range is between 0 and 1.
5738 Specify which channels to filter, by default all available are filtered.
5741 Normalize biquad coefficients, by default is disabled.
5742 Enabling it will normalize magnitude response at DC to 0dB.
5745 Set transform type of IIR filter.
5754 @subsection Commands
5756 This filter supports the following commands:
5759 Change treble frequency.
5760 Syntax for the command is : "@var{frequency}"
5763 Change treble width_type.
5764 Syntax for the command is : "@var{width_type}"
5767 Change treble width.
5768 Syntax for the command is : "@var{width}"
5772 Syntax for the command is : "@var{gain}"
5776 Syntax for the command is : "@var{mix}"
5781 Sinusoidal amplitude modulation.
5783 The filter accepts the following options:
5787 Modulation frequency in Hertz. Modulation frequencies in the subharmonic range
5788 (20 Hz or lower) will result in a tremolo effect.
5789 This filter may also be used as a ring modulator by specifying
5790 a modulation frequency higher than 20 Hz.
5791 Range is 0.1 - 20000.0. Default value is 5.0 Hz.
5794 Depth of modulation as a percentage. Range is 0.0 - 1.0.
5795 Default value is 0.5.
5800 Sinusoidal phase modulation.
5802 The filter accepts the following options:
5806 Modulation frequency in Hertz.
5807 Range is 0.1 - 20000.0. Default value is 5.0 Hz.
5810 Depth of modulation as a percentage. Range is 0.0 - 1.0.
5811 Default value is 0.5.
5816 Adjust the input audio volume.
5818 It accepts the following parameters:
5822 Set audio volume expression.
5824 Output values are clipped to the maximum value.
5826 The output audio volume is given by the relation:
5828 @var{output_volume} = @var{volume} * @var{input_volume}
5831 The default value for @var{volume} is "1.0".
5834 This parameter represents the mathematical precision.
5836 It determines which input sample formats will be allowed, which affects the
5837 precision of the volume scaling.
5841 8-bit fixed-point; this limits input sample format to U8, S16, and S32.
5843 32-bit floating-point; this limits input sample format to FLT. (default)
5845 64-bit floating-point; this limits input sample format to DBL.
5849 Choose the behaviour on encountering ReplayGain side data in input frames.
5853 Remove ReplayGain side data, ignoring its contents (the default).
5856 Ignore ReplayGain side data, but leave it in the frame.
5859 Prefer the track gain, if present.
5862 Prefer the album gain, if present.
5865 @item replaygain_preamp
5866 Pre-amplification gain in dB to apply to the selected replaygain gain.
5868 Default value for @var{replaygain_preamp} is 0.0.
5870 @item replaygain_noclip
5871 Prevent clipping by limiting the gain applied.
5873 Default value for @var{replaygain_noclip} is 1.
5876 Set when the volume expression is evaluated.
5878 It accepts the following values:
5881 only evaluate expression once during the filter initialization, or
5882 when the @samp{volume} command is sent
5885 evaluate expression for each incoming frame
5888 Default value is @samp{once}.
5891 The volume expression can contain the following parameters.
5895 frame number (starting at zero)
5898 @item nb_consumed_samples
5899 number of samples consumed by the filter
5901 number of samples in the current frame
5903 original frame position in the file
5909 PTS at start of stream
5911 time at start of stream
5917 last set volume value
5920 Note that when @option{eval} is set to @samp{once} only the
5921 @var{sample_rate} and @var{tb} variables are available, all other
5922 variables will evaluate to NAN.
5924 @subsection Commands
5926 This filter supports the following commands:
5929 Modify the volume expression.
5930 The command accepts the same syntax of the corresponding option.
5932 If the specified expression is not valid, it is kept at its current
5936 @subsection Examples
5940 Halve the input audio volume:
5944 volume=volume=-6.0206dB
5947 In all the above example the named key for @option{volume} can be
5948 omitted, for example like in:
5954 Increase input audio power by 6 decibels using fixed-point precision:
5956 volume=volume=6dB:precision=fixed
5960 Fade volume after time 10 with an annihilation period of 5 seconds:
5962 volume='if(lt(t,10),1,max(1-(t-10)/5,0))':eval=frame
5966 @section volumedetect
5968 Detect the volume of the input video.
5970 The filter has no parameters. The input is not modified. Statistics about
5971 the volume will be printed in the log when the input stream end is reached.
5973 In particular it will show the mean volume (root mean square), maximum
5974 volume (on a per-sample basis), and the beginning of a histogram of the
5975 registered volume values (from the maximum value to a cumulated 1/1000 of
5978 All volumes are in decibels relative to the maximum PCM value.
5980 @subsection Examples
5982 Here is an excerpt of the output:
5984 [Parsed_volumedetect_0 @ 0xa23120] mean_volume: -27 dB
5985 [Parsed_volumedetect_0 @ 0xa23120] max_volume: -4 dB
5986 [Parsed_volumedetect_0 @ 0xa23120] histogram_4db: 6
5987 [Parsed_volumedetect_0 @ 0xa23120] histogram_5db: 62
5988 [Parsed_volumedetect_0 @ 0xa23120] histogram_6db: 286
5989 [Parsed_volumedetect_0 @ 0xa23120] histogram_7db: 1042
5990 [Parsed_volumedetect_0 @ 0xa23120] histogram_8db: 2551
5991 [Parsed_volumedetect_0 @ 0xa23120] histogram_9db: 4609
5992 [Parsed_volumedetect_0 @ 0xa23120] histogram_10db: 8409
5998 The mean square energy is approximately -27 dB, or 10^-2.7.
6000 The largest sample is at -4 dB, or more precisely between -4 dB and -5 dB.
6002 There are 6 samples at -4 dB, 62 at -5 dB, 286 at -6 dB, etc.
6005 In other words, raising the volume by +4 dB does not cause any clipping,
6006 raising it by +5 dB causes clipping for 6 samples, etc.
6008 @c man end AUDIO FILTERS
6010 @chapter Audio Sources
6011 @c man begin AUDIO SOURCES
6013 Below is a description of the currently available audio sources.
6017 Buffer audio frames, and make them available to the filter chain.
6019 This source is mainly intended for a programmatic use, in particular
6020 through the interface defined in @file{libavfilter/buffersrc.h}.
6022 It accepts the following parameters:
6026 The timebase which will be used for timestamps of submitted frames. It must be
6027 either a floating-point number or in @var{numerator}/@var{denominator} form.
6030 The sample rate of the incoming audio buffers.
6033 The sample format of the incoming audio buffers.
6034 Either a sample format name or its corresponding integer representation from
6035 the enum AVSampleFormat in @file{libavutil/samplefmt.h}
6037 @item channel_layout
6038 The channel layout of the incoming audio buffers.
6039 Either a channel layout name from channel_layout_map in
6040 @file{libavutil/channel_layout.c} or its corresponding integer representation
6041 from the AV_CH_LAYOUT_* macros in @file{libavutil/channel_layout.h}
6044 The number of channels of the incoming audio buffers.
6045 If both @var{channels} and @var{channel_layout} are specified, then they
6050 @subsection Examples
6053 abuffer=sample_rate=44100:sample_fmt=s16p:channel_layout=stereo
6056 will instruct the source to accept planar 16bit signed stereo at 44100Hz.
6057 Since the sample format with name "s16p" corresponds to the number
6058 6 and the "stereo" channel layout corresponds to the value 0x3, this is
6061 abuffer=sample_rate=44100:sample_fmt=6:channel_layout=0x3
6066 Generate an audio signal specified by an expression.
6068 This source accepts in input one or more expressions (one for each
6069 channel), which are evaluated and used to generate a corresponding
6072 This source accepts the following options:
6076 Set the '|'-separated expressions list for each separate channel. In case the
6077 @option{channel_layout} option is not specified, the selected channel layout
6078 depends on the number of provided expressions. Otherwise the last
6079 specified expression is applied to the remaining output channels.
6081 @item channel_layout, c
6082 Set the channel layout. The number of channels in the specified layout
6083 must be equal to the number of specified expressions.
6086 Set the minimum duration of the sourced audio. See
6087 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
6088 for the accepted syntax.
6089 Note that the resulting duration may be greater than the specified
6090 duration, as the generated audio is always cut at the end of a
6093 If not specified, or the expressed duration is negative, the audio is
6094 supposed to be generated forever.
6097 Set the number of samples per channel per each output frame,
6100 @item sample_rate, s
6101 Specify the sample rate, default to 44100.
6104 Each expression in @var{exprs} can contain the following constants:
6108 number of the evaluated sample, starting from 0
6111 time of the evaluated sample expressed in seconds, starting from 0
6118 @subsection Examples
6128 Generate a sin signal with frequency of 440 Hz, set sample rate to
6131 aevalsrc="sin(440*2*PI*t):s=8000"
6135 Generate a two channels signal, specify the channel layout (Front
6136 Center + Back Center) explicitly:
6138 aevalsrc="sin(420*2*PI*t)|cos(430*2*PI*t):c=FC|BC"
6142 Generate white noise:
6144 aevalsrc="-2+random(0)"
6148 Generate an amplitude modulated signal:
6150 aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)"
6154 Generate 2.5 Hz binaural beats on a 360 Hz carrier:
6156 aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) | 0.1*sin(2*PI*(360+2.5/2)*t)"
6163 Generate a FIR coefficients using frequency sampling method.
6165 The resulting stream can be used with @ref{afir} filter for filtering the audio signal.
6167 The filter accepts the following options:
6171 Set number of filter coefficents in output audio stream.
6172 Default value is 1025.
6175 Set frequency points from where magnitude and phase are set.
6176 This must be in non decreasing order, and first element must be 0, while last element
6177 must be 1. Elements are separated by white spaces.
6180 Set magnitude value for every frequency point set by @option{frequency}.
6181 Number of values must be same as number of frequency points.
6182 Values are separated by white spaces.
6185 Set phase value for every frequency point set by @option{frequency}.
6186 Number of values must be same as number of frequency points.
6187 Values are separated by white spaces.
6189 @item sample_rate, r
6190 Set sample rate, default is 44100.
6193 Set number of samples per each frame. Default is 1024.
6196 Set window function. Default is blackman.
6201 The null audio source, return unprocessed audio frames. It is mainly useful
6202 as a template and to be employed in analysis / debugging tools, or as
6203 the source for filters which ignore the input data (for example the sox
6206 This source accepts the following options:
6210 @item channel_layout, cl
6212 Specifies the channel layout, and can be either an integer or a string
6213 representing a channel layout. The default value of @var{channel_layout}
6216 Check the channel_layout_map definition in
6217 @file{libavutil/channel_layout.c} for the mapping between strings and
6218 channel layout values.
6220 @item sample_rate, r
6221 Specifies the sample rate, and defaults to 44100.
6224 Set the number of samples per requested frames.
6227 Set the duration of the sourced audio. See
6228 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
6229 for the accepted syntax.
6231 If not specified, or the expressed duration is negative, the audio is
6232 supposed to be generated forever.
6235 @subsection Examples
6239 Set the sample rate to 48000 Hz and the channel layout to AV_CH_LAYOUT_MONO.
6241 anullsrc=r=48000:cl=4
6245 Do the same operation with a more obvious syntax:
6247 anullsrc=r=48000:cl=mono
6251 All the parameters need to be explicitly defined.
6255 Synthesize a voice utterance using the libflite library.
6257 To enable compilation of this filter you need to configure FFmpeg with
6258 @code{--enable-libflite}.
6260 Note that versions of the flite library prior to 2.0 are not thread-safe.
6262 The filter accepts the following options:
6267 If set to 1, list the names of the available voices and exit
6268 immediately. Default value is 0.
6271 Set the maximum number of samples per frame. Default value is 512.
6274 Set the filename containing the text to speak.
6277 Set the text to speak.
6280 Set the voice to use for the speech synthesis. Default value is
6281 @code{kal}. See also the @var{list_voices} option.
6284 @subsection Examples
6288 Read from file @file{speech.txt}, and synthesize the text using the
6289 standard flite voice:
6291 flite=textfile=speech.txt
6295 Read the specified text selecting the @code{slt} voice:
6297 flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
6301 Input text to ffmpeg:
6303 ffmpeg -f lavfi -i flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
6307 Make @file{ffplay} speak the specified text, using @code{flite} and
6308 the @code{lavfi} device:
6310 ffplay -f lavfi flite=text='No more be grieved for which that thou hast done.'
6314 For more information about libflite, check:
6315 @url{http://www.festvox.org/flite/}
6319 Generate a noise audio signal.
6321 The filter accepts the following options:
6324 @item sample_rate, r
6325 Specify the sample rate. Default value is 48000 Hz.
6328 Specify the amplitude (0.0 - 1.0) of the generated audio stream. Default value
6332 Specify the duration of the generated audio stream. Not specifying this option
6333 results in noise with an infinite length.
6335 @item color, colour, c
6336 Specify the color of noise. Available noise colors are white, pink, brown,
6337 blue, violet and velvet. Default color is white.
6340 Specify a value used to seed the PRNG.
6343 Set the number of samples per each output frame, default is 1024.
6346 @subsection Examples
6351 Generate 60 seconds of pink noise, with a 44.1 kHz sampling rate and an amplitude of 0.5:
6353 anoisesrc=d=60:c=pink:r=44100:a=0.5
6359 Generate odd-tap Hilbert transform FIR coefficients.
6361 The resulting stream can be used with @ref{afir} filter for phase-shifting
6362 the signal by 90 degrees.
6364 This is used in many matrix coding schemes and for analytic signal generation.
6365 The process is often written as a multiplication by i (or j), the imaginary unit.
6367 The filter accepts the following options:
6371 @item sample_rate, s
6372 Set sample rate, default is 44100.
6375 Set length of FIR filter, default is 22051.
6378 Set number of samples per each frame.
6381 Set window function to be used when generating FIR coefficients.
6386 Generate a sinc kaiser-windowed low-pass, high-pass, band-pass, or band-reject FIR coefficients.
6388 The resulting stream can be used with @ref{afir} filter for filtering the audio signal.
6390 The filter accepts the following options:
6393 @item sample_rate, r
6394 Set sample rate, default is 44100.
6397 Set number of samples per each frame. Default is 1024.
6400 Set high-pass frequency. Default is 0.
6403 Set low-pass frequency. Default is 0.
6404 If high-pass frequency is lower than low-pass frequency and low-pass frequency
6405 is higher than 0 then filter will create band-pass filter coefficients,
6406 otherwise band-reject filter coefficients.
6409 Set filter phase response. Default is 50. Allowed range is from 0 to 100.
6412 Set Kaiser window beta.
6415 Set stop-band attenuation. Default is 120dB, allowed range is from 40 to 180 dB.
6418 Enable rounding, by default is disabled.
6421 Set number of taps for high-pass filter.
6424 Set number of taps for low-pass filter.
6429 Generate an audio signal made of a sine wave with amplitude 1/8.
6431 The audio signal is bit-exact.
6433 The filter accepts the following options:
6438 Set the carrier frequency. Default is 440 Hz.
6440 @item beep_factor, b
6441 Enable a periodic beep every second with frequency @var{beep_factor} times
6442 the carrier frequency. Default is 0, meaning the beep is disabled.
6444 @item sample_rate, r
6445 Specify the sample rate, default is 44100.
6448 Specify the duration of the generated audio stream.
6450 @item samples_per_frame
6451 Set the number of samples per output frame.
6453 The expression can contain the following constants:
6457 The (sequential) number of the output audio frame, starting from 0.
6460 The PTS (Presentation TimeStamp) of the output audio frame,
6461 expressed in @var{TB} units.
6464 The PTS of the output audio frame, expressed in seconds.
6467 The timebase of the output audio frames.
6470 Default is @code{1024}.
6473 @subsection Examples
6478 Generate a simple 440 Hz sine wave:
6484 Generate a 220 Hz sine wave with a 880 Hz beep each second, for 5 seconds:
6488 sine=frequency=220:beep_factor=4:duration=5
6492 Generate a 1 kHz sine wave following @code{1602,1601,1602,1601,1602} NTSC
6495 sine=1000:samples_per_frame='st(0,mod(n,5)); 1602-not(not(eq(ld(0),1)+eq(ld(0),3)))'
6499 @c man end AUDIO SOURCES
6501 @chapter Audio Sinks
6502 @c man begin AUDIO SINKS
6504 Below is a description of the currently available audio sinks.
6506 @section abuffersink
6508 Buffer audio frames, and make them available to the end of filter chain.
6510 This sink is mainly intended for programmatic use, in particular
6511 through the interface defined in @file{libavfilter/buffersink.h}
6512 or the options system.
6514 It accepts a pointer to an AVABufferSinkContext structure, which
6515 defines the incoming buffers' formats, to be passed as the opaque
6516 parameter to @code{avfilter_init_filter} for initialization.
6519 Null audio sink; do absolutely nothing with the input audio. It is
6520 mainly useful as a template and for use in analysis / debugging
6523 @c man end AUDIO SINKS
6525 @chapter Video Filters
6526 @c man begin VIDEO FILTERS
6528 When you configure your FFmpeg build, you can disable any of the
6529 existing filters using @code{--disable-filters}.
6530 The configure output will show the video filters included in your
6533 Below is a description of the currently available video filters.
6537 Mark a region of interest in a video frame.
6539 The frame data is passed through unchanged, but metadata is attached
6540 to the frame indicating regions of interest which can affect the
6541 behaviour of later encoding. Multiple regions can be marked by
6542 applying the filter multiple times.
6546 Region distance in pixels from the left edge of the frame.
6548 Region distance in pixels from the top edge of the frame.
6550 Region width in pixels.
6552 Region height in pixels.
6554 The parameters @var{x}, @var{y}, @var{w} and @var{h} are expressions,
6555 and may contain the following variables:
6558 Width of the input frame.
6560 Height of the input frame.
6564 Quantisation offset to apply within the region.
6566 This must be a real value in the range -1 to +1. A value of zero
6567 indicates no quality change. A negative value asks for better quality
6568 (less quantisation), while a positive value asks for worse quality
6569 (greater quantisation).
6571 The range is calibrated so that the extreme values indicate the
6572 largest possible offset - if the rest of the frame is encoded with the
6573 worst possible quality, an offset of -1 indicates that this region
6574 should be encoded with the best possible quality anyway. Intermediate
6575 values are then interpolated in some codec-dependent way.
6577 For example, in 10-bit H.264 the quantisation parameter varies between
6578 -12 and 51. A typical qoffset value of -1/10 therefore indicates that
6579 this region should be encoded with a QP around one-tenth of the full
6580 range better than the rest of the frame. So, if most of the frame
6581 were to be encoded with a QP of around 30, this region would get a QP
6582 of around 24 (an offset of approximately -1/10 * (51 - -12) = -6.3).
6583 An extreme value of -1 would indicate that this region should be
6584 encoded with the best possible quality regardless of the treatment of
6585 the rest of the frame - that is, should be encoded at a QP of -12.
6587 If set to true, remove any existing regions of interest marked on the
6588 frame before adding the new one.
6591 @subsection Examples
6595 Mark the centre quarter of the frame as interesting.
6597 addroi=iw/4:ih/4:iw/2:ih/2:-1/10
6600 Mark the 100-pixel-wide region on the left edge of the frame as very
6601 uninteresting (to be encoded at much lower quality than the rest of
6604 addroi=0:0:100:ih:+1/5
6608 @section alphaextract
6610 Extract the alpha component from the input as a grayscale video. This
6611 is especially useful with the @var{alphamerge} filter.
6615 Add or replace the alpha component of the primary input with the
6616 grayscale value of a second input. This is intended for use with
6617 @var{alphaextract} to allow the transmission or storage of frame
6618 sequences that have alpha in a format that doesn't support an alpha
6621 For example, to reconstruct full frames from a normal YUV-encoded video
6622 and a separate video created with @var{alphaextract}, you might use:
6624 movie=in_alpha.mkv [alpha]; [in][alpha] alphamerge [out]
6629 Amplify differences between current pixel and pixels of adjacent frames in
6630 same pixel location.
6632 This filter accepts the following options:
6636 Set frame radius. Default is 2. Allowed range is from 1 to 63.
6637 For example radius of 3 will instruct filter to calculate average of 7 frames.
6640 Set factor to amplify difference. Default is 2. Allowed range is from 0 to 65535.
6643 Set threshold for difference amplification. Any difference greater or equal to
6644 this value will not alter source pixel. Default is 10.
6645 Allowed range is from 0 to 65535.
6648 Set tolerance for difference amplification. Any difference lower to
6649 this value will not alter source pixel. Default is 0.
6650 Allowed range is from 0 to 65535.
6653 Set lower limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535.
6654 This option controls maximum possible value that will decrease source pixel value.
6657 Set high limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535.
6658 This option controls maximum possible value that will increase source pixel value.
6661 Set which planes to filter. Default is all. Allowed range is from 0 to 15.
6664 @subsection Commands
6666 This filter supports the following @ref{commands} that corresponds to option of same name:
6678 Same as the @ref{subtitles} filter, except that it doesn't require libavcodec
6679 and libavformat to work. On the other hand, it is limited to ASS (Advanced
6680 Substation Alpha) subtitles files.
6682 This filter accepts the following option in addition to the common options from
6683 the @ref{subtitles} filter:
6687 Set the shaping engine
6689 Available values are:
6692 The default libass shaping engine, which is the best available.
6694 Fast, font-agnostic shaper that can do only substitutions
6696 Slower shaper using OpenType for substitutions and positioning
6699 The default is @code{auto}.
6703 Apply an Adaptive Temporal Averaging Denoiser to the video input.
6705 The filter accepts the following options:
6709 Set threshold A for 1st plane. Default is 0.02.
6710 Valid range is 0 to 0.3.
6713 Set threshold B for 1st plane. Default is 0.04.
6714 Valid range is 0 to 5.
6717 Set threshold A for 2nd plane. Default is 0.02.
6718 Valid range is 0 to 0.3.
6721 Set threshold B for 2nd plane. Default is 0.04.
6722 Valid range is 0 to 5.
6725 Set threshold A for 3rd plane. Default is 0.02.
6726 Valid range is 0 to 0.3.
6729 Set threshold B for 3rd plane. Default is 0.04.
6730 Valid range is 0 to 5.
6732 Threshold A is designed to react on abrupt changes in the input signal and
6733 threshold B is designed to react on continuous changes in the input signal.
6736 Set number of frames filter will use for averaging. Default is 9. Must be odd
6737 number in range [5, 129].
6740 Set what planes of frame filter will use for averaging. Default is all.
6743 Set what variant of algorithm filter will use for averaging. Default is @code{p} parallel.
6744 Alternatively can be set to @code{s} serial.
6746 Parallel can be faster then serial, while other way around is never true.
6747 Parallel will abort early on first change being greater then thresholds, while serial
6748 will continue processing other side of frames if they are equal or bellow thresholds.
6751 @subsection Commands
6752 This filter supports same @ref{commands} as options except option @code{s}.
6753 The command accepts the same syntax of the corresponding option.
6757 Apply average blur filter.
6759 The filter accepts the following options:
6763 Set horizontal radius size.
6766 Set which planes to filter. By default all planes are filtered.
6769 Set vertical radius size, if zero it will be same as @code{sizeX}.
6770 Default is @code{0}.
6773 @subsection Commands
6774 This filter supports same commands as options.
6775 The command accepts the same syntax of the corresponding option.
6777 If the specified expression is not valid, it is kept at its current
6782 Compute the bounding box for the non-black pixels in the input frame
6785 This filter computes the bounding box containing all the pixels with a
6786 luminance value greater than the minimum allowed value.
6787 The parameters describing the bounding box are printed on the filter
6790 The filter accepts the following option:
6794 Set the minimal luminance value. Default is @code{16}.
6798 Apply bilateral filter, spatial smoothing while preserving edges.
6800 The filter accepts the following options:
6803 Set sigma of gaussian function to calculate spatial weight.
6804 Allowed range is 0 to 512. Default is 0.1.
6807 Set sigma of gaussian function to calculate range weight.
6808 Allowed range is 0 to 1. Default is 0.1.
6811 Set planes to filter. Default is first only.
6814 @section bitplanenoise
6816 Show and measure bit plane noise.
6818 The filter accepts the following options:
6822 Set which plane to analyze. Default is @code{1}.
6825 Filter out noisy pixels from @code{bitplane} set above.
6826 Default is disabled.
6829 @section blackdetect
6831 Detect video intervals that are (almost) completely black. Can be
6832 useful to detect chapter transitions, commercials, or invalid
6835 The filter outputs its detection analysis to both the log as well as
6836 frame metadata. If a black segment of at least the specified minimum
6837 duration is found, a line with the start and end timestamps as well
6838 as duration is printed to the log with level @code{info}. In addition,
6839 a log line with level @code{debug} is printed per frame showing the
6840 black amount detected for that frame.
6842 The filter also attaches metadata to the first frame of a black
6843 segment with key @code{lavfi.black_start} and to the first frame
6844 after the black segment ends with key @code{lavfi.black_end}. The
6845 value is the frame's timestamp. This metadata is added regardless
6846 of the minimum duration specified.
6848 The filter accepts the following options:
6851 @item black_min_duration, d
6852 Set the minimum detected black duration expressed in seconds. It must
6853 be a non-negative floating point number.
6855 Default value is 2.0.
6857 @item picture_black_ratio_th, pic_th
6858 Set the threshold for considering a picture "black".
6859 Express the minimum value for the ratio:
6861 @var{nb_black_pixels} / @var{nb_pixels}
6864 for which a picture is considered black.
6865 Default value is 0.98.
6867 @item pixel_black_th, pix_th
6868 Set the threshold for considering a pixel "black".
6870 The threshold expresses the maximum pixel luminance value for which a
6871 pixel is considered "black". The provided value is scaled according to
6872 the following equation:
6874 @var{absolute_threshold} = @var{luminance_minimum_value} + @var{pixel_black_th} * @var{luminance_range_size}
6877 @var{luminance_range_size} and @var{luminance_minimum_value} depend on
6878 the input video format, the range is [0-255] for YUV full-range
6879 formats and [16-235] for YUV non full-range formats.
6881 Default value is 0.10.
6884 The following example sets the maximum pixel threshold to the minimum
6885 value, and detects only black intervals of 2 or more seconds:
6887 blackdetect=d=2:pix_th=0.00
6892 Detect frames that are (almost) completely black. Can be useful to
6893 detect chapter transitions or commercials. Output lines consist of
6894 the frame number of the detected frame, the percentage of blackness,
6895 the position in the file if known or -1 and the timestamp in seconds.
6897 In order to display the output lines, you need to set the loglevel at
6898 least to the AV_LOG_INFO value.
6900 This filter exports frame metadata @code{lavfi.blackframe.pblack}.
6901 The value represents the percentage of pixels in the picture that
6902 are below the threshold value.
6904 It accepts the following parameters:
6909 The percentage of the pixels that have to be below the threshold; it defaults to
6912 @item threshold, thresh
6913 The threshold below which a pixel value is considered black; it defaults to
6921 Blend two video frames into each other.
6923 The @code{blend} filter takes two input streams and outputs one
6924 stream, the first input is the "top" layer and second input is
6925 "bottom" layer. By default, the output terminates when the longest input terminates.
6927 The @code{tblend} (time blend) filter takes two consecutive frames
6928 from one single stream, and outputs the result obtained by blending
6929 the new frame on top of the old frame.
6931 A description of the accepted options follows.
6939 Set blend mode for specific pixel component or all pixel components in case
6940 of @var{all_mode}. Default value is @code{normal}.
6942 Available values for component modes are:
6984 Set blend opacity for specific pixel component or all pixel components in case
6985 of @var{all_opacity}. Only used in combination with pixel component blend modes.
6992 Set blend expression for specific pixel component or all pixel components in case
6993 of @var{all_expr}. Note that related mode options will be ignored if those are set.
6995 The expressions can use the following variables:
6999 The sequential number of the filtered frame, starting from @code{0}.
7003 the coordinates of the current sample
7007 the width and height of currently filtered plane
7011 Width and height scale for the plane being filtered. It is the
7012 ratio between the dimensions of the current plane to the luma plane,
7013 e.g. for a @code{yuv420p} frame, the values are @code{1,1} for
7014 the luma plane and @code{0.5,0.5} for the chroma planes.
7017 Time of the current frame, expressed in seconds.
7020 Value of pixel component at current location for first video frame (top layer).
7023 Value of pixel component at current location for second video frame (bottom layer).
7027 The @code{blend} filter also supports the @ref{framesync} options.
7029 @subsection Examples
7033 Apply transition from bottom layer to top layer in first 10 seconds:
7035 blend=all_expr='A*(if(gte(T,10),1,T/10))+B*(1-(if(gte(T,10),1,T/10)))'
7039 Apply linear horizontal transition from top layer to bottom layer:
7041 blend=all_expr='A*(X/W)+B*(1-X/W)'
7045 Apply 1x1 checkerboard effect:
7047 blend=all_expr='if(eq(mod(X,2),mod(Y,2)),A,B)'
7051 Apply uncover left effect:
7053 blend=all_expr='if(gte(N*SW+X,W),A,B)'
7057 Apply uncover down effect:
7059 blend=all_expr='if(gte(Y-N*SH,0),A,B)'
7063 Apply uncover up-left effect:
7065 blend=all_expr='if(gte(T*SH*40+Y,H)*gte((T*40*SW+X)*W/H,W),A,B)'
7069 Split diagonally video and shows top and bottom layer on each side:
7071 blend=all_expr='if(gt(X,Y*(W/H)),A,B)'
7075 Display differences between the current and the previous frame:
7077 tblend=all_mode=grainextract
7083 Denoise frames using Block-Matching 3D algorithm.
7085 The filter accepts the following options.
7089 Set denoising strength. Default value is 1.
7090 Allowed range is from 0 to 999.9.
7091 The denoising algorithm is very sensitive to sigma, so adjust it
7092 according to the source.
7095 Set local patch size. This sets dimensions in 2D.
7098 Set sliding step for processing blocks. Default value is 4.
7099 Allowed range is from 1 to 64.
7100 Smaller values allows processing more reference blocks and is slower.
7103 Set maximal number of similar blocks for 3rd dimension. Default value is 1.
7104 When set to 1, no block matching is done. Larger values allows more blocks
7106 Allowed range is from 1 to 256.
7109 Set radius for search block matching. Default is 9.
7110 Allowed range is from 1 to INT32_MAX.
7113 Set step between two search locations for block matching. Default is 1.
7114 Allowed range is from 1 to 64. Smaller is slower.
7117 Set threshold of mean square error for block matching. Valid range is 0 to
7121 Set thresholding parameter for hard thresholding in 3D transformed domain.
7122 Larger values results in stronger hard-thresholding filtering in frequency
7126 Set filtering estimation mode. Can be @code{basic} or @code{final}.
7127 Default is @code{basic}.
7130 If enabled, filter will use 2nd stream for block matching.
7131 Default is disabled for @code{basic} value of @var{estim} option,
7132 and always enabled if value of @var{estim} is @code{final}.
7135 Set planes to filter. Default is all available except alpha.
7138 @subsection Examples
7142 Basic filtering with bm3d:
7144 bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic
7148 Same as above, but filtering only luma:
7150 bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic:planes=1
7154 Same as above, but with both estimation modes:
7156 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
7160 Same as above, but prefilter with @ref{nlmeans} filter instead:
7162 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
7168 Apply a boxblur algorithm to the input video.
7170 It accepts the following parameters:
7174 @item luma_radius, lr
7175 @item luma_power, lp
7176 @item chroma_radius, cr
7177 @item chroma_power, cp
7178 @item alpha_radius, ar
7179 @item alpha_power, ap
7183 A description of the accepted options follows.
7186 @item luma_radius, lr
7187 @item chroma_radius, cr
7188 @item alpha_radius, ar
7189 Set an expression for the box radius in pixels used for blurring the
7190 corresponding input plane.
7192 The radius value must be a non-negative number, and must not be
7193 greater than the value of the expression @code{min(w,h)/2} for the
7194 luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma
7197 Default value for @option{luma_radius} is "2". If not specified,
7198 @option{chroma_radius} and @option{alpha_radius} default to the
7199 corresponding value set for @option{luma_radius}.
7201 The expressions can contain the following constants:
7205 The input width and height in pixels.
7209 The input chroma image width and height in pixels.
7213 The horizontal and vertical chroma subsample values. For example, for the
7214 pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1.
7217 @item luma_power, lp
7218 @item chroma_power, cp
7219 @item alpha_power, ap
7220 Specify how many times the boxblur filter is applied to the
7221 corresponding plane.
7223 Default value for @option{luma_power} is 2. If not specified,
7224 @option{chroma_power} and @option{alpha_power} default to the
7225 corresponding value set for @option{luma_power}.
7227 A value of 0 will disable the effect.
7230 @subsection Examples
7234 Apply a boxblur filter with the luma, chroma, and alpha radii
7237 boxblur=luma_radius=2:luma_power=1
7242 Set the luma radius to 2, and alpha and chroma radius to 0:
7244 boxblur=2:1:cr=0:ar=0
7248 Set the luma and chroma radii to a fraction of the video dimension:
7250 boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1
7256 Deinterlace the input video ("bwdif" stands for "Bob Weaver
7257 Deinterlacing Filter").
7259 Motion adaptive deinterlacing based on yadif with the use of w3fdif and cubic
7260 interpolation algorithms.
7261 It accepts the following parameters:
7265 The interlacing mode to adopt. It accepts one of the following values:
7269 Output one frame for each frame.
7271 Output one frame for each field.
7274 The default value is @code{send_field}.
7277 The picture field parity assumed for the input interlaced video. It accepts one
7278 of the following values:
7282 Assume the top field is first.
7284 Assume the bottom field is first.
7286 Enable automatic detection of field parity.
7289 The default value is @code{auto}.
7290 If the interlacing is unknown or the decoder does not export this information,
7291 top field first will be assumed.
7294 Specify which frames to deinterlace. Accepts one of the following
7299 Deinterlace all frames.
7301 Only deinterlace frames marked as interlaced.
7304 The default value is @code{all}.
7309 Apply Contrast Adaptive Sharpen filter to video stream.
7311 The filter accepts the following options:
7315 Set the sharpening strength. Default value is 0.
7318 Set planes to filter. Default value is to filter all
7319 planes except alpha plane.
7323 Remove all color information for all colors except for certain one.
7325 The filter accepts the following options:
7329 The color which will not be replaced with neutral chroma.
7332 Similarity percentage with the above color.
7333 0.01 matches only the exact key color, while 1.0 matches everything.
7337 0.0 makes pixels either fully gray, or not gray at all.
7338 Higher values result in more preserved color.
7341 Signals that the color passed is already in YUV instead of RGB.
7343 Literal colors like "green" or "red" don't make sense with this enabled anymore.
7344 This can be used to pass exact YUV values as hexadecimal numbers.
7347 @subsection Commands
7348 This filter supports same @ref{commands} as options.
7349 The command accepts the same syntax of the corresponding option.
7351 If the specified expression is not valid, it is kept at its current
7355 YUV colorspace color/chroma keying.
7357 The filter accepts the following options:
7361 The color which will be replaced with transparency.
7364 Similarity percentage with the key color.
7366 0.01 matches only the exact key color, while 1.0 matches everything.
7371 0.0 makes pixels either fully transparent, or not transparent at all.
7373 Higher values result in semi-transparent pixels, with a higher transparency
7374 the more similar the pixels color is to the key color.
7377 Signals that the color passed is already in YUV instead of RGB.
7379 Literal colors like "green" or "red" don't make sense with this enabled anymore.
7380 This can be used to pass exact YUV values as hexadecimal numbers.
7383 @subsection Commands
7384 This filter supports same @ref{commands} as options.
7385 The command accepts the same syntax of the corresponding option.
7387 If the specified expression is not valid, it is kept at its current
7390 @subsection Examples
7394 Make every green pixel in the input image transparent:
7396 ffmpeg -i input.png -vf chromakey=green out.png
7400 Overlay a greenscreen-video on top of a static black background.
7402 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
7407 Reduce chrominance noise.
7409 The filter accepts the following options:
7413 Set threshold for averaging chrominance values.
7414 Sum of absolute difference of U and V pixel components or current
7415 pixel and neighbour pixels lower than this threshold will be used in
7416 averaging. Luma component is left unchanged and is copied to output.
7417 Default value is 30. Allowed range is from 1 to 200.
7420 Set horizontal radius of rectangle used for averaging.
7421 Allowed range is from 1 to 100. Default value is 5.
7424 Set vertical radius of rectangle used for averaging.
7425 Allowed range is from 1 to 100. Default value is 5.
7428 Set horizontal step when averaging. Default value is 1.
7429 Allowed range is from 1 to 50.
7430 Mostly useful to speed-up filtering.
7433 Set vertical step when averaging. Default value is 1.
7434 Allowed range is from 1 to 50.
7435 Mostly useful to speed-up filtering.
7438 @subsection Commands
7439 This filter supports same @ref{commands} as options.
7440 The command accepts the same syntax of the corresponding option.
7442 @section chromashift
7443 Shift chroma pixels horizontally and/or vertically.
7445 The filter accepts the following options:
7448 Set amount to shift chroma-blue horizontally.
7450 Set amount to shift chroma-blue vertically.
7452 Set amount to shift chroma-red horizontally.
7454 Set amount to shift chroma-red vertically.
7456 Set edge mode, can be @var{smear}, default, or @var{warp}.
7459 @subsection Commands
7461 This filter supports the all above options as @ref{commands}.
7465 Display CIE color diagram with pixels overlaid onto it.
7467 The filter accepts the following options:
7482 @item uhdtv, rec2020
7496 Set what gamuts to draw.
7498 See @code{system} option for available values.
7501 Set ciescope size, by default set to 512.
7504 Set intensity used to map input pixel values to CIE diagram.
7507 Set contrast used to draw tongue colors that are out of active color system gamut.
7510 Correct gamma displayed on scope, by default enabled.
7513 Show white point on CIE diagram, by default disabled.
7516 Set input gamma. Used only with XYZ input color space.
7521 Visualize information exported by some codecs.
7523 Some codecs can export information through frames using side-data or other
7524 means. For example, some MPEG based codecs export motion vectors through the
7525 @var{export_mvs} flag in the codec @option{flags2} option.
7527 The filter accepts the following option:
7531 Set motion vectors to visualize.
7533 Available flags for @var{mv} are:
7537 forward predicted MVs of P-frames
7539 forward predicted MVs of B-frames
7541 backward predicted MVs of B-frames
7545 Display quantization parameters using the chroma planes.
7548 Set motion vectors type to visualize. Includes MVs from all frames unless specified by @var{frame_type} option.
7550 Available flags for @var{mv_type} are:
7554 forward predicted MVs
7556 backward predicted MVs
7559 @item frame_type, ft
7560 Set frame type to visualize motion vectors of.
7562 Available flags for @var{frame_type} are:
7566 intra-coded frames (I-frames)
7568 predicted frames (P-frames)
7570 bi-directionally predicted frames (B-frames)
7574 @subsection Examples
7578 Visualize forward predicted MVs of all frames using @command{ffplay}:
7580 ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv_type=fp
7584 Visualize multi-directionals MVs of P and B-Frames using @command{ffplay}:
7586 ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv=pf+bf+bb
7590 @section colorbalance
7591 Modify intensity of primary colors (red, green and blue) of input frames.
7593 The filter allows an input frame to be adjusted in the shadows, midtones or highlights
7594 regions for the red-cyan, green-magenta or blue-yellow balance.
7596 A positive adjustment value shifts the balance towards the primary color, a negative
7597 value towards the complementary color.
7599 The filter accepts the following options:
7605 Adjust red, green and blue shadows (darkest pixels).
7610 Adjust red, green and blue midtones (medium pixels).
7615 Adjust red, green and blue highlights (brightest pixels).
7617 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
7620 Preserve lightness when changing color balance. Default is disabled.
7623 @subsection Examples
7627 Add red color cast to shadows:
7633 @subsection Commands
7635 This filter supports the all above options as @ref{commands}.
7637 @section colorchannelmixer
7639 Adjust video input frames by re-mixing color channels.
7641 This filter modifies a color channel by adding the values associated to
7642 the other channels of the same pixels. For example if the value to
7643 modify is red, the output value will be:
7645 @var{red}=@var{red}*@var{rr} + @var{blue}*@var{rb} + @var{green}*@var{rg} + @var{alpha}*@var{ra}
7648 The filter accepts the following options:
7655 Adjust contribution of input red, green, blue and alpha channels for output red channel.
7656 Default is @code{1} for @var{rr}, and @code{0} for @var{rg}, @var{rb} and @var{ra}.
7662 Adjust contribution of input red, green, blue and alpha channels for output green channel.
7663 Default is @code{1} for @var{gg}, and @code{0} for @var{gr}, @var{gb} and @var{ga}.
7669 Adjust contribution of input red, green, blue and alpha channels for output blue channel.
7670 Default is @code{1} for @var{bb}, and @code{0} for @var{br}, @var{bg} and @var{ba}.
7676 Adjust contribution of input red, green, blue and alpha channels for output alpha channel.
7677 Default is @code{1} for @var{aa}, and @code{0} for @var{ar}, @var{ag} and @var{ab}.
7679 Allowed ranges for options are @code{[-2.0, 2.0]}.
7682 @subsection Examples
7686 Convert source to grayscale:
7688 colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3
7691 Simulate sepia tones:
7693 colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131
7697 @subsection Commands
7699 This filter supports the all above options as @ref{commands}.
7702 RGB colorspace color keying.
7704 The filter accepts the following options:
7708 The color which will be replaced with transparency.
7711 Similarity percentage with the key color.
7713 0.01 matches only the exact key color, while 1.0 matches everything.
7718 0.0 makes pixels either fully transparent, or not transparent at all.
7720 Higher values result in semi-transparent pixels, with a higher transparency
7721 the more similar the pixels color is to the key color.
7724 @subsection Examples
7728 Make every green pixel in the input image transparent:
7730 ffmpeg -i input.png -vf colorkey=green out.png
7734 Overlay a greenscreen-video on top of a static background image.
7736 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
7740 @subsection Commands
7741 This filter supports same @ref{commands} as options.
7742 The command accepts the same syntax of the corresponding option.
7744 If the specified expression is not valid, it is kept at its current
7748 Remove all color information for all RGB colors except for certain one.
7750 The filter accepts the following options:
7754 The color which will not be replaced with neutral gray.
7757 Similarity percentage with the above color.
7758 0.01 matches only the exact key color, while 1.0 matches everything.
7761 Blend percentage. 0.0 makes pixels fully gray.
7762 Higher values result in more preserved color.
7765 @subsection Commands
7766 This filter supports same @ref{commands} as options.
7767 The command accepts the same syntax of the corresponding option.
7769 If the specified expression is not valid, it is kept at its current
7772 @section colorlevels
7774 Adjust video input frames using levels.
7776 The filter accepts the following options:
7783 Adjust red, green, blue and alpha input black point.
7784 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
7790 Adjust red, green, blue and alpha input white point.
7791 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{1}.
7793 Input levels are used to lighten highlights (bright tones), darken shadows
7794 (dark tones), change the balance of bright and dark tones.
7800 Adjust red, green, blue and alpha output black point.
7801 Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{0}.
7807 Adjust red, green, blue and alpha output white point.
7808 Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{1}.
7810 Output levels allows manual selection of a constrained output level range.
7813 @subsection Examples
7817 Make video output darker:
7819 colorlevels=rimin=0.058:gimin=0.058:bimin=0.058
7825 colorlevels=rimin=0.039:gimin=0.039:bimin=0.039:rimax=0.96:gimax=0.96:bimax=0.96
7829 Make video output lighter:
7831 colorlevels=rimax=0.902:gimax=0.902:bimax=0.902
7835 Increase brightness:
7837 colorlevels=romin=0.5:gomin=0.5:bomin=0.5
7841 @subsection Commands
7843 This filter supports the all above options as @ref{commands}.
7845 @section colormatrix
7847 Convert color matrix.
7849 The filter accepts the following options:
7854 Specify the source and destination color matrix. Both values must be
7857 The accepted values are:
7885 For example to convert from BT.601 to SMPTE-240M, use the command:
7887 colormatrix=bt601:smpte240m
7892 Convert colorspace, transfer characteristics or color primaries.
7893 Input video needs to have an even size.
7895 The filter accepts the following options:
7900 Specify all color properties at once.
7902 The accepted values are:
7932 Specify output colorspace.
7934 The accepted values are:
7943 BT.470BG or BT.601-6 625
7946 SMPTE-170M or BT.601-6 525
7955 BT.2020 with non-constant luminance
7961 Specify output transfer characteristics.
7963 The accepted values are:
7975 Constant gamma of 2.2
7978 Constant gamma of 2.8
7981 SMPTE-170M, BT.601-6 625 or BT.601-6 525
7999 BT.2020 for 10-bits content
8002 BT.2020 for 12-bits content
8008 Specify output color primaries.
8010 The accepted values are:
8019 BT.470BG or BT.601-6 625
8022 SMPTE-170M or BT.601-6 525
8046 Specify output color range.
8048 The accepted values are:
8051 TV (restricted) range
8054 MPEG (restricted) range
8065 Specify output color format.
8067 The accepted values are:
8070 YUV 4:2:0 planar 8-bits
8073 YUV 4:2:0 planar 10-bits
8076 YUV 4:2:0 planar 12-bits
8079 YUV 4:2:2 planar 8-bits
8082 YUV 4:2:2 planar 10-bits
8085 YUV 4:2:2 planar 12-bits
8088 YUV 4:4:4 planar 8-bits
8091 YUV 4:4:4 planar 10-bits
8094 YUV 4:4:4 planar 12-bits
8099 Do a fast conversion, which skips gamma/primary correction. This will take
8100 significantly less CPU, but will be mathematically incorrect. To get output
8101 compatible with that produced by the colormatrix filter, use fast=1.
8104 Specify dithering mode.
8106 The accepted values are:
8112 Floyd-Steinberg dithering
8116 Whitepoint adaptation mode.
8118 The accepted values are:
8121 Bradford whitepoint adaptation
8124 von Kries whitepoint adaptation
8127 identity whitepoint adaptation (i.e. no whitepoint adaptation)
8131 Override all input properties at once. Same accepted values as @ref{all}.
8134 Override input colorspace. Same accepted values as @ref{space}.
8137 Override input color primaries. Same accepted values as @ref{primaries}.
8140 Override input transfer characteristics. Same accepted values as @ref{trc}.
8143 Override input color range. Same accepted values as @ref{range}.
8147 The filter converts the transfer characteristics, color space and color
8148 primaries to the specified user values. The output value, if not specified,
8149 is set to a default value based on the "all" property. If that property is
8150 also not specified, the filter will log an error. The output color range and
8151 format default to the same value as the input color range and format. The
8152 input transfer characteristics, color space, color primaries and color range
8153 should be set on the input data. If any of these are missing, the filter will
8154 log an error and no conversion will take place.
8156 For example to convert the input to SMPTE-240M, use the command:
8158 colorspace=smpte240m
8161 @section convolution
8163 Apply convolution of 3x3, 5x5, 7x7 or horizontal/vertical up to 49 elements.
8165 The filter accepts the following options:
8172 Set matrix for each plane.
8173 Matrix is sequence of 9, 25 or 49 signed integers in @var{square} mode,
8174 and from 1 to 49 odd number of signed integers in @var{row} mode.
8180 Set multiplier for calculated value for each plane.
8181 If unset or 0, it will be sum of all matrix elements.
8187 Set bias for each plane. This value is added to the result of the multiplication.
8188 Useful for making the overall image brighter or darker. Default is 0.0.
8194 Set matrix mode for each plane. Can be @var{square}, @var{row} or @var{column}.
8195 Default is @var{square}.
8198 @subsection Examples
8204 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"
8210 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"
8216 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"
8222 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"
8226 Apply laplacian edge detector which includes diagonals:
8228 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"
8234 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"
8240 Apply 2D convolution of video stream in frequency domain using second stream
8243 The filter accepts the following options:
8247 Set which planes to process.
8250 Set which impulse video frames will be processed, can be @var{first}
8251 or @var{all}. Default is @var{all}.
8254 The @code{convolve} filter also supports the @ref{framesync} options.
8258 Copy the input video source unchanged to the output. This is mainly useful for
8263 Video filtering on GPU using Apple's CoreImage API on OSX.
8265 Hardware acceleration is based on an OpenGL context. Usually, this means it is
8266 processed by video hardware. However, software-based OpenGL implementations
8267 exist which means there is no guarantee for hardware processing. It depends on
8270 There are many filters and image generators provided by Apple that come with a
8271 large variety of options. The filter has to be referenced by its name along
8274 The coreimage filter accepts the following options:
8277 List all available filters and generators along with all their respective
8278 options as well as possible minimum and maximum values along with the default
8285 Specify all filters by their respective name and options.
8286 Use @var{list_filters} to determine all valid filter names and options.
8287 Numerical options are specified by a float value and are automatically clamped
8288 to their respective value range. Vector and color options have to be specified
8289 by a list of space separated float values. Character escaping has to be done.
8290 A special option name @code{default} is available to use default options for a
8293 It is required to specify either @code{default} or at least one of the filter options.
8294 All omitted options are used with their default values.
8295 The syntax of the filter string is as follows:
8297 filter=<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...][#<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...]][#...]
8301 Specify a rectangle where the output of the filter chain is copied into the
8302 input image. It is given by a list of space separated float values:
8304 output_rect=x\ y\ width\ height
8306 If not given, the output rectangle equals the dimensions of the input image.
8307 The output rectangle is automatically cropped at the borders of the input
8308 image. Negative values are valid for each component.
8310 output_rect=25\ 25\ 100\ 100
8314 Several filters can be chained for successive processing without GPU-HOST
8315 transfers allowing for fast processing of complex filter chains.
8316 Currently, only filters with zero (generators) or exactly one (filters) input
8317 image and one output image are supported. Also, transition filters are not yet
8320 Some filters generate output images with additional padding depending on the
8321 respective filter kernel. The padding is automatically removed to ensure the
8322 filter output has the same size as the input image.
8324 For image generators, the size of the output image is determined by the
8325 previous output image of the filter chain or the input image of the whole
8326 filterchain, respectively. The generators do not use the pixel information of
8327 this image to generate their output. However, the generated output is
8328 blended onto this image, resulting in partial or complete coverage of the
8331 The @ref{coreimagesrc} video source can be used for generating input images
8332 which are directly fed into the filter chain. By using it, providing input
8333 images by another video source or an input video is not required.
8335 @subsection Examples
8340 List all filters available:
8342 coreimage=list_filters=true
8346 Use the CIBoxBlur filter with default options to blur an image:
8348 coreimage=filter=CIBoxBlur@@default
8352 Use a filter chain with CISepiaTone at default values and CIVignetteEffect with
8353 its center at 100x100 and a radius of 50 pixels:
8355 coreimage=filter=CIBoxBlur@@default#CIVignetteEffect@@inputCenter=100\ 100@@inputRadius=50
8359 Use nullsrc and CIQRCodeGenerator to create a QR code for the FFmpeg homepage,
8360 given as complete and escaped command-line for Apple's standard bash shell:
8362 ffmpeg -f lavfi -i nullsrc=s=100x100,coreimage=filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png
8368 Cover a rectangular object
8370 It accepts the following options:
8374 Filepath of the optional cover image, needs to be in yuv420.
8379 It accepts the following values:
8382 cover it by the supplied image
8384 cover it by interpolating the surrounding pixels
8387 Default value is @var{blur}.
8390 @subsection Examples
8394 Cover a rectangular object by the supplied image of a given video using @command{ffmpeg}:
8396 ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
8402 Crop the input video to given dimensions.
8404 It accepts the following parameters:
8408 The width of the output video. It defaults to @code{iw}.
8409 This expression is evaluated only once during the filter
8410 configuration, or when the @samp{w} or @samp{out_w} command is sent.
8413 The height of the output video. It defaults to @code{ih}.
8414 This expression is evaluated only once during the filter
8415 configuration, or when the @samp{h} or @samp{out_h} command is sent.
8418 The horizontal position, in the input video, of the left edge of the output
8419 video. It defaults to @code{(in_w-out_w)/2}.
8420 This expression is evaluated per-frame.
8423 The vertical position, in the input video, of the top edge of the output video.
8424 It defaults to @code{(in_h-out_h)/2}.
8425 This expression is evaluated per-frame.
8428 If set to 1 will force the output display aspect ratio
8429 to be the same of the input, by changing the output sample aspect
8430 ratio. It defaults to 0.
8433 Enable exact cropping. If enabled, subsampled videos will be cropped at exact
8434 width/height/x/y as specified and will not be rounded to nearest smaller value.
8438 The @var{out_w}, @var{out_h}, @var{x}, @var{y} parameters are
8439 expressions containing the following constants:
8444 The computed values for @var{x} and @var{y}. They are evaluated for
8449 The input width and height.
8453 These are the same as @var{in_w} and @var{in_h}.
8457 The output (cropped) width and height.
8461 These are the same as @var{out_w} and @var{out_h}.
8464 same as @var{iw} / @var{ih}
8467 input sample aspect ratio
8470 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
8474 horizontal and vertical chroma subsample values. For example for the
8475 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
8478 The number of the input frame, starting from 0.
8481 the position in the file of the input frame, NAN if unknown
8484 The timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
8488 The expression for @var{out_w} may depend on the value of @var{out_h},
8489 and the expression for @var{out_h} may depend on @var{out_w}, but they
8490 cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are
8491 evaluated after @var{out_w} and @var{out_h}.
8493 The @var{x} and @var{y} parameters specify the expressions for the
8494 position of the top-left corner of the output (non-cropped) area. They
8495 are evaluated for each frame. If the evaluated value is not valid, it
8496 is approximated to the nearest valid value.
8498 The expression for @var{x} may depend on @var{y}, and the expression
8499 for @var{y} may depend on @var{x}.
8501 @subsection Examples
8505 Crop area with size 100x100 at position (12,34).
8510 Using named options, the example above becomes:
8512 crop=w=100:h=100:x=12:y=34
8516 Crop the central input area with size 100x100:
8522 Crop the central input area with size 2/3 of the input video:
8524 crop=2/3*in_w:2/3*in_h
8528 Crop the input video central square:
8535 Delimit the rectangle with the top-left corner placed at position
8536 100:100 and the right-bottom corner corresponding to the right-bottom
8537 corner of the input image.
8539 crop=in_w-100:in_h-100:100:100
8543 Crop 10 pixels from the left and right borders, and 20 pixels from
8544 the top and bottom borders
8546 crop=in_w-2*10:in_h-2*20
8550 Keep only the bottom right quarter of the input image:
8552 crop=in_w/2:in_h/2:in_w/2:in_h/2
8556 Crop height for getting Greek harmony:
8558 crop=in_w:1/PHI*in_w
8562 Apply trembling effect:
8564 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)
8568 Apply erratic camera effect depending on timestamp:
8570 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)"
8574 Set x depending on the value of y:
8576 crop=in_w/2:in_h/2:y:10+10*sin(n/10)
8580 @subsection Commands
8582 This filter supports the following commands:
8588 Set width/height of the output video and the horizontal/vertical position
8590 The command accepts the same syntax of the corresponding option.
8592 If the specified expression is not valid, it is kept at its current
8598 Auto-detect the crop size.
8600 It calculates the necessary cropping parameters and prints the
8601 recommended parameters via the logging system. The detected dimensions
8602 correspond to the non-black area of the input video.
8604 It accepts the following parameters:
8609 Set higher black value threshold, which can be optionally specified
8610 from nothing (0) to everything (255 for 8-bit based formats). An intensity
8611 value greater to the set value is considered non-black. It defaults to 24.
8612 You can also specify a value between 0.0 and 1.0 which will be scaled depending
8613 on the bitdepth of the pixel format.
8616 The value which the width/height should be divisible by. It defaults to
8617 16. The offset is automatically adjusted to center the video. Use 2 to
8618 get only even dimensions (needed for 4:2:2 video). 16 is best when
8619 encoding to most video codecs.
8621 @item reset_count, reset
8622 Set the counter that determines after how many frames cropdetect will
8623 reset the previously detected largest video area and start over to
8624 detect the current optimal crop area. Default value is 0.
8626 This can be useful when channel logos distort the video area. 0
8627 indicates 'never reset', and returns the largest area encountered during
8634 Delay video filtering until a given wallclock timestamp. The filter first
8635 passes on @option{preroll} amount of frames, then it buffers at most
8636 @option{buffer} amount of frames and waits for the cue. After reaching the cue
8637 it forwards the buffered frames and also any subsequent frames coming in its
8640 The filter can be used synchronize the output of multiple ffmpeg processes for
8641 realtime output devices like decklink. By putting the delay in the filtering
8642 chain and pre-buffering frames the process can pass on data to output almost
8643 immediately after the target wallclock timestamp is reached.
8645 Perfect frame accuracy cannot be guaranteed, but the result is good enough for
8651 The cue timestamp expressed in a UNIX timestamp in microseconds. Default is 0.
8654 The duration of content to pass on as preroll expressed in seconds. Default is 0.
8657 The maximum duration of content to buffer before waiting for the cue expressed
8658 in seconds. Default is 0.
8665 Apply color adjustments using curves.
8667 This filter is similar to the Adobe Photoshop and GIMP curves tools. Each
8668 component (red, green and blue) has its values defined by @var{N} key points
8669 tied from each other using a smooth curve. The x-axis represents the pixel
8670 values from the input frame, and the y-axis the new pixel values to be set for
8673 By default, a component curve is defined by the two points @var{(0;0)} and
8674 @var{(1;1)}. This creates a straight line where each original pixel value is
8675 "adjusted" to its own value, which means no change to the image.
8677 The filter allows you to redefine these two points and add some more. A new
8678 curve (using a natural cubic spline interpolation) will be define to pass
8679 smoothly through all these new coordinates. The new defined points needs to be
8680 strictly increasing over the x-axis, and their @var{x} and @var{y} values must
8681 be in the @var{[0;1]} interval. If the computed curves happened to go outside
8682 the vector spaces, the values will be clipped accordingly.
8684 The filter accepts the following options:
8688 Select one of the available color presets. This option can be used in addition
8689 to the @option{r}, @option{g}, @option{b} parameters; in this case, the later
8690 options takes priority on the preset values.
8691 Available presets are:
8694 @item color_negative
8697 @item increase_contrast
8699 @item linear_contrast
8700 @item medium_contrast
8702 @item strong_contrast
8705 Default is @code{none}.
8707 Set the master key points. These points will define a second pass mapping. It
8708 is sometimes called a "luminance" or "value" mapping. It can be used with
8709 @option{r}, @option{g}, @option{b} or @option{all} since it acts like a
8710 post-processing LUT.
8712 Set the key points for the red component.
8714 Set the key points for the green component.
8716 Set the key points for the blue component.
8718 Set the key points for all components (not including master).
8719 Can be used in addition to the other key points component
8720 options. In this case, the unset component(s) will fallback on this
8721 @option{all} setting.
8723 Specify a Photoshop curves file (@code{.acv}) to import the settings from.
8725 Save Gnuplot script of the curves in specified file.
8728 To avoid some filtergraph syntax conflicts, each key points list need to be
8729 defined using the following syntax: @code{x0/y0 x1/y1 x2/y2 ...}.
8731 @subsection Examples
8735 Increase slightly the middle level of blue:
8737 curves=blue='0/0 0.5/0.58 1/1'
8743 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'
8745 Here we obtain the following coordinates for each components:
8748 @code{(0;0.11) (0.42;0.51) (1;0.95)}
8750 @code{(0;0) (0.50;0.48) (1;1)}
8752 @code{(0;0.22) (0.49;0.44) (1;0.80)}
8756 The previous example can also be achieved with the associated built-in preset:
8758 curves=preset=vintage
8768 Use a Photoshop preset and redefine the points of the green component:
8770 curves=psfile='MyCurvesPresets/purple.acv':green='0/0 0.45/0.53 1/1'
8774 Check out the curves of the @code{cross_process} profile using @command{ffmpeg}
8775 and @command{gnuplot}:
8777 ffmpeg -f lavfi -i color -vf curves=cross_process:plot=/tmp/curves.plt -frames:v 1 -f null -
8778 gnuplot -p /tmp/curves.plt
8784 Video data analysis filter.
8786 This filter shows hexadecimal pixel values of part of video.
8788 The filter accepts the following options:
8792 Set output video size.
8795 Set x offset from where to pick pixels.
8798 Set y offset from where to pick pixels.
8801 Set scope mode, can be one of the following:
8804 Draw hexadecimal pixel values with white color on black background.
8807 Draw hexadecimal pixel values with input video pixel color on black
8811 Draw hexadecimal pixel values on color background picked from input video,
8812 the text color is picked in such way so its always visible.
8816 Draw rows and columns numbers on left and top of video.
8819 Set background opacity.
8822 Set display number format. Can be @code{hex}, or @code{dec}. Default is @code{hex}.
8826 Apply Directional blur filter.
8828 The filter accepts the following options:
8832 Set angle of directional blur. Default is @code{45}.
8835 Set radius of directional blur. Default is @code{5}.
8838 Set which planes to filter. By default all planes are filtered.
8841 @subsection Commands
8842 This filter supports same @ref{commands} as options.
8843 The command accepts the same syntax of the corresponding option.
8845 If the specified expression is not valid, it is kept at its current
8850 Denoise frames using 2D DCT (frequency domain filtering).
8852 This filter is not designed for real time.
8854 The filter accepts the following options:
8858 Set the noise sigma constant.
8860 This @var{sigma} defines a hard threshold of @code{3 * sigma}; every DCT
8861 coefficient (absolute value) below this threshold with be dropped.
8863 If you need a more advanced filtering, see @option{expr}.
8865 Default is @code{0}.
8868 Set number overlapping pixels for each block. Since the filter can be slow, you
8869 may want to reduce this value, at the cost of a less effective filter and the
8870 risk of various artefacts.
8872 If the overlapping value doesn't permit processing the whole input width or
8873 height, a warning will be displayed and according borders won't be denoised.
8875 Default value is @var{blocksize}-1, which is the best possible setting.
8878 Set the coefficient factor expression.
8880 For each coefficient of a DCT block, this expression will be evaluated as a
8881 multiplier value for the coefficient.
8883 If this is option is set, the @option{sigma} option will be ignored.
8885 The absolute value of the coefficient can be accessed through the @var{c}
8889 Set the @var{blocksize} using the number of bits. @code{1<<@var{n}} defines the
8890 @var{blocksize}, which is the width and height of the processed blocks.
8892 The default value is @var{3} (8x8) and can be raised to @var{4} for a
8893 @var{blocksize} of 16x16. Note that changing this setting has huge consequences
8894 on the speed processing. Also, a larger block size does not necessarily means a
8898 @subsection Examples
8900 Apply a denoise with a @option{sigma} of @code{4.5}:
8905 The same operation can be achieved using the expression system:
8907 dctdnoiz=e='gte(c, 4.5*3)'
8910 Violent denoise using a block size of @code{16x16}:
8917 Remove banding artifacts from input video.
8918 It works by replacing banded pixels with average value of referenced pixels.
8920 The filter accepts the following options:
8927 Set banding detection threshold for each plane. Default is 0.02.
8928 Valid range is 0.00003 to 0.5.
8929 If difference between current pixel and reference pixel is less than threshold,
8930 it will be considered as banded.
8933 Banding detection range in pixels. Default is 16. If positive, random number
8934 in range 0 to set value will be used. If negative, exact absolute value
8936 The range defines square of four pixels around current pixel.
8939 Set direction in radians from which four pixel will be compared. If positive,
8940 random direction from 0 to set direction will be picked. If negative, exact of
8941 absolute value will be picked. For example direction 0, -PI or -2*PI radians
8942 will pick only pixels on same row and -PI/2 will pick only pixels on same
8946 If enabled, current pixel is compared with average value of all four
8947 surrounding pixels. The default is enabled. If disabled current pixel is
8948 compared with all four surrounding pixels. The pixel is considered banded
8949 if only all four differences with surrounding pixels are less than threshold.
8952 If enabled, current pixel is changed if and only if all pixel components are banded,
8953 e.g. banding detection threshold is triggered for all color components.
8954 The default is disabled.
8959 Remove blocking artifacts from input video.
8961 The filter accepts the following options:
8965 Set filter type, can be @var{weak} or @var{strong}. Default is @var{strong}.
8966 This controls what kind of deblocking is applied.
8969 Set size of block, allowed range is from 4 to 512. Default is @var{8}.
8975 Set blocking detection thresholds. Allowed range is 0 to 1.
8976 Defaults are: @var{0.098} for @var{alpha} and @var{0.05} for the rest.
8977 Using higher threshold gives more deblocking strength.
8978 Setting @var{alpha} controls threshold detection at exact edge of block.
8979 Remaining options controls threshold detection near the edge. Each one for
8980 below/above or left/right. Setting any of those to @var{0} disables
8984 Set planes to filter. Default is to filter all available planes.
8987 @subsection Examples
8991 Deblock using weak filter and block size of 4 pixels.
8993 deblock=filter=weak:block=4
8997 Deblock using strong filter, block size of 4 pixels and custom thresholds for
8998 deblocking more edges.
9000 deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05
9004 Similar as above, but filter only first plane.
9006 deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=1
9010 Similar as above, but filter only second and third plane.
9012 deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=6
9019 Drop duplicated frames at regular intervals.
9021 The filter accepts the following options:
9025 Set the number of frames from which one will be dropped. Setting this to
9026 @var{N} means one frame in every batch of @var{N} frames will be dropped.
9027 Default is @code{5}.
9030 Set the threshold for duplicate detection. If the difference metric for a frame
9031 is less than or equal to this value, then it is declared as duplicate. Default
9035 Set scene change threshold. Default is @code{15}.
9039 Set the size of the x and y-axis blocks used during metric calculations.
9040 Larger blocks give better noise suppression, but also give worse detection of
9041 small movements. Must be a power of two. Default is @code{32}.
9044 Mark main input as a pre-processed input and activate clean source input
9045 stream. This allows the input to be pre-processed with various filters to help
9046 the metrics calculation while keeping the frame selection lossless. When set to
9047 @code{1}, the first stream is for the pre-processed input, and the second
9048 stream is the clean source from where the kept frames are chosen. Default is
9052 Set whether or not chroma is considered in the metric calculations. Default is
9058 Apply 2D deconvolution of video stream in frequency domain using second stream
9061 The filter accepts the following options:
9065 Set which planes to process.
9068 Set which impulse video frames will be processed, can be @var{first}
9069 or @var{all}. Default is @var{all}.
9072 Set noise when doing divisions. Default is @var{0.0000001}. Useful when width
9073 and height are not same and not power of 2 or if stream prior to convolving
9077 The @code{deconvolve} filter also supports the @ref{framesync} options.
9081 Reduce cross-luminance (dot-crawl) and cross-color (rainbows) from video.
9083 It accepts the following options:
9087 Set mode of operation. Can be combination of @var{dotcrawl} for cross-luminance reduction and/or
9088 @var{rainbows} for cross-color reduction.
9091 Set spatial luma threshold. Lower values increases reduction of cross-luminance.
9094 Set tolerance for temporal luma. Higher values increases reduction of cross-luminance.
9097 Set tolerance for chroma temporal variation. Higher values increases reduction of cross-color.
9100 Set temporal chroma threshold. Lower values increases reduction of cross-color.
9105 Apply deflate effect to the video.
9107 This filter replaces the pixel by the local(3x3) average by taking into account
9108 only values lower than the pixel.
9110 It accepts the following options:
9117 Limit the maximum change for each plane, default is 65535.
9118 If 0, plane will remain unchanged.
9121 @subsection Commands
9123 This filter supports the all above options as @ref{commands}.
9127 Remove temporal frame luminance variations.
9129 It accepts the following options:
9133 Set moving-average filter size in frames. Default is 5. Allowed range is 2 - 129.
9136 Set averaging mode to smooth temporal luminance variations.
9138 Available values are:
9163 Do not actually modify frame. Useful when one only wants metadata.
9168 Remove judder produced by partially interlaced telecined content.
9170 Judder can be introduced, for instance, by @ref{pullup} filter. If the original
9171 source was partially telecined content then the output of @code{pullup,dejudder}
9172 will have a variable frame rate. May change the recorded frame rate of the
9173 container. Aside from that change, this filter will not affect constant frame
9176 The option available in this filter is:
9180 Specify the length of the window over which the judder repeats.
9182 Accepts any integer greater than 1. Useful values are:
9186 If the original was telecined from 24 to 30 fps (Film to NTSC).
9189 If the original was telecined from 25 to 30 fps (PAL to NTSC).
9192 If a mixture of the two.
9195 The default is @samp{4}.
9200 Suppress a TV station logo by a simple interpolation of the surrounding
9201 pixels. Just set a rectangle covering the logo and watch it disappear
9202 (and sometimes something even uglier appear - your mileage may vary).
9204 It accepts the following parameters:
9209 Specify the top left corner coordinates of the logo. They must be
9214 Specify the width and height of the logo to clear. They must be
9218 Specify the thickness of the fuzzy edge of the rectangle (added to
9219 @var{w} and @var{h}). The default value is 1. This option is
9220 deprecated, setting higher values should no longer be necessary and
9224 When set to 1, a green rectangle is drawn on the screen to simplify
9225 finding the right @var{x}, @var{y}, @var{w}, and @var{h} parameters.
9226 The default value is 0.
9228 The rectangle is drawn on the outermost pixels which will be (partly)
9229 replaced with interpolated values. The values of the next pixels
9230 immediately outside this rectangle in each direction will be used to
9231 compute the interpolated pixel values inside the rectangle.
9235 @subsection Examples
9239 Set a rectangle covering the area with top left corner coordinates 0,0
9240 and size 100x77, and a band of size 10:
9242 delogo=x=0:y=0:w=100:h=77:band=10
9250 Remove the rain in the input image/video by applying the derain methods based on
9251 convolutional neural networks. Supported models:
9255 Recurrent Squeeze-and-Excitation Context Aggregation Net (RESCAN).
9256 See @url{http://openaccess.thecvf.com/content_ECCV_2018/papers/Xia_Li_Recurrent_Squeeze-and-Excitation_Context_ECCV_2018_paper.pdf}.
9259 Training as well as model generation scripts are provided in
9260 the repository at @url{https://github.com/XueweiMeng/derain_filter.git}.
9262 Native model files (.model) can be generated from TensorFlow model
9263 files (.pb) by using tools/python/convert.py
9265 The filter accepts the following options:
9269 Specify which filter to use. This option accepts the following values:
9273 Derain filter. To conduct derain filter, you need to use a derain model.
9276 Dehaze filter. To conduct dehaze filter, you need to use a dehaze model.
9278 Default value is @samp{derain}.
9281 Specify which DNN backend to use for model loading and execution. This option accepts
9282 the following values:
9286 Native implementation of DNN loading and execution.
9289 TensorFlow backend. To enable this backend you
9290 need to install the TensorFlow for C library (see
9291 @url{https://www.tensorflow.org/install/install_c}) and configure FFmpeg with
9292 @code{--enable-libtensorflow}
9294 Default value is @samp{native}.
9297 Set path to model file specifying network architecture and its parameters.
9298 Note that different backends use different file formats. TensorFlow and native
9299 backend can load files for only its format.
9302 It can also be finished with @ref{dnn_processing} filter.
9306 Attempt to fix small changes in horizontal and/or vertical shift. This
9307 filter helps remove camera shake from hand-holding a camera, bumping a
9308 tripod, moving on a vehicle, etc.
9310 The filter accepts the following options:
9318 Specify a rectangular area where to limit the search for motion
9320 If desired the search for motion vectors can be limited to a
9321 rectangular area of the frame defined by its top left corner, width
9322 and height. These parameters have the same meaning as the drawbox
9323 filter which can be used to visualise the position of the bounding
9326 This is useful when simultaneous movement of subjects within the frame
9327 might be confused for camera motion by the motion vector search.
9329 If any or all of @var{x}, @var{y}, @var{w} and @var{h} are set to -1
9330 then the full frame is used. This allows later options to be set
9331 without specifying the bounding box for the motion vector search.
9333 Default - search the whole frame.
9337 Specify the maximum extent of movement in x and y directions in the
9338 range 0-64 pixels. Default 16.
9341 Specify how to generate pixels to fill blanks at the edge of the
9342 frame. Available values are:
9345 Fill zeroes at blank locations
9347 Original image at blank locations
9349 Extruded edge value at blank locations
9351 Mirrored edge at blank locations
9353 Default value is @samp{mirror}.
9356 Specify the blocksize to use for motion search. Range 4-128 pixels,
9360 Specify the contrast threshold for blocks. Only blocks with more than
9361 the specified contrast (difference between darkest and lightest
9362 pixels) will be considered. Range 1-255, default 125.
9365 Specify the search strategy. Available values are:
9368 Set exhaustive search
9370 Set less exhaustive search.
9372 Default value is @samp{exhaustive}.
9375 If set then a detailed log of the motion search is written to the
9382 Remove unwanted contamination of foreground colors, caused by reflected color of
9383 greenscreen or bluescreen.
9385 This filter accepts the following options:
9389 Set what type of despill to use.
9392 Set how spillmap will be generated.
9395 Set how much to get rid of still remaining spill.
9398 Controls amount of red in spill area.
9401 Controls amount of green in spill area.
9402 Should be -1 for greenscreen.
9405 Controls amount of blue in spill area.
9406 Should be -1 for bluescreen.
9409 Controls brightness of spill area, preserving colors.
9412 Modify alpha from generated spillmap.
9415 @subsection Commands
9417 This filter supports the all above options as @ref{commands}.
9421 Apply an exact inverse of the telecine operation. It requires a predefined
9422 pattern specified using the pattern option which must be the same as that passed
9423 to the telecine filter.
9425 This filter accepts the following options:
9434 The default value is @code{top}.
9438 A string of numbers representing the pulldown pattern you wish to apply.
9439 The default value is @code{23}.
9442 A number representing position of the first frame with respect to the telecine
9443 pattern. This is to be used if the stream is cut. The default value is @code{0}.
9448 Apply dilation effect to the video.
9450 This filter replaces the pixel by the local(3x3) maximum.
9452 It accepts the following options:
9459 Limit the maximum change for each plane, default is 65535.
9460 If 0, plane will remain unchanged.
9463 Flag which specifies the pixel to refer to. Default is 255 i.e. all eight
9466 Flags to local 3x3 coordinates maps like this:
9473 @subsection Commands
9475 This filter supports the all above options as @ref{commands}.
9479 Displace pixels as indicated by second and third input stream.
9481 It takes three input streams and outputs one stream, the first input is the
9482 source, and second and third input are displacement maps.
9484 The second input specifies how much to displace pixels along the
9485 x-axis, while the third input specifies how much to displace pixels
9487 If one of displacement map streams terminates, last frame from that
9488 displacement map will be used.
9490 Note that once generated, displacements maps can be reused over and over again.
9492 A description of the accepted options follows.
9496 Set displace behavior for pixels that are out of range.
9498 Available values are:
9501 Missing pixels are replaced by black pixels.
9504 Adjacent pixels will spread out to replace missing pixels.
9507 Out of range pixels are wrapped so they point to pixels of other side.
9510 Out of range pixels will be replaced with mirrored pixels.
9512 Default is @samp{smear}.
9516 @subsection Examples
9520 Add ripple effect to rgb input of video size hd720:
9522 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
9526 Add wave effect to rgb input of video size hd720:
9528 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
9532 @anchor{dnn_processing}
9533 @section dnn_processing
9535 Do image processing with deep neural networks. It works together with another filter
9536 which converts the pixel format of the Frame to what the dnn network requires.
9538 The filter accepts the following options:
9542 Specify which DNN backend to use for model loading and execution. This option accepts
9543 the following values:
9547 Native implementation of DNN loading and execution.
9550 TensorFlow backend. To enable this backend you
9551 need to install the TensorFlow for C library (see
9552 @url{https://www.tensorflow.org/install/install_c}) and configure FFmpeg with
9553 @code{--enable-libtensorflow}
9556 OpenVINO backend. To enable this backend you
9557 need to build and install the OpenVINO for C library (see
9558 @url{https://github.com/openvinotoolkit/openvino/blob/master/build-instruction.md}) and configure FFmpeg with
9559 @code{--enable-libopenvino} (--extra-cflags=-I... --extra-ldflags=-L... might
9560 be needed if the header files and libraries are not installed into system path)
9564 Default value is @samp{native}.
9567 Set path to model file specifying network architecture and its parameters.
9568 Note that different backends use different file formats. TensorFlow, OpenVINO and native
9569 backend can load files for only its format.
9571 Native model file (.model) can be generated from TensorFlow model file (.pb) by using tools/python/convert.py
9574 Set the input name of the dnn network.
9577 Set the output name of the dnn network.
9581 @subsection Examples
9585 Remove rain in rgb24 frame with can.pb (see @ref{derain} filter):
9587 ./ffmpeg -i rain.jpg -vf format=rgb24,dnn_processing=dnn_backend=tensorflow:model=can.pb:input=x:output=y derain.jpg
9591 Halve the pixel value of the frame with format gray32f:
9593 ffmpeg -i input.jpg -vf format=grayf32,dnn_processing=model=halve_gray_float.model:input=dnn_in:output=dnn_out:dnn_backend=native -y out.native.png
9597 Handle the Y channel with srcnn.pb (see @ref{sr} filter) for frame with yuv420p (planar YUV formats supported):
9599 ./ffmpeg -i 480p.jpg -vf format=yuv420p,scale=w=iw*2:h=ih*2,dnn_processing=dnn_backend=tensorflow:model=srcnn.pb:input=x:output=y -y srcnn.jpg
9603 Handle the Y channel with espcn.pb (see @ref{sr} filter), which changes frame size, for format yuv420p (planar YUV formats supported):
9605 ./ffmpeg -i 480p.jpg -vf format=yuv420p,dnn_processing=dnn_backend=tensorflow:model=espcn.pb:input=x:output=y -y tmp.espcn.jpg
9612 Draw a colored box on the input image.
9614 It accepts the following parameters:
9619 The expressions which specify the top left corner coordinates of the box. It defaults to 0.
9623 The expressions which specify the width and height of the box; if 0 they are interpreted as
9624 the input width and height. It defaults to 0.
9627 Specify the color of the box to write. For the general syntax of this option,
9628 check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. If the special
9629 value @code{invert} is used, the box edge color is the same as the
9630 video with inverted luma.
9633 The expression which sets the thickness of the box edge.
9634 A value of @code{fill} will create a filled box. Default value is @code{3}.
9636 See below for the list of accepted constants.
9639 Applicable if the input has alpha. With value @code{1}, the pixels of the painted box
9640 will overwrite the video's color and alpha pixels.
9641 Default is @code{0}, which composites the box onto the input, leaving the video's alpha intact.
9644 The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
9645 following constants:
9649 The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
9653 horizontal and vertical chroma subsample values. For example for the
9654 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
9658 The input width and height.
9661 The input sample aspect ratio.
9665 The x and y offset coordinates where the box is drawn.
9669 The width and height of the drawn box.
9672 The thickness of the drawn box.
9674 These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
9675 each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
9679 @subsection Examples
9683 Draw a black box around the edge of the input image:
9689 Draw a box with color red and an opacity of 50%:
9691 drawbox=10:20:200:60:red@@0.5
9694 The previous example can be specified as:
9696 drawbox=x=10:y=20:w=200:h=60:color=red@@0.5
9700 Fill the box with pink color:
9702 drawbox=x=10:y=10:w=100:h=100:color=pink@@0.5:t=fill
9706 Draw a 2-pixel red 2.40:1 mask:
9708 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
9712 @subsection Commands
9713 This filter supports same commands as options.
9714 The command accepts the same syntax of the corresponding option.
9716 If the specified expression is not valid, it is kept at its current
9721 Draw a graph using input video metadata.
9723 It accepts the following parameters:
9727 Set 1st frame metadata key from which metadata values will be used to draw a graph.
9730 Set 1st foreground color expression.
9733 Set 2nd frame metadata key from which metadata values will be used to draw a graph.
9736 Set 2nd foreground color expression.
9739 Set 3rd frame metadata key from which metadata values will be used to draw a graph.
9742 Set 3rd foreground color expression.
9745 Set 4th frame metadata key from which metadata values will be used to draw a graph.
9748 Set 4th foreground color expression.
9751 Set minimal value of metadata value.
9754 Set maximal value of metadata value.
9757 Set graph background color. Default is white.
9762 Available values for mode is:
9769 Default is @code{line}.
9774 Available values for slide is:
9777 Draw new frame when right border is reached.
9780 Replace old columns with new ones.
9783 Scroll from right to left.
9786 Scroll from left to right.
9789 Draw single picture.
9792 Default is @code{frame}.
9795 Set size of graph video. For the syntax of this option, check the
9796 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
9797 The default value is @code{900x256}.
9800 Set the output frame rate. Default value is @code{25}.
9802 The foreground color expressions can use the following variables:
9805 Minimal value of metadata value.
9808 Maximal value of metadata value.
9811 Current metadata key value.
9814 The color is defined as 0xAABBGGRR.
9817 Example using metadata from @ref{signalstats} filter:
9819 signalstats,drawgraph=lavfi.signalstats.YAVG:min=0:max=255
9822 Example using metadata from @ref{ebur128} filter:
9824 ebur128=metadata=1,adrawgraph=lavfi.r128.M:min=-120:max=5
9829 Draw a grid on the input image.
9831 It accepts the following parameters:
9836 The expressions which specify the coordinates of some point of grid intersection (meant to configure offset). Both default to 0.
9840 The expressions which specify the width and height of the grid cell, if 0 they are interpreted as the
9841 input width and height, respectively, minus @code{thickness}, so image gets
9842 framed. Default to 0.
9845 Specify the color of the grid. For the general syntax of this option,
9846 check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. If the special
9847 value @code{invert} is used, the grid color is the same as the
9848 video with inverted luma.
9851 The expression which sets the thickness of the grid line. Default value is @code{1}.
9853 See below for the list of accepted constants.
9856 Applicable if the input has alpha. With @code{1} the pixels of the painted grid
9857 will overwrite the video's color and alpha pixels.
9858 Default is @code{0}, which composites the grid onto the input, leaving the video's alpha intact.
9861 The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
9862 following constants:
9866 The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
9870 horizontal and vertical chroma subsample values. For example for the
9871 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
9875 The input grid cell width and height.
9878 The input sample aspect ratio.
9882 The x and y coordinates of some point of grid intersection (meant to configure offset).
9886 The width and height of the drawn cell.
9889 The thickness of the drawn cell.
9891 These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
9892 each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
9896 @subsection Examples
9900 Draw a grid with cell 100x100 pixels, thickness 2 pixels, with color red and an opacity of 50%:
9902 drawgrid=width=100:height=100:thickness=2:color=red@@0.5
9906 Draw a white 3x3 grid with an opacity of 50%:
9908 drawgrid=w=iw/3:h=ih/3:t=2:c=white@@0.5
9912 @subsection Commands
9913 This filter supports same commands as options.
9914 The command accepts the same syntax of the corresponding option.
9916 If the specified expression is not valid, it is kept at its current
9922 Draw a text string or text from a specified file on top of a video, using the
9923 libfreetype library.
9925 To enable compilation of this filter, you need to configure FFmpeg with
9926 @code{--enable-libfreetype}.
9927 To enable default font fallback and the @var{font} option you need to
9928 configure FFmpeg with @code{--enable-libfontconfig}.
9929 To enable the @var{text_shaping} option, you need to configure FFmpeg with
9930 @code{--enable-libfribidi}.
9934 It accepts the following parameters:
9939 Used to draw a box around text using the background color.
9940 The value must be either 1 (enable) or 0 (disable).
9941 The default value of @var{box} is 0.
9944 Set the width of the border to be drawn around the box using @var{boxcolor}.
9945 The default value of @var{boxborderw} is 0.
9948 The color to be used for drawing box around text. For the syntax of this
9949 option, check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
9951 The default value of @var{boxcolor} is "white".
9954 Set the line spacing in pixels of the border to be drawn around the box using @var{box}.
9955 The default value of @var{line_spacing} is 0.
9958 Set the width of the border to be drawn around the text using @var{bordercolor}.
9959 The default value of @var{borderw} is 0.
9962 Set the color to be used for drawing border around text. For the syntax of this
9963 option, check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
9965 The default value of @var{bordercolor} is "black".
9968 Select how the @var{text} is expanded. Can be either @code{none},
9969 @code{strftime} (deprecated) or
9970 @code{normal} (default). See the @ref{drawtext_expansion, Text expansion} section
9974 Set a start time for the count. Value is in microseconds. Only applied
9975 in the deprecated strftime expansion mode. To emulate in normal expansion
9976 mode use the @code{pts} function, supplying the start time (in seconds)
9977 as the second argument.
9980 If true, check and fix text coords to avoid clipping.
9983 The color to be used for drawing fonts. For the syntax of this option, check
9984 the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
9986 The default value of @var{fontcolor} is "black".
9988 @item fontcolor_expr
9989 String which is expanded the same way as @var{text} to obtain dynamic
9990 @var{fontcolor} value. By default this option has empty value and is not
9991 processed. When this option is set, it overrides @var{fontcolor} option.
9994 The font family to be used for drawing text. By default Sans.
9997 The font file to be used for drawing text. The path must be included.
9998 This parameter is mandatory if the fontconfig support is disabled.
10001 Draw the text applying alpha blending. The value can
10002 be a number between 0.0 and 1.0.
10003 The expression accepts the same variables @var{x, y} as well.
10004 The default value is 1.
10005 Please see @var{fontcolor_expr}.
10008 The font size to be used for drawing text.
10009 The default value of @var{fontsize} is 16.
10012 If set to 1, attempt to shape the text (for example, reverse the order of
10013 right-to-left text and join Arabic characters) before drawing it.
10014 Otherwise, just draw the text exactly as given.
10015 By default 1 (if supported).
10017 @item ft_load_flags
10018 The flags to be used for loading the fonts.
10020 The flags map the corresponding flags supported by libfreetype, and are
10021 a combination of the following values:
10028 @item vertical_layout
10029 @item force_autohint
10032 @item ignore_global_advance_width
10034 @item ignore_transform
10036 @item linear_design
10040 Default value is "default".
10042 For more information consult the documentation for the FT_LOAD_*
10046 The color to be used for drawing a shadow behind the drawn text. For the
10047 syntax of this option, check the @ref{color syntax,,"Color" section in the
10048 ffmpeg-utils manual,ffmpeg-utils}.
10050 The default value of @var{shadowcolor} is "black".
10054 The x and y offsets for the text shadow position with respect to the
10055 position of the text. They can be either positive or negative
10056 values. The default value for both is "0".
10059 The starting frame number for the n/frame_num variable. The default value
10063 The size in number of spaces to use for rendering the tab.
10064 Default value is 4.
10067 Set the initial timecode representation in "hh:mm:ss[:;.]ff"
10068 format. It can be used with or without text parameter. @var{timecode_rate}
10069 option must be specified.
10071 @item timecode_rate, rate, r
10072 Set the timecode frame rate (timecode only). Value will be rounded to nearest
10073 integer. Minimum value is "1".
10074 Drop-frame timecode is supported for frame rates 30 & 60.
10077 If set to 1, the output of the timecode option will wrap around at 24 hours.
10078 Default is 0 (disabled).
10081 The text string to be drawn. The text must be a sequence of UTF-8
10082 encoded characters.
10083 This parameter is mandatory if no file is specified with the parameter
10087 A text file containing text to be drawn. The text must be a sequence
10088 of UTF-8 encoded characters.
10090 This parameter is mandatory if no text string is specified with the
10091 parameter @var{text}.
10093 If both @var{text} and @var{textfile} are specified, an error is thrown.
10096 If set to 1, the @var{textfile} will be reloaded before each frame.
10097 Be sure to update it atomically, or it may be read partially, or even fail.
10101 The expressions which specify the offsets where text will be drawn
10102 within the video frame. They are relative to the top/left border of the
10105 The default value of @var{x} and @var{y} is "0".
10107 See below for the list of accepted constants and functions.
10110 The parameters for @var{x} and @var{y} are expressions containing the
10111 following constants and functions:
10115 input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
10119 horizontal and vertical chroma subsample values. For example for the
10120 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
10123 the height of each text line
10131 @item max_glyph_a, ascent
10132 the maximum distance from the baseline to the highest/upper grid
10133 coordinate used to place a glyph outline point, for all the rendered
10135 It is a positive value, due to the grid's orientation with the Y axis
10138 @item max_glyph_d, descent
10139 the maximum distance from the baseline to the lowest grid coordinate
10140 used to place a glyph outline point, for all the rendered glyphs.
10141 This is a negative value, due to the grid's orientation, with the Y axis
10145 maximum glyph height, that is the maximum height for all the glyphs
10146 contained in the rendered text, it is equivalent to @var{ascent} -
10150 maximum glyph width, that is the maximum width for all the glyphs
10151 contained in the rendered text
10154 the number of input frame, starting from 0
10156 @item rand(min, max)
10157 return a random number included between @var{min} and @var{max}
10160 The input sample aspect ratio.
10163 timestamp expressed in seconds, NAN if the input timestamp is unknown
10166 the height of the rendered text
10169 the width of the rendered text
10173 the x and y offset coordinates where the text is drawn.
10175 These parameters allow the @var{x} and @var{y} expressions to refer
10176 to each other, so you can for example specify @code{y=x/dar}.
10179 A one character description of the current frame's picture type.
10182 The current packet's position in the input file or stream
10183 (in bytes, from the start of the input). A value of -1 indicates
10184 this info is not available.
10187 The current packet's duration, in seconds.
10190 The current packet's size (in bytes).
10193 @anchor{drawtext_expansion}
10194 @subsection Text expansion
10196 If @option{expansion} is set to @code{strftime},
10197 the filter recognizes strftime() sequences in the provided text and
10198 expands them accordingly. Check the documentation of strftime(). This
10199 feature is deprecated.
10201 If @option{expansion} is set to @code{none}, the text is printed verbatim.
10203 If @option{expansion} is set to @code{normal} (which is the default),
10204 the following expansion mechanism is used.
10206 The backslash character @samp{\}, followed by any character, always expands to
10207 the second character.
10209 Sequences of the form @code{%@{...@}} are expanded. The text between the
10210 braces is a function name, possibly followed by arguments separated by ':'.
10211 If the arguments contain special characters or delimiters (':' or '@}'),
10212 they should be escaped.
10214 Note that they probably must also be escaped as the value for the
10215 @option{text} option in the filter argument string and as the filter
10216 argument in the filtergraph description, and possibly also for the shell,
10217 that makes up to four levels of escaping; using a text file avoids these
10220 The following functions are available:
10225 The expression evaluation result.
10227 It must take one argument specifying the expression to be evaluated,
10228 which accepts the same constants and functions as the @var{x} and
10229 @var{y} values. Note that not all constants should be used, for
10230 example the text size is not known when evaluating the expression, so
10231 the constants @var{text_w} and @var{text_h} will have an undefined
10234 @item expr_int_format, eif
10235 Evaluate the expression's value and output as formatted integer.
10237 The first argument is the expression to be evaluated, just as for the @var{expr} function.
10238 The second argument specifies the output format. Allowed values are @samp{x},
10239 @samp{X}, @samp{d} and @samp{u}. They are treated exactly as in the
10240 @code{printf} function.
10241 The third parameter is optional and sets the number of positions taken by the output.
10242 It can be used to add padding with zeros from the left.
10245 The time at which the filter is running, expressed in UTC.
10246 It can accept an argument: a strftime() format string.
10249 The time at which the filter is running, expressed in the local time zone.
10250 It can accept an argument: a strftime() format string.
10253 Frame metadata. Takes one or two arguments.
10255 The first argument is mandatory and specifies the metadata key.
10257 The second argument is optional and specifies a default value, used when the
10258 metadata key is not found or empty.
10260 Available metadata can be identified by inspecting entries
10261 starting with TAG included within each frame section
10262 printed by running @code{ffprobe -show_frames}.
10264 String metadata generated in filters leading to
10265 the drawtext filter are also available.
10268 The frame number, starting from 0.
10271 A one character description of the current picture type.
10274 The timestamp of the current frame.
10275 It can take up to three arguments.
10277 The first argument is the format of the timestamp; it defaults to @code{flt}
10278 for seconds as a decimal number with microsecond accuracy; @code{hms} stands
10279 for a formatted @var{[-]HH:MM:SS.mmm} timestamp with millisecond accuracy.
10280 @code{gmtime} stands for the timestamp of the frame formatted as UTC time;
10281 @code{localtime} stands for the timestamp of the frame formatted as
10282 local time zone time.
10284 The second argument is an offset added to the timestamp.
10286 If the format is set to @code{hms}, a third argument @code{24HH} may be
10287 supplied to present the hour part of the formatted timestamp in 24h format
10290 If the format is set to @code{localtime} or @code{gmtime},
10291 a third argument may be supplied: a strftime() format string.
10292 By default, @var{YYYY-MM-DD HH:MM:SS} format will be used.
10295 @subsection Commands
10297 This filter supports altering parameters via commands:
10300 Alter existing filter parameters.
10302 Syntax for the argument is the same as for filter invocation, e.g.
10305 fontsize=56:fontcolor=green:text='Hello World'
10308 Full filter invocation with sendcmd would look like this:
10311 sendcmd=c='56.0 drawtext reinit fontsize=56\:fontcolor=green\:text=Hello\\ World'
10315 If the entire argument can't be parsed or applied as valid values then the filter will
10316 continue with its existing parameters.
10318 @subsection Examples
10322 Draw "Test Text" with font FreeSerif, using the default values for the
10323 optional parameters.
10326 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"
10330 Draw 'Test Text' with font FreeSerif of size 24 at position x=100
10331 and y=50 (counting from the top-left corner of the screen), text is
10332 yellow with a red box around it. Both the text and the box have an
10336 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
10337 x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2"
10340 Note that the double quotes are not necessary if spaces are not used
10341 within the parameter list.
10344 Show the text at the center of the video frame:
10346 drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h)/2"
10350 Show the text at a random position, switching to a new position every 30 seconds:
10352 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)"
10356 Show a text line sliding from right to left in the last row of the video
10357 frame. The file @file{LONG_LINE} is assumed to contain a single line
10360 drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t"
10364 Show the content of file @file{CREDITS} off the bottom of the frame and scroll up.
10366 drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t"
10370 Draw a single green letter "g", at the center of the input video.
10371 The glyph baseline is placed at half screen height.
10373 drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent"
10377 Show text for 1 second every 3 seconds:
10379 drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:enable=lt(mod(t\,3)\,1):text='blink'"
10383 Use fontconfig to set the font. Note that the colons need to be escaped.
10385 drawtext='fontfile=Linux Libertine O-40\:style=Semibold:text=FFmpeg'
10389 Draw "Test Text" with font size dependent on height of the video.
10391 drawtext="text='Test Text': fontsize=h/30: x=(w-text_w)/2: y=(h-text_h*2)"
10395 Print the date of a real-time encoding (see strftime(3)):
10397 drawtext='fontfile=FreeSans.ttf:text=%@{localtime\:%a %b %d %Y@}'
10401 Show text fading in and out (appearing/disappearing):
10404 DS=1.0 # display start
10405 DE=10.0 # display end
10406 FID=1.5 # fade in duration
10407 FOD=5 # fade out duration
10408 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 @}"
10412 Horizontally align multiple separate texts. Note that @option{max_glyph_a}
10413 and the @option{fontsize} value are included in the @option{y} offset.
10415 drawtext=fontfile=FreeSans.ttf:text=DOG:fontsize=24:x=10:y=20+24-max_glyph_a,
10416 drawtext=fontfile=FreeSans.ttf:text=cow:fontsize=24:x=80:y=20+24-max_glyph_a
10420 Plot special @var{lavf.image2dec.source_basename} metadata onto each frame if
10421 such metadata exists. Otherwise, plot the string "NA". Note that image2 demuxer
10422 must have option @option{-export_path_metadata 1} for the special metadata fields
10423 to be available for filters.
10425 drawtext="fontsize=20:fontcolor=white:fontfile=FreeSans.ttf:text='%@{metadata\:lavf.image2dec.source_basename\:NA@}':x=10:y=10"
10430 For more information about libfreetype, check:
10431 @url{http://www.freetype.org/}.
10433 For more information about fontconfig, check:
10434 @url{http://freedesktop.org/software/fontconfig/fontconfig-user.html}.
10436 For more information about libfribidi, check:
10437 @url{http://fribidi.org/}.
10439 @section edgedetect
10441 Detect and draw edges. The filter uses the Canny Edge Detection algorithm.
10443 The filter accepts the following options:
10448 Set low and high threshold values used by the Canny thresholding
10451 The high threshold selects the "strong" edge pixels, which are then
10452 connected through 8-connectivity with the "weak" edge pixels selected
10453 by the low threshold.
10455 @var{low} and @var{high} threshold values must be chosen in the range
10456 [0,1], and @var{low} should be lesser or equal to @var{high}.
10458 Default value for @var{low} is @code{20/255}, and default value for @var{high}
10462 Define the drawing mode.
10466 Draw white/gray wires on black background.
10469 Mix the colors to create a paint/cartoon effect.
10472 Apply Canny edge detector on all selected planes.
10474 Default value is @var{wires}.
10477 Select planes for filtering. By default all available planes are filtered.
10480 @subsection Examples
10484 Standard edge detection with custom values for the hysteresis thresholding:
10486 edgedetect=low=0.1:high=0.4
10490 Painting effect without thresholding:
10492 edgedetect=mode=colormix:high=0
10498 Apply a posterize effect using the ELBG (Enhanced LBG) algorithm.
10500 For each input image, the filter will compute the optimal mapping from
10501 the input to the output given the codebook length, that is the number
10502 of distinct output colors.
10504 This filter accepts the following options.
10507 @item codebook_length, l
10508 Set codebook length. The value must be a positive integer, and
10509 represents the number of distinct output colors. Default value is 256.
10512 Set the maximum number of iterations to apply for computing the optimal
10513 mapping. The higher the value the better the result and the higher the
10514 computation time. Default value is 1.
10517 Set a random seed, must be an integer included between 0 and
10518 UINT32_MAX. If not specified, or if explicitly set to -1, the filter
10519 will try to use a good random seed on a best effort basis.
10522 Set pal8 output pixel format. This option does not work with codebook
10523 length greater than 256.
10528 Measure graylevel entropy in histogram of color channels of video frames.
10530 It accepts the following parameters:
10534 Can be either @var{normal} or @var{diff}. Default is @var{normal}.
10536 @var{diff} mode measures entropy of histogram delta values, absolute differences
10537 between neighbour histogram values.
10541 Set brightness, contrast, saturation and approximate gamma adjustment.
10543 The filter accepts the following options:
10547 Set the contrast expression. The value must be a float value in range
10548 @code{-1000.0} to @code{1000.0}. The default value is "1".
10551 Set the brightness expression. The value must be a float value in
10552 range @code{-1.0} to @code{1.0}. The default value is "0".
10555 Set the saturation expression. The value must be a float in
10556 range @code{0.0} to @code{3.0}. The default value is "1".
10559 Set the gamma expression. The value must be a float in range
10560 @code{0.1} to @code{10.0}. The default value is "1".
10563 Set the gamma expression for red. The value must be a float in
10564 range @code{0.1} to @code{10.0}. The default value is "1".
10567 Set the gamma expression for green. The value must be a float in range
10568 @code{0.1} to @code{10.0}. The default value is "1".
10571 Set the gamma expression for blue. The value must be a float in range
10572 @code{0.1} to @code{10.0}. The default value is "1".
10575 Set the gamma weight expression. It can be used to reduce the effect
10576 of a high gamma value on bright image areas, e.g. keep them from
10577 getting overamplified and just plain white. The value must be a float
10578 in range @code{0.0} to @code{1.0}. A value of @code{0.0} turns the
10579 gamma correction all the way down while @code{1.0} leaves it at its
10580 full strength. Default is "1".
10583 Set when the expressions for brightness, contrast, saturation and
10584 gamma expressions are evaluated.
10586 It accepts the following values:
10589 only evaluate expressions once during the filter initialization or
10590 when a command is processed
10593 evaluate expressions for each incoming frame
10596 Default value is @samp{init}.
10599 The expressions accept the following parameters:
10602 frame count of the input frame starting from 0
10605 byte position of the corresponding packet in the input file, NAN if
10609 frame rate of the input video, NAN if the input frame rate is unknown
10612 timestamp expressed in seconds, NAN if the input timestamp is unknown
10615 @subsection Commands
10616 The filter supports the following commands:
10620 Set the contrast expression.
10623 Set the brightness expression.
10626 Set the saturation expression.
10629 Set the gamma expression.
10632 Set the gamma_r expression.
10635 Set gamma_g expression.
10638 Set gamma_b expression.
10641 Set gamma_weight expression.
10643 The command accepts the same syntax of the corresponding option.
10645 If the specified expression is not valid, it is kept at its current
10652 Apply erosion effect to the video.
10654 This filter replaces the pixel by the local(3x3) minimum.
10656 It accepts the following options:
10663 Limit the maximum change for each plane, default is 65535.
10664 If 0, plane will remain unchanged.
10667 Flag which specifies the pixel to refer to. Default is 255 i.e. all eight
10670 Flags to local 3x3 coordinates maps like this:
10677 @subsection Commands
10679 This filter supports the all above options as @ref{commands}.
10681 @section extractplanes
10683 Extract color channel components from input video stream into
10684 separate grayscale video streams.
10686 The filter accepts the following option:
10690 Set plane(s) to extract.
10692 Available values for planes are:
10703 Choosing planes not available in the input will result in an error.
10704 That means you cannot select @code{r}, @code{g}, @code{b} planes
10705 with @code{y}, @code{u}, @code{v} planes at same time.
10708 @subsection Examples
10712 Extract luma, u and v color channel component from input video frame
10713 into 3 grayscale outputs:
10715 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
10721 Apply a fade-in/out effect to the input video.
10723 It accepts the following parameters:
10727 The effect type can be either "in" for a fade-in, or "out" for a fade-out
10729 Default is @code{in}.
10731 @item start_frame, s
10732 Specify the number of the frame to start applying the fade
10733 effect at. Default is 0.
10736 The number of frames that the fade effect lasts. At the end of the
10737 fade-in effect, the output video will have the same intensity as the input video.
10738 At the end of the fade-out transition, the output video will be filled with the
10739 selected @option{color}.
10743 If set to 1, fade only alpha channel, if one exists on the input.
10744 Default value is 0.
10746 @item start_time, st
10747 Specify the timestamp (in seconds) of the frame to start to apply the fade
10748 effect. If both start_frame and start_time are specified, the fade will start at
10749 whichever comes last. Default is 0.
10752 The number of seconds for which the fade effect has to last. At the end of the
10753 fade-in effect the output video will have the same intensity as the input video,
10754 at the end of the fade-out transition the output video will be filled with the
10755 selected @option{color}.
10756 If both duration and nb_frames are specified, duration is used. Default is 0
10757 (nb_frames is used by default).
10760 Specify the color of the fade. Default is "black".
10763 @subsection Examples
10767 Fade in the first 30 frames of video:
10772 The command above is equivalent to:
10778 Fade out the last 45 frames of a 200-frame video:
10781 fade=type=out:start_frame=155:nb_frames=45
10785 Fade in the first 25 frames and fade out the last 25 frames of a 1000-frame video:
10787 fade=in:0:25, fade=out:975:25
10791 Make the first 5 frames yellow, then fade in from frame 5-24:
10793 fade=in:5:20:color=yellow
10797 Fade in alpha over first 25 frames of video:
10799 fade=in:0:25:alpha=1
10803 Make the first 5.5 seconds black, then fade in for 0.5 seconds:
10805 fade=t=in:st=5.5:d=0.5
10811 Denoise frames using 3D FFT (frequency domain filtering).
10813 The filter accepts the following options:
10817 Set the noise sigma constant. This sets denoising strength.
10818 Default value is 1. Allowed range is from 0 to 30.
10819 Using very high sigma with low overlap may give blocking artifacts.
10822 Set amount of denoising. By default all detected noise is reduced.
10823 Default value is 1. Allowed range is from 0 to 1.
10826 Set size of block, Default is 4, can be 3, 4, 5 or 6.
10827 Actual size of block in pixels is 2 to power of @var{block}, so by default
10828 block size in pixels is 2^4 which is 16.
10831 Set block overlap. Default is 0.5. Allowed range is from 0.2 to 0.8.
10834 Set number of previous frames to use for denoising. By default is set to 0.
10837 Set number of next frames to to use for denoising. By default is set to 0.
10840 Set planes which will be filtered, by default are all available filtered
10845 Apply arbitrary expressions to samples in frequency domain
10849 Adjust the dc value (gain) of the luma plane of the image. The filter
10850 accepts an integer value in range @code{0} to @code{1000}. The default
10851 value is set to @code{0}.
10854 Adjust the dc value (gain) of the 1st chroma plane of the image. The
10855 filter accepts an integer value in range @code{0} to @code{1000}. The
10856 default value is set to @code{0}.
10859 Adjust the dc value (gain) of the 2nd chroma plane of the image. The
10860 filter accepts an integer value in range @code{0} to @code{1000}. The
10861 default value is set to @code{0}.
10864 Set the frequency domain weight expression for the luma plane.
10867 Set the frequency domain weight expression for the 1st chroma plane.
10870 Set the frequency domain weight expression for the 2nd chroma plane.
10873 Set when the expressions are evaluated.
10875 It accepts the following values:
10878 Only evaluate expressions once during the filter initialization.
10881 Evaluate expressions for each incoming frame.
10884 Default value is @samp{init}.
10886 The filter accepts the following variables:
10889 The coordinates of the current sample.
10893 The width and height of the image.
10896 The number of input frame, starting from 0.
10899 @subsection Examples
10905 fftfilt=dc_Y=128:weight_Y='squish(1-(Y+X)/100)'
10911 fftfilt=dc_Y=0:weight_Y='squish((Y+X)/100-1)'
10917 fftfilt=dc_Y=0:weight_Y='1+squish(1-(Y+X)/100)'
10923 fftfilt=dc_Y=0:weight_Y='exp(-4 * ((Y+X)/(W+H)))'
10930 Extract a single field from an interlaced image using stride
10931 arithmetic to avoid wasting CPU time. The output frames are marked as
10934 The filter accepts the following options:
10938 Specify whether to extract the top (if the value is @code{0} or
10939 @code{top}) or the bottom field (if the value is @code{1} or
10945 Create new frames by copying the top and bottom fields from surrounding frames
10946 supplied as numbers by the hint file.
10950 Set file containing hints: absolute/relative frame numbers.
10952 There must be one line for each frame in a clip. Each line must contain two
10953 numbers separated by the comma, optionally followed by @code{-} or @code{+}.
10954 Numbers supplied on each line of file can not be out of [N-1,N+1] where N
10955 is current frame number for @code{absolute} mode or out of [-1, 1] range
10956 for @code{relative} mode. First number tells from which frame to pick up top
10957 field and second number tells from which frame to pick up bottom field.
10959 If optionally followed by @code{+} output frame will be marked as interlaced,
10960 else if followed by @code{-} output frame will be marked as progressive, else
10961 it will be marked same as input frame.
10962 If optionally followed by @code{t} output frame will use only top field, or in
10963 case of @code{b} it will use only bottom field.
10964 If line starts with @code{#} or @code{;} that line is skipped.
10967 Can be item @code{absolute} or @code{relative}. Default is @code{absolute}.
10970 Example of first several lines of @code{hint} file for @code{relative} mode:
10972 0,0 - # first frame
10973 1,0 - # second frame, use third's frame top field and second's frame bottom field
10974 1,0 - # third frame, use fourth's frame top field and third's frame bottom field
10989 @section fieldmatch
10991 Field matching filter for inverse telecine. It is meant to reconstruct the
10992 progressive frames from a telecined stream. The filter does not drop duplicated
10993 frames, so to achieve a complete inverse telecine @code{fieldmatch} needs to be
10994 followed by a decimation filter such as @ref{decimate} in the filtergraph.
10996 The separation of the field matching and the decimation is notably motivated by
10997 the possibility of inserting a de-interlacing filter fallback between the two.
10998 If the source has mixed telecined and real interlaced content,
10999 @code{fieldmatch} will not be able to match fields for the interlaced parts.
11000 But these remaining combed frames will be marked as interlaced, and thus can be
11001 de-interlaced by a later filter such as @ref{yadif} before decimation.
11003 In addition to the various configuration options, @code{fieldmatch} can take an
11004 optional second stream, activated through the @option{ppsrc} option. If
11005 enabled, the frames reconstruction will be based on the fields and frames from
11006 this second stream. This allows the first input to be pre-processed in order to
11007 help the various algorithms of the filter, while keeping the output lossless
11008 (assuming the fields are matched properly). Typically, a field-aware denoiser,
11009 or brightness/contrast adjustments can help.
11011 Note that this filter uses the same algorithms as TIVTC/TFM (AviSynth project)
11012 and VIVTC/VFM (VapourSynth project). The later is a light clone of TFM from
11013 which @code{fieldmatch} is based on. While the semantic and usage are very
11014 close, some behaviour and options names can differ.
11016 The @ref{decimate} filter currently only works for constant frame rate input.
11017 If your input has mixed telecined (30fps) and progressive content with a lower
11018 framerate like 24fps use the following filterchain to produce the necessary cfr
11019 stream: @code{dejudder,fps=30000/1001,fieldmatch,decimate}.
11021 The filter accepts the following options:
11025 Specify the assumed field order of the input stream. Available values are:
11029 Auto detect parity (use FFmpeg's internal parity value).
11031 Assume bottom field first.
11033 Assume top field first.
11036 Note that it is sometimes recommended not to trust the parity announced by the
11039 Default value is @var{auto}.
11042 Set the matching mode or strategy to use. @option{pc} mode is the safest in the
11043 sense that it won't risk creating jerkiness due to duplicate frames when
11044 possible, but if there are bad edits or blended fields it will end up
11045 outputting combed frames when a good match might actually exist. On the other
11046 hand, @option{pcn_ub} mode is the most risky in terms of creating jerkiness,
11047 but will almost always find a good frame if there is one. The other values are
11048 all somewhere in between @option{pc} and @option{pcn_ub} in terms of risking
11049 jerkiness and creating duplicate frames versus finding good matches in sections
11050 with bad edits, orphaned fields, blended fields, etc.
11052 More details about p/c/n/u/b are available in @ref{p/c/n/u/b meaning} section.
11054 Available values are:
11058 2-way matching (p/c)
11060 2-way matching, and trying 3rd match if still combed (p/c + n)
11062 2-way matching, and trying 3rd match (same order) if still combed (p/c + u)
11064 2-way matching, trying 3rd match if still combed, and trying 4th/5th matches if
11065 still combed (p/c + n + u/b)
11067 3-way matching (p/c/n)
11069 3-way matching, and trying 4th/5th matches if all 3 of the original matches are
11070 detected as combed (p/c/n + u/b)
11073 The parenthesis at the end indicate the matches that would be used for that
11074 mode assuming @option{order}=@var{tff} (and @option{field} on @var{auto} or
11077 In terms of speed @option{pc} mode is by far the fastest and @option{pcn_ub} is
11080 Default value is @var{pc_n}.
11083 Mark the main input stream as a pre-processed input, and enable the secondary
11084 input stream as the clean source to pick the fields from. See the filter
11085 introduction for more details. It is similar to the @option{clip2} feature from
11088 Default value is @code{0} (disabled).
11091 Set the field to match from. It is recommended to set this to the same value as
11092 @option{order} unless you experience matching failures with that setting. In
11093 certain circumstances changing the field that is used to match from can have a
11094 large impact on matching performance. Available values are:
11098 Automatic (same value as @option{order}).
11100 Match from the bottom field.
11102 Match from the top field.
11105 Default value is @var{auto}.
11108 Set whether or not chroma is included during the match comparisons. In most
11109 cases it is recommended to leave this enabled. You should set this to @code{0}
11110 only if your clip has bad chroma problems such as heavy rainbowing or other
11111 artifacts. Setting this to @code{0} could also be used to speed things up at
11112 the cost of some accuracy.
11114 Default value is @code{1}.
11118 These define an exclusion band which excludes the lines between @option{y0} and
11119 @option{y1} from being included in the field matching decision. An exclusion
11120 band can be used to ignore subtitles, a logo, or other things that may
11121 interfere with the matching. @option{y0} sets the starting scan line and
11122 @option{y1} sets the ending line; all lines in between @option{y0} and
11123 @option{y1} (including @option{y0} and @option{y1}) will be ignored. Setting
11124 @option{y0} and @option{y1} to the same value will disable the feature.
11125 @option{y0} and @option{y1} defaults to @code{0}.
11128 Set the scene change detection threshold as a percentage of maximum change on
11129 the luma plane. Good values are in the @code{[8.0, 14.0]} range. Scene change
11130 detection is only relevant in case @option{combmatch}=@var{sc}. The range for
11131 @option{scthresh} is @code{[0.0, 100.0]}.
11133 Default value is @code{12.0}.
11136 When @option{combatch} is not @var{none}, @code{fieldmatch} will take into
11137 account the combed scores of matches when deciding what match to use as the
11138 final match. Available values are:
11142 No final matching based on combed scores.
11144 Combed scores are only used when a scene change is detected.
11146 Use combed scores all the time.
11149 Default is @var{sc}.
11152 Force @code{fieldmatch} to calculate the combed metrics for certain matches and
11153 print them. This setting is known as @option{micout} in TFM/VFM vocabulary.
11154 Available values are:
11158 No forced calculation.
11160 Force p/c/n calculations.
11162 Force p/c/n/u/b calculations.
11165 Default value is @var{none}.
11168 This is the area combing threshold used for combed frame detection. This
11169 essentially controls how "strong" or "visible" combing must be to be detected.
11170 Larger values mean combing must be more visible and smaller values mean combing
11171 can be less visible or strong and still be detected. Valid settings are from
11172 @code{-1} (every pixel will be detected as combed) to @code{255} (no pixel will
11173 be detected as combed). This is basically a pixel difference value. A good
11174 range is @code{[8, 12]}.
11176 Default value is @code{9}.
11179 Sets whether or not chroma is considered in the combed frame decision. Only
11180 disable this if your source has chroma problems (rainbowing, etc.) that are
11181 causing problems for the combed frame detection with chroma enabled. Actually,
11182 using @option{chroma}=@var{0} is usually more reliable, except for the case
11183 where there is chroma only combing in the source.
11185 Default value is @code{0}.
11189 Respectively set the x-axis and y-axis size of the window used during combed
11190 frame detection. This has to do with the size of the area in which
11191 @option{combpel} pixels are required to be detected as combed for a frame to be
11192 declared combed. See the @option{combpel} parameter description for more info.
11193 Possible values are any number that is a power of 2 starting at 4 and going up
11196 Default value is @code{16}.
11199 The number of combed pixels inside any of the @option{blocky} by
11200 @option{blockx} size blocks on the frame for the frame to be detected as
11201 combed. While @option{cthresh} controls how "visible" the combing must be, this
11202 setting controls "how much" combing there must be in any localized area (a
11203 window defined by the @option{blockx} and @option{blocky} settings) on the
11204 frame. Minimum value is @code{0} and maximum is @code{blocky x blockx} (at
11205 which point no frames will ever be detected as combed). This setting is known
11206 as @option{MI} in TFM/VFM vocabulary.
11208 Default value is @code{80}.
11211 @anchor{p/c/n/u/b meaning}
11212 @subsection p/c/n/u/b meaning
11214 @subsubsection p/c/n
11216 We assume the following telecined stream:
11219 Top fields: 1 2 2 3 4
11220 Bottom fields: 1 2 3 4 4
11223 The numbers correspond to the progressive frame the fields relate to. Here, the
11224 first two frames are progressive, the 3rd and 4th are combed, and so on.
11226 When @code{fieldmatch} is configured to run a matching from bottom
11227 (@option{field}=@var{bottom}) this is how this input stream get transformed:
11232 B 1 2 3 4 4 <-- matching reference
11241 As a result of the field matching, we can see that some frames get duplicated.
11242 To perform a complete inverse telecine, you need to rely on a decimation filter
11243 after this operation. See for instance the @ref{decimate} filter.
11245 The same operation now matching from top fields (@option{field}=@var{top})
11250 T 1 2 2 3 4 <-- matching reference
11260 In these examples, we can see what @var{p}, @var{c} and @var{n} mean;
11261 basically, they refer to the frame and field of the opposite parity:
11264 @item @var{p} matches the field of the opposite parity in the previous frame
11265 @item @var{c} matches the field of the opposite parity in the current frame
11266 @item @var{n} matches the field of the opposite parity in the next frame
11271 The @var{u} and @var{b} matching are a bit special in the sense that they match
11272 from the opposite parity flag. In the following examples, we assume that we are
11273 currently matching the 2nd frame (Top:2, bottom:2). According to the match, a
11274 'x' is placed above and below each matched fields.
11276 With bottom matching (@option{field}=@var{bottom}):
11281 Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2
11282 Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3
11290 With top matching (@option{field}=@var{top}):
11295 Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2
11296 Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3
11304 @subsection Examples
11306 Simple IVTC of a top field first telecined stream:
11308 fieldmatch=order=tff:combmatch=none, decimate
11311 Advanced IVTC, with fallback on @ref{yadif} for still combed frames:
11313 fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate
11316 @section fieldorder
11318 Transform the field order of the input video.
11320 It accepts the following parameters:
11325 The output field order. Valid values are @var{tff} for top field first or @var{bff}
11326 for bottom field first.
11329 The default value is @samp{tff}.
11331 The transformation is done by shifting the picture content up or down
11332 by one line, and filling the remaining line with appropriate picture content.
11333 This method is consistent with most broadcast field order converters.
11335 If the input video is not flagged as being interlaced, or it is already
11336 flagged as being of the required output field order, then this filter does
11337 not alter the incoming video.
11339 It is very useful when converting to or from PAL DV material,
11340 which is bottom field first.
11344 ffmpeg -i in.vob -vf "fieldorder=bff" out.dv
11347 @section fifo, afifo
11349 Buffer input images and send them when they are requested.
11351 It is mainly useful when auto-inserted by the libavfilter
11354 It does not take parameters.
11356 @section fillborders
11358 Fill borders of the input video, without changing video stream dimensions.
11359 Sometimes video can have garbage at the four edges and you may not want to
11360 crop video input to keep size multiple of some number.
11362 This filter accepts the following options:
11366 Number of pixels to fill from left border.
11369 Number of pixels to fill from right border.
11372 Number of pixels to fill from top border.
11375 Number of pixels to fill from bottom border.
11380 It accepts the following values:
11383 fill pixels using outermost pixels
11386 fill pixels using mirroring
11389 fill pixels with constant value
11392 Default is @var{smear}.
11395 Set color for pixels in fixed mode. Default is @var{black}.
11398 @subsection Commands
11399 This filter supports same @ref{commands} as options.
11400 The command accepts the same syntax of the corresponding option.
11402 If the specified expression is not valid, it is kept at its current
11407 Find a rectangular object
11409 It accepts the following options:
11413 Filepath of the object image, needs to be in gray8.
11416 Detection threshold, default is 0.5.
11419 Number of mipmaps, default is 3.
11421 @item xmin, ymin, xmax, ymax
11422 Specifies the rectangle in which to search.
11425 @subsection Examples
11429 Cover a rectangular object by the supplied image of a given video using @command{ffmpeg}:
11431 ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
11437 Flood area with values of same pixel components with another values.
11439 It accepts the following options:
11442 Set pixel x coordinate.
11445 Set pixel y coordinate.
11448 Set source #0 component value.
11451 Set source #1 component value.
11454 Set source #2 component value.
11457 Set source #3 component value.
11460 Set destination #0 component value.
11463 Set destination #1 component value.
11466 Set destination #2 component value.
11469 Set destination #3 component value.
11475 Convert the input video to one of the specified pixel formats.
11476 Libavfilter will try to pick one that is suitable as input to
11479 It accepts the following parameters:
11483 A '|'-separated list of pixel format names, such as
11484 "pix_fmts=yuv420p|monow|rgb24".
11488 @subsection Examples
11492 Convert the input video to the @var{yuv420p} format
11494 format=pix_fmts=yuv420p
11497 Convert the input video to any of the formats in the list
11499 format=pix_fmts=yuv420p|yuv444p|yuv410p
11506 Convert the video to specified constant frame rate by duplicating or dropping
11507 frames as necessary.
11509 It accepts the following parameters:
11513 The desired output frame rate. The default is @code{25}.
11516 Assume the first PTS should be the given value, in seconds. This allows for
11517 padding/trimming at the start of stream. By default, no assumption is made
11518 about the first frame's expected PTS, so no padding or trimming is done.
11519 For example, this could be set to 0 to pad the beginning with duplicates of
11520 the first frame if a video stream starts after the audio stream or to trim any
11521 frames with a negative PTS.
11524 Timestamp (PTS) rounding method.
11526 Possible values are:
11533 round towards -infinity
11535 round towards +infinity
11539 The default is @code{near}.
11542 Action performed when reading the last frame.
11544 Possible values are:
11547 Use same timestamp rounding method as used for other frames.
11549 Pass through last frame if input duration has not been reached yet.
11551 The default is @code{round}.
11555 Alternatively, the options can be specified as a flat string:
11556 @var{fps}[:@var{start_time}[:@var{round}]].
11558 See also the @ref{setpts} filter.
11560 @subsection Examples
11564 A typical usage in order to set the fps to 25:
11570 Sets the fps to 24, using abbreviation and rounding method to round to nearest:
11572 fps=fps=film:round=near
11578 Pack two different video streams into a stereoscopic video, setting proper
11579 metadata on supported codecs. The two views should have the same size and
11580 framerate and processing will stop when the shorter video ends. Please note
11581 that you may conveniently adjust view properties with the @ref{scale} and
11584 It accepts the following parameters:
11588 The desired packing format. Supported values are:
11593 The views are next to each other (default).
11596 The views are on top of each other.
11599 The views are packed by line.
11602 The views are packed by column.
11605 The views are temporally interleaved.
11614 # Convert left and right views into a frame-sequential video
11615 ffmpeg -i LEFT -i RIGHT -filter_complex framepack=frameseq OUTPUT
11617 # Convert views into a side-by-side video with the same output resolution as the input
11618 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
11623 Change the frame rate by interpolating new video output frames from the source
11626 This filter is not designed to function correctly with interlaced media. If
11627 you wish to change the frame rate of interlaced media then you are required
11628 to deinterlace before this filter and re-interlace after this filter.
11630 A description of the accepted options follows.
11634 Specify the output frames per second. This option can also be specified
11635 as a value alone. The default is @code{50}.
11638 Specify the start of a range where the output frame will be created as a
11639 linear interpolation of two frames. The range is [@code{0}-@code{255}],
11640 the default is @code{15}.
11643 Specify the end of a range where the output frame will be created as a
11644 linear interpolation of two frames. The range is [@code{0}-@code{255}],
11645 the default is @code{240}.
11648 Specify the level at which a scene change is detected as a value between
11649 0 and 100 to indicate a new scene; a low value reflects a low
11650 probability for the current frame to introduce a new scene, while a higher
11651 value means the current frame is more likely to be one.
11652 The default is @code{8.2}.
11655 Specify flags influencing the filter process.
11657 Available value for @var{flags} is:
11660 @item scene_change_detect, scd
11661 Enable scene change detection using the value of the option @var{scene}.
11662 This flag is enabled by default.
11668 Select one frame every N-th frame.
11670 This filter accepts the following option:
11673 Select frame after every @code{step} frames.
11674 Allowed values are positive integers higher than 0. Default value is @code{1}.
11677 @section freezedetect
11679 Detect frozen video.
11681 This filter logs a message and sets frame metadata when it detects that the
11682 input video has no significant change in content during a specified duration.
11683 Video freeze detection calculates the mean average absolute difference of all
11684 the components of video frames and compares it to a noise floor.
11686 The printed times and duration are expressed in seconds. The
11687 @code{lavfi.freezedetect.freeze_start} metadata key is set on the first frame
11688 whose timestamp equals or exceeds the detection duration and it contains the
11689 timestamp of the first frame of the freeze. The
11690 @code{lavfi.freezedetect.freeze_duration} and
11691 @code{lavfi.freezedetect.freeze_end} metadata keys are set on the first frame
11694 The filter accepts the following options:
11698 Set noise tolerance. Can be specified in dB (in case "dB" is appended to the
11699 specified value) or as a difference ratio between 0 and 1. Default is -60dB, or
11703 Set freeze duration until notification (default is 2 seconds).
11706 @section freezeframes
11708 Freeze video frames.
11710 This filter freezes video frames using frame from 2nd input.
11712 The filter accepts the following options:
11716 Set number of first frame from which to start freeze.
11719 Set number of last frame from which to end freeze.
11722 Set number of frame from 2nd input which will be used instead of replaced frames.
11728 Apply a frei0r effect to the input video.
11730 To enable the compilation of this filter, you need to install the frei0r
11731 header and configure FFmpeg with @code{--enable-frei0r}.
11733 It accepts the following parameters:
11738 The name of the frei0r effect to load. If the environment variable
11739 @env{FREI0R_PATH} is defined, the frei0r effect is searched for in each of the
11740 directories specified by the colon-separated list in @env{FREI0R_PATH}.
11741 Otherwise, the standard frei0r paths are searched, in this order:
11742 @file{HOME/.frei0r-1/lib/}, @file{/usr/local/lib/frei0r-1/},
11743 @file{/usr/lib/frei0r-1/}.
11745 @item filter_params
11746 A '|'-separated list of parameters to pass to the frei0r effect.
11750 A frei0r effect parameter can be a boolean (its value is either
11751 "y" or "n"), a double, a color (specified as
11752 @var{R}/@var{G}/@var{B}, where @var{R}, @var{G}, and @var{B} are floating point
11753 numbers between 0.0 and 1.0, inclusive) or a color description as specified in the
11754 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils},
11755 a position (specified as @var{X}/@var{Y}, where
11756 @var{X} and @var{Y} are floating point numbers) and/or a string.
11758 The number and types of parameters depend on the loaded effect. If an
11759 effect parameter is not specified, the default value is set.
11761 @subsection Examples
11765 Apply the distort0r effect, setting the first two double parameters:
11767 frei0r=filter_name=distort0r:filter_params=0.5|0.01
11771 Apply the colordistance effect, taking a color as the first parameter:
11773 frei0r=colordistance:0.2/0.3/0.4
11774 frei0r=colordistance:violet
11775 frei0r=colordistance:0x112233
11779 Apply the perspective effect, specifying the top left and top right image
11782 frei0r=perspective:0.2/0.2|0.8/0.2
11786 For more information, see
11787 @url{http://frei0r.dyne.org}
11789 @subsection Commands
11791 This filter supports the @option{filter_params} option as @ref{commands}.
11795 Apply fast and simple postprocessing. It is a faster version of @ref{spp}.
11797 It splits (I)DCT into horizontal/vertical passes. Unlike the simple post-
11798 processing filter, one of them is performed once per block, not per pixel.
11799 This allows for much higher speed.
11801 The filter accepts the following options:
11805 Set quality. This option defines the number of levels for averaging. It accepts
11806 an integer in the range 4-5. Default value is @code{4}.
11809 Force a constant quantization parameter. It accepts an integer in range 0-63.
11810 If not set, the filter will use the QP from the video stream (if available).
11813 Set filter strength. It accepts an integer in range -15 to 32. Lower values mean
11814 more details but also more artifacts, while higher values make the image smoother
11815 but also blurrier. Default value is @code{0} − PSNR optimal.
11817 @item use_bframe_qp
11818 Enable the use of the QP from the B-Frames if set to @code{1}. Using this
11819 option may cause flicker since the B-Frames have often larger QP. Default is
11820 @code{0} (not enabled).
11826 Apply Gaussian blur filter.
11828 The filter accepts the following options:
11832 Set horizontal sigma, standard deviation of Gaussian blur. Default is @code{0.5}.
11835 Set number of steps for Gaussian approximation. Default is @code{1}.
11838 Set which planes to filter. By default all planes are filtered.
11841 Set vertical sigma, if negative it will be same as @code{sigma}.
11842 Default is @code{-1}.
11845 @subsection Commands
11846 This filter supports same commands as options.
11847 The command accepts the same syntax of the corresponding option.
11849 If the specified expression is not valid, it is kept at its current
11854 Apply generic equation to each pixel.
11856 The filter accepts the following options:
11859 @item lum_expr, lum
11860 Set the luminance expression.
11862 Set the chrominance blue expression.
11864 Set the chrominance red expression.
11865 @item alpha_expr, a
11866 Set the alpha expression.
11868 Set the red expression.
11869 @item green_expr, g
11870 Set the green expression.
11872 Set the blue expression.
11875 The colorspace is selected according to the specified options. If one
11876 of the @option{lum_expr}, @option{cb_expr}, or @option{cr_expr}
11877 options is specified, the filter will automatically select a YCbCr
11878 colorspace. If one of the @option{red_expr}, @option{green_expr}, or
11879 @option{blue_expr} options is specified, it will select an RGB
11882 If one of the chrominance expression is not defined, it falls back on the other
11883 one. If no alpha expression is specified it will evaluate to opaque value.
11884 If none of chrominance expressions are specified, they will evaluate
11885 to the luminance expression.
11887 The expressions can use the following variables and functions:
11891 The sequential number of the filtered frame, starting from @code{0}.
11895 The coordinates of the current sample.
11899 The width and height of the image.
11903 Width and height scale depending on the currently filtered plane. It is the
11904 ratio between the corresponding luma plane number of pixels and the current
11905 plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and
11906 @code{0.5,0.5} for chroma planes.
11909 Time of the current frame, expressed in seconds.
11912 Return the value of the pixel at location (@var{x},@var{y}) of the current
11916 Return the value of the pixel at location (@var{x},@var{y}) of the luminance
11920 Return the value of the pixel at location (@var{x},@var{y}) of the
11921 blue-difference chroma plane. Return 0 if there is no such plane.
11924 Return the value of the pixel at location (@var{x},@var{y}) of the
11925 red-difference chroma plane. Return 0 if there is no such plane.
11930 Return the value of the pixel at location (@var{x},@var{y}) of the
11931 red/green/blue component. Return 0 if there is no such component.
11934 Return the value of the pixel at location (@var{x},@var{y}) of the alpha
11935 plane. Return 0 if there is no such plane.
11937 @item psum(x,y), lumsum(x, y), cbsum(x,y), crsum(x,y), rsum(x,y), gsum(x,y), bsum(x,y), alphasum(x,y)
11938 Sum of sample values in the rectangle from (0,0) to (x,y), this allows obtaining
11939 sums of samples within a rectangle. See the functions without the sum postfix.
11941 @item interpolation
11942 Set one of interpolation methods:
11947 Default is bilinear.
11950 For functions, if @var{x} and @var{y} are outside the area, the value will be
11951 automatically clipped to the closer edge.
11953 Please note that this filter can use multiple threads in which case each slice
11954 will have its own expression state. If you want to use only a single expression
11955 state because your expressions depend on previous state then you should limit
11956 the number of filter threads to 1.
11958 @subsection Examples
11962 Flip the image horizontally:
11968 Generate a bidimensional sine wave, with angle @code{PI/3} and a
11969 wavelength of 100 pixels:
11971 geq=128 + 100*sin(2*(PI/100)*(cos(PI/3)*(X-50*T) + sin(PI/3)*Y)):128:128
11975 Generate a fancy enigmatic moving light:
11977 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
11981 Generate a quick emboss effect:
11983 format=gray,geq=lum_expr='(p(X,Y)+(256-p(X-4,Y-4)))/2'
11987 Modify RGB components depending on pixel position:
11989 geq=r='X/W*r(X,Y)':g='(1-X/W)*g(X,Y)':b='(H-Y)/H*b(X,Y)'
11993 Create a radial gradient that is the same size as the input (also see
11994 the @ref{vignette} filter):
11996 geq=lum=255*gauss((X/W-0.5)*3)*gauss((Y/H-0.5)*3)/gauss(0)/gauss(0),format=gray
12002 Fix the banding artifacts that are sometimes introduced into nearly flat
12003 regions by truncation to 8-bit color depth.
12004 Interpolate the gradients that should go where the bands are, and
12007 It is designed for playback only. Do not use it prior to
12008 lossy compression, because compression tends to lose the dither and
12009 bring back the bands.
12011 It accepts the following parameters:
12016 The maximum amount by which the filter will change any one pixel. This is also
12017 the threshold for detecting nearly flat regions. Acceptable values range from
12018 .51 to 64; the default value is 1.2. Out-of-range values will be clipped to the
12022 The neighborhood to fit the gradient to. A larger radius makes for smoother
12023 gradients, but also prevents the filter from modifying the pixels near detailed
12024 regions. Acceptable values are 8-32; the default value is 16. Out-of-range
12025 values will be clipped to the valid range.
12029 Alternatively, the options can be specified as a flat string:
12030 @var{strength}[:@var{radius}]
12032 @subsection Examples
12036 Apply the filter with a @code{3.5} strength and radius of @code{8}:
12042 Specify radius, omitting the strength (which will fall-back to the default
12050 @anchor{graphmonitor}
12051 @section graphmonitor
12052 Show various filtergraph stats.
12054 With this filter one can debug complete filtergraph.
12055 Especially issues with links filling with queued frames.
12057 The filter accepts the following options:
12061 Set video output size. Default is @var{hd720}.
12064 Set video opacity. Default is @var{0.9}. Allowed range is from @var{0} to @var{1}.
12067 Set output mode, can be @var{fulll} or @var{compact}.
12068 In @var{compact} mode only filters with some queued frames have displayed stats.
12071 Set flags which enable which stats are shown in video.
12073 Available values for flags are:
12076 Display number of queued frames in each link.
12078 @item frame_count_in
12079 Display number of frames taken from filter.
12081 @item frame_count_out
12082 Display number of frames given out from filter.
12085 Display current filtered frame pts.
12088 Display current filtered frame time.
12091 Display time base for filter link.
12094 Display used format for filter link.
12097 Display video size or number of audio channels in case of audio used by filter link.
12100 Display video frame rate or sample rate in case of audio used by filter link.
12103 Display link output status.
12107 Set upper limit for video rate of output stream, Default value is @var{25}.
12108 This guarantee that output video frame rate will not be higher than this value.
12112 A color constancy variation filter which estimates scene illumination via grey edge algorithm
12113 and corrects the scene colors accordingly.
12115 See: @url{https://staff.science.uva.nl/th.gevers/pub/GeversTIP07.pdf}
12117 The filter accepts the following options:
12121 The order of differentiation to be applied on the scene. Must be chosen in the range
12122 [0,2] and default value is 1.
12125 The Minkowski parameter to be used for calculating the Minkowski distance. Must
12126 be chosen in the range [0,20] and default value is 1. Set to 0 for getting
12127 max value instead of calculating Minkowski distance.
12130 The standard deviation of Gaussian blur to be applied on the scene. Must be
12131 chosen in the range [0,1024.0] and default value = 1. floor( @var{sigma} * break_off_sigma(3) )
12132 can't be equal to 0 if @var{difford} is greater than 0.
12135 @subsection Examples
12141 greyedge=difford=1:minknorm=5:sigma=2
12147 greyedge=difford=1:minknorm=0:sigma=2
12155 Apply a Hald CLUT to a video stream.
12157 First input is the video stream to process, and second one is the Hald CLUT.
12158 The Hald CLUT input can be a simple picture or a complete video stream.
12160 The filter accepts the following options:
12164 Force termination when the shortest input terminates. Default is @code{0}.
12166 Continue applying the last CLUT after the end of the stream. A value of
12167 @code{0} disable the filter after the last frame of the CLUT is reached.
12168 Default is @code{1}.
12171 @code{haldclut} also has the same interpolation options as @ref{lut3d} (both
12172 filters share the same internals).
12174 This filter also supports the @ref{framesync} options.
12176 More information about the Hald CLUT can be found on Eskil Steenberg's website
12177 (Hald CLUT author) at @url{http://www.quelsolaar.com/technology/clut.html}.
12179 @subsection Workflow examples
12181 @subsubsection Hald CLUT video stream
12183 Generate an identity Hald CLUT stream altered with various effects:
12185 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
12188 Note: make sure you use a lossless codec.
12190 Then use it with @code{haldclut} to apply it on some random stream:
12192 ffmpeg -f lavfi -i mandelbrot -i clut.nut -filter_complex '[0][1] haldclut' -t 20 mandelclut.mkv
12195 The Hald CLUT will be applied to the 10 first seconds (duration of
12196 @file{clut.nut}), then the latest picture of that CLUT stream will be applied
12197 to the remaining frames of the @code{mandelbrot} stream.
12199 @subsubsection Hald CLUT with preview
12201 A Hald CLUT is supposed to be a squared image of @code{Level*Level*Level} by
12202 @code{Level*Level*Level} pixels. For a given Hald CLUT, FFmpeg will select the
12203 biggest possible square starting at the top left of the picture. The remaining
12204 padding pixels (bottom or right) will be ignored. This area can be used to add
12205 a preview of the Hald CLUT.
12207 Typically, the following generated Hald CLUT will be supported by the
12208 @code{haldclut} filter:
12211 ffmpeg -f lavfi -i @ref{haldclutsrc}=8 -vf "
12212 pad=iw+320 [padded_clut];
12213 smptebars=s=320x256, split [a][b];
12214 [padded_clut][a] overlay=W-320:h, curves=color_negative [main];
12215 [main][b] overlay=W-320" -frames:v 1 clut.png
12218 It contains the original and a preview of the effect of the CLUT: SMPTE color
12219 bars are displayed on the right-top, and below the same color bars processed by
12222 Then, the effect of this Hald CLUT can be visualized with:
12224 ffplay input.mkv -vf "movie=clut.png, [in] haldclut"
12229 Flip the input video horizontally.
12231 For example, to horizontally flip the input video with @command{ffmpeg}:
12233 ffmpeg -i in.avi -vf "hflip" out.avi
12237 This filter applies a global color histogram equalization on a
12240 It can be used to correct video that has a compressed range of pixel
12241 intensities. The filter redistributes the pixel intensities to
12242 equalize their distribution across the intensity range. It may be
12243 viewed as an "automatically adjusting contrast filter". This filter is
12244 useful only for correcting degraded or poorly captured source
12247 The filter accepts the following options:
12251 Determine the amount of equalization to be applied. As the strength
12252 is reduced, the distribution of pixel intensities more-and-more
12253 approaches that of the input frame. The value must be a float number
12254 in the range [0,1] and defaults to 0.200.
12257 Set the maximum intensity that can generated and scale the output
12258 values appropriately. The strength should be set as desired and then
12259 the intensity can be limited if needed to avoid washing-out. The value
12260 must be a float number in the range [0,1] and defaults to 0.210.
12263 Set the antibanding level. If enabled the filter will randomly vary
12264 the luminance of output pixels by a small amount to avoid banding of
12265 the histogram. Possible values are @code{none}, @code{weak} or
12266 @code{strong}. It defaults to @code{none}.
12272 Compute and draw a color distribution histogram for the input video.
12274 The computed histogram is a representation of the color component
12275 distribution in an image.
12277 Standard histogram displays the color components distribution in an image.
12278 Displays color graph for each color component. Shows distribution of
12279 the Y, U, V, A or R, G, B components, depending on input format, in the
12280 current frame. Below each graph a color component scale meter is shown.
12282 The filter accepts the following options:
12286 Set height of level. Default value is @code{200}.
12287 Allowed range is [50, 2048].
12290 Set height of color scale. Default value is @code{12}.
12291 Allowed range is [0, 40].
12295 It accepts the following values:
12298 Per color component graphs are placed below each other.
12301 Per color component graphs are placed side by side.
12304 Presents information identical to that in the @code{parade}, except
12305 that the graphs representing color components are superimposed directly
12308 Default is @code{stack}.
12311 Set mode. Can be either @code{linear}, or @code{logarithmic}.
12312 Default is @code{linear}.
12315 Set what color components to display.
12316 Default is @code{7}.
12319 Set foreground opacity. Default is @code{0.7}.
12322 Set background opacity. Default is @code{0.5}.
12325 @subsection Examples
12330 Calculate and draw histogram:
12332 ffplay -i input -vf histogram
12340 This is a high precision/quality 3d denoise filter. It aims to reduce
12341 image noise, producing smooth images and making still images really
12342 still. It should enhance compressibility.
12344 It accepts the following optional parameters:
12348 A non-negative floating point number which specifies spatial luma strength.
12349 It defaults to 4.0.
12351 @item chroma_spatial
12352 A non-negative floating point number which specifies spatial chroma strength.
12353 It defaults to 3.0*@var{luma_spatial}/4.0.
12356 A floating point number which specifies luma temporal strength. It defaults to
12357 6.0*@var{luma_spatial}/4.0.
12360 A floating point number which specifies chroma temporal strength. It defaults to
12361 @var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}.
12364 @subsection Commands
12365 This filter supports same @ref{commands} as options.
12366 The command accepts the same syntax of the corresponding option.
12368 If the specified expression is not valid, it is kept at its current
12371 @anchor{hwdownload}
12372 @section hwdownload
12374 Download hardware frames to system memory.
12376 The input must be in hardware frames, and the output a non-hardware format.
12377 Not all formats will be supported on the output - it may be necessary to insert
12378 an additional @option{format} filter immediately following in the graph to get
12379 the output in a supported format.
12383 Map hardware frames to system memory or to another device.
12385 This filter has several different modes of operation; which one is used depends
12386 on the input and output formats:
12389 Hardware frame input, normal frame output
12391 Map the input frames to system memory and pass them to the output. If the
12392 original hardware frame is later required (for example, after overlaying
12393 something else on part of it), the @option{hwmap} filter can be used again
12394 in the next mode to retrieve it.
12396 Normal frame input, hardware frame output
12398 If the input is actually a software-mapped hardware frame, then unmap it -
12399 that is, return the original hardware frame.
12401 Otherwise, a device must be provided. Create new hardware surfaces on that
12402 device for the output, then map them back to the software format at the input
12403 and give those frames to the preceding filter. This will then act like the
12404 @option{hwupload} filter, but may be able to avoid an additional copy when
12405 the input is already in a compatible format.
12407 Hardware frame input and output
12409 A device must be supplied for the output, either directly or with the
12410 @option{derive_device} option. The input and output devices must be of
12411 different types and compatible - the exact meaning of this is
12412 system-dependent, but typically it means that they must refer to the same
12413 underlying hardware context (for example, refer to the same graphics card).
12415 If the input frames were originally created on the output device, then unmap
12416 to retrieve the original frames.
12418 Otherwise, map the frames to the output device - create new hardware frames
12419 on the output corresponding to the frames on the input.
12422 The following additional parameters are accepted:
12426 Set the frame mapping mode. Some combination of:
12429 The mapped frame should be readable.
12431 The mapped frame should be writeable.
12433 The mapping will always overwrite the entire frame.
12435 This may improve performance in some cases, as the original contents of the
12436 frame need not be loaded.
12438 The mapping must not involve any copying.
12440 Indirect mappings to copies of frames are created in some cases where either
12441 direct mapping is not possible or it would have unexpected properties.
12442 Setting this flag ensures that the mapping is direct and will fail if that is
12445 Defaults to @var{read+write} if not specified.
12447 @item derive_device @var{type}
12448 Rather than using the device supplied at initialisation, instead derive a new
12449 device of type @var{type} from the device the input frames exist on.
12452 In a hardware to hardware mapping, map in reverse - create frames in the sink
12453 and map them back to the source. This may be necessary in some cases where
12454 a mapping in one direction is required but only the opposite direction is
12455 supported by the devices being used.
12457 This option is dangerous - it may break the preceding filter in undefined
12458 ways if there are any additional constraints on that filter's output.
12459 Do not use it without fully understanding the implications of its use.
12465 Upload system memory frames to hardware surfaces.
12467 The device to upload to must be supplied when the filter is initialised. If
12468 using ffmpeg, select the appropriate device with the @option{-filter_hw_device}
12469 option or with the @option{derive_device} option. The input and output devices
12470 must be of different types and compatible - the exact meaning of this is
12471 system-dependent, but typically it means that they must refer to the same
12472 underlying hardware context (for example, refer to the same graphics card).
12474 The following additional parameters are accepted:
12477 @item derive_device @var{type}
12478 Rather than using the device supplied at initialisation, instead derive a new
12479 device of type @var{type} from the device the input frames exist on.
12482 @anchor{hwupload_cuda}
12483 @section hwupload_cuda
12485 Upload system memory frames to a CUDA device.
12487 It accepts the following optional parameters:
12491 The number of the CUDA device to use
12496 Apply a high-quality magnification filter designed for pixel art. This filter
12497 was originally created by Maxim Stepin.
12499 It accepts the following option:
12503 Set the scaling dimension: @code{2} for @code{hq2x}, @code{3} for
12504 @code{hq3x} and @code{4} for @code{hq4x}.
12505 Default is @code{3}.
12509 Stack input videos horizontally.
12511 All streams must be of same pixel format and of same height.
12513 Note that this filter is faster than using @ref{overlay} and @ref{pad} filter
12514 to create same output.
12516 The filter accepts the following option:
12520 Set number of input streams. Default is 2.
12523 If set to 1, force the output to terminate when the shortest input
12524 terminates. Default value is 0.
12529 Modify the hue and/or the saturation of the input.
12531 It accepts the following parameters:
12535 Specify the hue angle as a number of degrees. It accepts an expression,
12536 and defaults to "0".
12539 Specify the saturation in the [-10,10] range. It accepts an expression and
12543 Specify the hue angle as a number of radians. It accepts an
12544 expression, and defaults to "0".
12547 Specify the brightness in the [-10,10] range. It accepts an expression and
12551 @option{h} and @option{H} are mutually exclusive, and can't be
12552 specified at the same time.
12554 The @option{b}, @option{h}, @option{H} and @option{s} option values are
12555 expressions containing the following constants:
12559 frame count of the input frame starting from 0
12562 presentation timestamp of the input frame expressed in time base units
12565 frame rate of the input video, NAN if the input frame rate is unknown
12568 timestamp expressed in seconds, NAN if the input timestamp is unknown
12571 time base of the input video
12574 @subsection Examples
12578 Set the hue to 90 degrees and the saturation to 1.0:
12584 Same command but expressing the hue in radians:
12590 Rotate hue and make the saturation swing between 0
12591 and 2 over a period of 1 second:
12593 hue="H=2*PI*t: s=sin(2*PI*t)+1"
12597 Apply a 3 seconds saturation fade-in effect starting at 0:
12599 hue="s=min(t/3\,1)"
12602 The general fade-in expression can be written as:
12604 hue="s=min(0\, max((t-START)/DURATION\, 1))"
12608 Apply a 3 seconds saturation fade-out effect starting at 5 seconds:
12610 hue="s=max(0\, min(1\, (8-t)/3))"
12613 The general fade-out expression can be written as:
12615 hue="s=max(0\, min(1\, (START+DURATION-t)/DURATION))"
12620 @subsection Commands
12622 This filter supports the following commands:
12628 Modify the hue and/or the saturation and/or brightness of the input video.
12629 The command accepts the same syntax of the corresponding option.
12631 If the specified expression is not valid, it is kept at its current
12635 @section hysteresis
12637 Grow first stream into second stream by connecting components.
12638 This makes it possible to build more robust edge masks.
12640 This filter accepts the following options:
12644 Set which planes will be processed as bitmap, unprocessed planes will be
12645 copied from first stream.
12646 By default value 0xf, all planes will be processed.
12649 Set threshold which is used in filtering. If pixel component value is higher than
12650 this value filter algorithm for connecting components is activated.
12651 By default value is 0.
12654 The @code{hysteresis} filter also supports the @ref{framesync} options.
12658 Detect video interlacing type.
12660 This filter tries to detect if the input frames are interlaced, progressive,
12661 top or bottom field first. It will also try to detect fields that are
12662 repeated between adjacent frames (a sign of telecine).
12664 Single frame detection considers only immediately adjacent frames when classifying each frame.
12665 Multiple frame detection incorporates the classification history of previous frames.
12667 The filter will log these metadata values:
12670 @item single.current_frame
12671 Detected type of current frame using single-frame detection. One of:
12672 ``tff'' (top field first), ``bff'' (bottom field first),
12673 ``progressive'', or ``undetermined''
12676 Cumulative number of frames detected as top field first using single-frame detection.
12679 Cumulative number of frames detected as top field first using multiple-frame detection.
12682 Cumulative number of frames detected as bottom field first using single-frame detection.
12684 @item multiple.current_frame
12685 Detected type of current frame using multiple-frame detection. One of:
12686 ``tff'' (top field first), ``bff'' (bottom field first),
12687 ``progressive'', or ``undetermined''
12690 Cumulative number of frames detected as bottom field first using multiple-frame detection.
12692 @item single.progressive
12693 Cumulative number of frames detected as progressive using single-frame detection.
12695 @item multiple.progressive
12696 Cumulative number of frames detected as progressive using multiple-frame detection.
12698 @item single.undetermined
12699 Cumulative number of frames that could not be classified using single-frame detection.
12701 @item multiple.undetermined
12702 Cumulative number of frames that could not be classified using multiple-frame detection.
12704 @item repeated.current_frame
12705 Which field in the current frame is repeated from the last. One of ``neither'', ``top'', or ``bottom''.
12707 @item repeated.neither
12708 Cumulative number of frames with no repeated field.
12711 Cumulative number of frames with the top field repeated from the previous frame's top field.
12713 @item repeated.bottom
12714 Cumulative number of frames with the bottom field repeated from the previous frame's bottom field.
12717 The filter accepts the following options:
12721 Set interlacing threshold.
12723 Set progressive threshold.
12725 Threshold for repeated field detection.
12727 Number of frames after which a given frame's contribution to the
12728 statistics is halved (i.e., it contributes only 0.5 to its
12729 classification). The default of 0 means that all frames seen are given
12730 full weight of 1.0 forever.
12731 @item analyze_interlaced_flag
12732 When this is not 0 then idet will use the specified number of frames to determine
12733 if the interlaced flag is accurate, it will not count undetermined frames.
12734 If the flag is found to be accurate it will be used without any further
12735 computations, if it is found to be inaccurate it will be cleared without any
12736 further computations. This allows inserting the idet filter as a low computational
12737 method to clean up the interlaced flag
12742 Deinterleave or interleave fields.
12744 This filter allows one to process interlaced images fields without
12745 deinterlacing them. Deinterleaving splits the input frame into 2
12746 fields (so called half pictures). Odd lines are moved to the top
12747 half of the output image, even lines to the bottom half.
12748 You can process (filter) them independently and then re-interleave them.
12750 The filter accepts the following options:
12754 @item chroma_mode, c
12755 @item alpha_mode, a
12756 Available values for @var{luma_mode}, @var{chroma_mode} and
12757 @var{alpha_mode} are:
12763 @item deinterleave, d
12764 Deinterleave fields, placing one above the other.
12766 @item interleave, i
12767 Interleave fields. Reverse the effect of deinterleaving.
12769 Default value is @code{none}.
12771 @item luma_swap, ls
12772 @item chroma_swap, cs
12773 @item alpha_swap, as
12774 Swap luma/chroma/alpha fields. Exchange even & odd lines. Default value is @code{0}.
12777 @subsection Commands
12779 This filter supports the all above options as @ref{commands}.
12783 Apply inflate effect to the video.
12785 This filter replaces the pixel by the local(3x3) average by taking into account
12786 only values higher than the pixel.
12788 It accepts the following options:
12795 Limit the maximum change for each plane, default is 65535.
12796 If 0, plane will remain unchanged.
12799 @subsection Commands
12801 This filter supports the all above options as @ref{commands}.
12805 Simple interlacing filter from progressive contents. This interleaves upper (or
12806 lower) lines from odd frames with lower (or upper) lines from even frames,
12807 halving the frame rate and preserving image height.
12810 Original Original New Frame
12811 Frame 'j' Frame 'j+1' (tff)
12812 ========== =========== ==================
12813 Line 0 --------------------> Frame 'j' Line 0
12814 Line 1 Line 1 ----> Frame 'j+1' Line 1
12815 Line 2 ---------------------> Frame 'j' Line 2
12816 Line 3 Line 3 ----> Frame 'j+1' Line 3
12818 New Frame + 1 will be generated by Frame 'j+2' and Frame 'j+3' and so on
12821 It accepts the following optional parameters:
12825 This determines whether the interlaced frame is taken from the even
12826 (tff - default) or odd (bff) lines of the progressive frame.
12829 Vertical lowpass filter to avoid twitter interlacing and
12830 reduce moire patterns.
12834 Disable vertical lowpass filter
12837 Enable linear filter (default)
12840 Enable complex filter. This will slightly less reduce twitter and moire
12841 but better retain detail and subjective sharpness impression.
12848 Deinterlace input video by applying Donald Graft's adaptive kernel
12849 deinterling. Work on interlaced parts of a video to produce
12850 progressive frames.
12852 The description of the accepted parameters follows.
12856 Set the threshold which affects the filter's tolerance when
12857 determining if a pixel line must be processed. It must be an integer
12858 in the range [0,255] and defaults to 10. A value of 0 will result in
12859 applying the process on every pixels.
12862 Paint pixels exceeding the threshold value to white if set to 1.
12866 Set the fields order. Swap fields if set to 1, leave fields alone if
12870 Enable additional sharpening if set to 1. Default is 0.
12873 Enable twoway sharpening if set to 1. Default is 0.
12876 @subsection Examples
12880 Apply default values:
12882 kerndeint=thresh=10:map=0:order=0:sharp=0:twoway=0
12886 Enable additional sharpening:
12892 Paint processed pixels in white:
12900 Slowly update darker pixels.
12902 This filter makes short flashes of light appear longer.
12903 This filter accepts the following options:
12907 Set factor for decaying. Default is .95. Allowed range is from 0 to 1.
12910 Set which planes to filter. Default is all. Allowed range is from 0 to 15.
12913 @section lenscorrection
12915 Correct radial lens distortion
12917 This filter can be used to correct for radial distortion as can result from the use
12918 of wide angle lenses, and thereby re-rectify the image. To find the right parameters
12919 one can use tools available for example as part of opencv or simply trial-and-error.
12920 To use opencv use the calibration sample (under samples/cpp) from the opencv sources
12921 and extract the k1 and k2 coefficients from the resulting matrix.
12923 Note that effectively the same filter is available in the open-source tools Krita and
12924 Digikam from the KDE project.
12926 In contrast to the @ref{vignette} filter, which can also be used to compensate lens errors,
12927 this filter corrects the distortion of the image, whereas @ref{vignette} corrects the
12928 brightness distribution, so you may want to use both filters together in certain
12929 cases, though you will have to take care of ordering, i.e. whether vignetting should
12930 be applied before or after lens correction.
12932 @subsection Options
12934 The filter accepts the following options:
12938 Relative x-coordinate of the focal point of the image, and thereby the center of the
12939 distortion. This value has a range [0,1] and is expressed as fractions of the image
12940 width. Default is 0.5.
12942 Relative y-coordinate of the focal point of the image, and thereby the center of the
12943 distortion. This value has a range [0,1] and is expressed as fractions of the image
12944 height. Default is 0.5.
12946 Coefficient of the quadratic correction term. This value has a range [-1,1]. 0 means
12947 no correction. Default is 0.
12949 Coefficient of the double quadratic correction term. This value has a range [-1,1].
12950 0 means no correction. Default is 0.
12953 The formula that generates the correction is:
12955 @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)
12957 where @var{r_0} is halve of the image diagonal and @var{r_src} and @var{r_tgt} are the
12958 distances from the focal point in the source and target images, respectively.
12962 Apply lens correction via the lensfun library (@url{http://lensfun.sourceforge.net/}).
12964 The @code{lensfun} filter requires the camera make, camera model, and lens model
12965 to apply the lens correction. The filter will load the lensfun database and
12966 query it to find the corresponding camera and lens entries in the database. As
12967 long as these entries can be found with the given options, the filter can
12968 perform corrections on frames. Note that incomplete strings will result in the
12969 filter choosing the best match with the given options, and the filter will
12970 output the chosen camera and lens models (logged with level "info"). You must
12971 provide the make, camera model, and lens model as they are required.
12973 The filter accepts the following options:
12977 The make of the camera (for example, "Canon"). This option is required.
12980 The model of the camera (for example, "Canon EOS 100D"). This option is
12984 The model of the lens (for example, "Canon EF-S 18-55mm f/3.5-5.6 IS STM"). This
12985 option is required.
12988 The type of correction to apply. The following values are valid options:
12992 Enables fixing lens vignetting.
12995 Enables fixing lens geometry. This is the default.
12998 Enables fixing chromatic aberrations.
13001 Enables fixing lens vignetting and lens geometry.
13004 Enables fixing lens vignetting and chromatic aberrations.
13007 Enables fixing both lens geometry and chromatic aberrations.
13010 Enables all possible corrections.
13014 The focal length of the image/video (zoom; expected constant for video). For
13015 example, a 18--55mm lens has focal length range of [18--55], so a value in that
13016 range should be chosen when using that lens. Default 18.
13019 The aperture of the image/video (expected constant for video). Note that
13020 aperture is only used for vignetting correction. Default 3.5.
13022 @item focus_distance
13023 The focus distance of the image/video (expected constant for video). Note that
13024 focus distance is only used for vignetting and only slightly affects the
13025 vignetting correction process. If unknown, leave it at the default value (which
13029 The scale factor which is applied after transformation. After correction the
13030 video is no longer necessarily rectangular. This parameter controls how much of
13031 the resulting image is visible. The value 0 means that a value will be chosen
13032 automatically such that there is little or no unmapped area in the output
13033 image. 1.0 means that no additional scaling is done. Lower values may result
13034 in more of the corrected image being visible, while higher values may avoid
13035 unmapped areas in the output.
13037 @item target_geometry
13038 The target geometry of the output image/video. The following values are valid
13042 @item rectilinear (default)
13045 @item equirectangular
13046 @item fisheye_orthographic
13047 @item fisheye_stereographic
13048 @item fisheye_equisolid
13049 @item fisheye_thoby
13052 Apply the reverse of image correction (instead of correcting distortion, apply
13055 @item interpolation
13056 The type of interpolation used when correcting distortion. The following values
13061 @item linear (default)
13066 @subsection Examples
13070 Apply lens correction with make "Canon", camera model "Canon EOS 100D", and lens
13071 model "Canon EF-S 18-55mm f/3.5-5.6 IS STM" with focal length of "18" and
13075 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
13079 Apply the same as before, but only for the first 5 seconds of video.
13082 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
13089 Obtain the VMAF (Video Multi-Method Assessment Fusion)
13090 score between two input videos.
13092 The obtained VMAF score is printed through the logging system.
13094 It requires Netflix's vmaf library (libvmaf) as a pre-requisite.
13095 After installing the library it can be enabled using:
13096 @code{./configure --enable-libvmaf}.
13097 If no model path is specified it uses the default model: @code{vmaf_v0.6.1.pkl}.
13099 The filter has following options:
13103 Set the model path which is to be used for SVM.
13104 Default value: @code{"/usr/local/share/model/vmaf_v0.6.1.pkl"}
13107 Set the file path to be used to store logs.
13110 Set the format of the log file (csv, json or xml).
13112 @item enable_transform
13113 This option can enable/disable the @code{score_transform} applied to the final predicted VMAF score,
13114 if you have specified score_transform option in the input parameter file passed to @code{run_vmaf_training.py}
13115 Default value: @code{false}
13118 Invokes the phone model which will generate VMAF scores higher than in the
13119 regular model, which is more suitable for laptop, TV, etc. viewing conditions.
13120 Default value: @code{false}
13123 Enables computing psnr along with vmaf.
13124 Default value: @code{false}
13127 Enables computing ssim along with vmaf.
13128 Default value: @code{false}
13131 Enables computing ms_ssim along with vmaf.
13132 Default value: @code{false}
13135 Set the pool method to be used for computing vmaf.
13136 Options are @code{min}, @code{harmonic_mean} or @code{mean} (default).
13139 Set number of threads to be used when computing vmaf.
13140 Default value: @code{0}, which makes use of all available logical processors.
13143 Set interval for frame subsampling used when computing vmaf.
13144 Default value: @code{1}
13146 @item enable_conf_interval
13147 Enables confidence interval.
13148 Default value: @code{false}
13151 This filter also supports the @ref{framesync} options.
13153 @subsection Examples
13156 On the below examples the input file @file{main.mpg} being processed is
13157 compared with the reference file @file{ref.mpg}.
13160 ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf -f null -
13164 Example with options:
13166 ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf="psnr=1:log_fmt=json" -f null -
13170 Example with options and different containers:
13172 ffmpeg -i main.mpg -i ref.mkv -lavfi "[0:v]settb=AVTB,setpts=PTS-STARTPTS[main];[1:v]settb=AVTB,setpts=PTS-STARTPTS[ref];[main][ref]libvmaf=psnr=1:log_fmt=json" -f null -
13178 Limits the pixel components values to the specified range [min, max].
13180 The filter accepts the following options:
13184 Lower bound. Defaults to the lowest allowed value for the input.
13187 Upper bound. Defaults to the highest allowed value for the input.
13190 Specify which planes will be processed. Defaults to all available.
13197 The filter accepts the following options:
13201 Set the number of loops. Setting this value to -1 will result in infinite loops.
13205 Set maximal size in number of frames. Default is 0.
13208 Set first frame of loop. Default is 0.
13211 @subsection Examples
13215 Loop single first frame infinitely:
13217 loop=loop=-1:size=1:start=0
13221 Loop single first frame 10 times:
13223 loop=loop=10:size=1:start=0
13227 Loop 10 first frames 5 times:
13229 loop=loop=5:size=10:start=0
13235 Apply a 1D LUT to an input video.
13237 The filter accepts the following options:
13241 Set the 1D LUT file name.
13243 Currently supported formats:
13252 Select interpolation mode.
13254 Available values are:
13258 Use values from the nearest defined point.
13260 Interpolate values using the linear interpolation.
13262 Interpolate values using the cosine interpolation.
13264 Interpolate values using the cubic interpolation.
13266 Interpolate values using the spline interpolation.
13273 Apply a 3D LUT to an input video.
13275 The filter accepts the following options:
13279 Set the 3D LUT file name.
13281 Currently supported formats:
13295 Select interpolation mode.
13297 Available values are:
13301 Use values from the nearest defined point.
13303 Interpolate values using the 8 points defining a cube.
13305 Interpolate values using a tetrahedron.
13311 Turn certain luma values into transparency.
13313 The filter accepts the following options:
13317 Set the luma which will be used as base for transparency.
13318 Default value is @code{0}.
13321 Set the range of luma values to be keyed out.
13322 Default value is @code{0.01}.
13325 Set the range of softness. Default value is @code{0}.
13326 Use this to control gradual transition from zero to full transparency.
13329 @subsection Commands
13330 This filter supports same @ref{commands} as options.
13331 The command accepts the same syntax of the corresponding option.
13333 If the specified expression is not valid, it is kept at its current
13336 @section lut, lutrgb, lutyuv
13338 Compute a look-up table for binding each pixel component input value
13339 to an output value, and apply it to the input video.
13341 @var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb}
13342 to an RGB input video.
13344 These filters accept the following parameters:
13347 set first pixel component expression
13349 set second pixel component expression
13351 set third pixel component expression
13353 set fourth pixel component expression, corresponds to the alpha component
13356 set red component expression
13358 set green component expression
13360 set blue component expression
13362 alpha component expression
13365 set Y/luminance component expression
13367 set U/Cb component expression
13369 set V/Cr component expression
13372 Each of them specifies the expression to use for computing the lookup table for
13373 the corresponding pixel component values.
13375 The exact component associated to each of the @var{c*} options depends on the
13378 The @var{lut} filter requires either YUV or RGB pixel formats in input,
13379 @var{lutrgb} requires RGB pixel formats in input, and @var{lutyuv} requires YUV.
13381 The expressions can contain the following constants and functions:
13386 The input width and height.
13389 The input value for the pixel component.
13392 The input value, clipped to the @var{minval}-@var{maxval} range.
13395 The maximum value for the pixel component.
13398 The minimum value for the pixel component.
13401 The negated value for the pixel component value, clipped to the
13402 @var{minval}-@var{maxval} range; it corresponds to the expression
13403 "maxval-clipval+minval".
13406 The computed value in @var{val}, clipped to the
13407 @var{minval}-@var{maxval} range.
13409 @item gammaval(gamma)
13410 The computed gamma correction value of the pixel component value,
13411 clipped to the @var{minval}-@var{maxval} range. It corresponds to the
13413 "pow((clipval-minval)/(maxval-minval)\,@var{gamma})*(maxval-minval)+minval"
13417 All expressions default to "val".
13419 @subsection Examples
13423 Negate input video:
13425 lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val"
13426 lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val"
13429 The above is the same as:
13431 lutrgb="r=negval:g=negval:b=negval"
13432 lutyuv="y=negval:u=negval:v=negval"
13442 Remove chroma components, turning the video into a graytone image:
13444 lutyuv="u=128:v=128"
13448 Apply a luma burning effect:
13454 Remove green and blue components:
13460 Set a constant alpha channel value on input:
13462 format=rgba,lutrgb=a="maxval-minval/2"
13466 Correct luminance gamma by a factor of 0.5:
13468 lutyuv=y=gammaval(0.5)
13472 Discard least significant bits of luma:
13474 lutyuv=y='bitand(val, 128+64+32)'
13478 Technicolor like effect:
13480 lutyuv=u='(val-maxval/2)*2+maxval/2':v='(val-maxval/2)*2+maxval/2'
13484 @section lut2, tlut2
13486 The @code{lut2} filter takes two input streams and outputs one
13489 The @code{tlut2} (time lut2) filter takes two consecutive frames
13490 from one single stream.
13492 This filter accepts the following parameters:
13495 set first pixel component expression
13497 set second pixel component expression
13499 set third pixel component expression
13501 set fourth pixel component expression, corresponds to the alpha component
13504 set output bit depth, only available for @code{lut2} filter. By default is 0,
13505 which means bit depth is automatically picked from first input format.
13508 The @code{lut2} filter also supports the @ref{framesync} options.
13510 Each of them specifies the expression to use for computing the lookup table for
13511 the corresponding pixel component values.
13513 The exact component associated to each of the @var{c*} options depends on the
13516 The expressions can contain the following constants:
13521 The input width and height.
13524 The first input value for the pixel component.
13527 The second input value for the pixel component.
13530 The first input video bit depth.
13533 The second input video bit depth.
13536 All expressions default to "x".
13538 @subsection Examples
13542 Highlight differences between two RGB video streams:
13544 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)'
13548 Highlight differences between two YUV video streams:
13550 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)'
13554 Show max difference between two video streams:
13556 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)))'
13560 @section maskedclamp
13562 Clamp the first input stream with the second input and third input stream.
13564 Returns the value of first stream to be between second input
13565 stream - @code{undershoot} and third input stream + @code{overshoot}.
13567 This filter accepts the following options:
13570 Default value is @code{0}.
13573 Default value is @code{0}.
13576 Set which planes will be processed as bitmap, unprocessed planes will be
13577 copied from first stream.
13578 By default value 0xf, all planes will be processed.
13583 Merge the second and third input stream into output stream using absolute differences
13584 between second input stream and first input stream and absolute difference between
13585 third input stream and first input stream. The picked value will be from second input
13586 stream if second absolute difference is greater than first one or from third input stream
13589 This filter accepts the following options:
13592 Set which planes will be processed as bitmap, unprocessed planes will be
13593 copied from first stream.
13594 By default value 0xf, all planes will be processed.
13597 @section maskedmerge
13599 Merge the first input stream with the second input stream using per pixel
13600 weights in the third input stream.
13602 A value of 0 in the third stream pixel component means that pixel component
13603 from first stream is returned unchanged, while maximum value (eg. 255 for
13604 8-bit videos) means that pixel component from second stream is returned
13605 unchanged. Intermediate values define the amount of merging between both
13606 input stream's pixel components.
13608 This filter accepts the following options:
13611 Set which planes will be processed as bitmap, unprocessed planes will be
13612 copied from first stream.
13613 By default value 0xf, all planes will be processed.
13618 Merge the second and third input stream into output stream using absolute differences
13619 between second input stream and first input stream and absolute difference between
13620 third input stream and first input stream. The picked value will be from second input
13621 stream if second absolute difference is less than first one or from third input stream
13624 This filter accepts the following options:
13627 Set which planes will be processed as bitmap, unprocessed planes will be
13628 copied from first stream.
13629 By default value 0xf, all planes will be processed.
13632 @section maskedthreshold
13633 Pick pixels comparing absolute difference of two video streams with fixed
13636 If absolute difference between pixel component of first and second video
13637 stream is equal or lower than user supplied threshold than pixel component
13638 from first video stream is picked, otherwise pixel component from second
13639 video stream is picked.
13641 This filter accepts the following options:
13644 Set threshold used when picking pixels from absolute difference from two input
13648 Set which planes will be processed as bitmap, unprocessed planes will be
13649 copied from second stream.
13650 By default value 0xf, all planes will be processed.
13654 Create mask from input video.
13656 For example it is useful to create motion masks after @code{tblend} filter.
13658 This filter accepts the following options:
13662 Set low threshold. Any pixel component lower or exact than this value will be set to 0.
13665 Set high threshold. Any pixel component higher than this value will be set to max value
13666 allowed for current pixel format.
13669 Set planes to filter, by default all available planes are filtered.
13672 Fill all frame pixels with this value.
13675 Set max average pixel value for frame. If sum of all pixel components is higher that this
13676 average, output frame will be completely filled with value set by @var{fill} option.
13677 Typically useful for scene changes when used in combination with @code{tblend} filter.
13682 Apply motion-compensation deinterlacing.
13684 It needs one field per frame as input and must thus be used together
13685 with yadif=1/3 or equivalent.
13687 This filter accepts the following options:
13690 Set the deinterlacing mode.
13692 It accepts one of the following values:
13697 use iterative motion estimation
13699 like @samp{slow}, but use multiple reference frames.
13701 Default value is @samp{fast}.
13704 Set the picture field parity assumed for the input video. It must be
13705 one of the following values:
13709 assume top field first
13711 assume bottom field first
13714 Default value is @samp{bff}.
13717 Set per-block quantization parameter (QP) used by the internal
13720 Higher values should result in a smoother motion vector field but less
13721 optimal individual vectors. Default value is 1.
13726 Pick median pixel from certain rectangle defined by radius.
13728 This filter accepts the following options:
13732 Set horizontal radius size. Default value is @code{1}.
13733 Allowed range is integer from 1 to 127.
13736 Set which planes to process. Default is @code{15}, which is all available planes.
13739 Set vertical radius size. Default value is @code{0}.
13740 Allowed range is integer from 0 to 127.
13741 If it is 0, value will be picked from horizontal @code{radius} option.
13744 Set median percentile. Default value is @code{0.5}.
13745 Default value of @code{0.5} will pick always median values, while @code{0} will pick
13746 minimum values, and @code{1} maximum values.
13749 @subsection Commands
13750 This filter supports same @ref{commands} as options.
13751 The command accepts the same syntax of the corresponding option.
13753 If the specified expression is not valid, it is kept at its current
13756 @section mergeplanes
13758 Merge color channel components from several video streams.
13760 The filter accepts up to 4 input streams, and merge selected input
13761 planes to the output video.
13763 This filter accepts the following options:
13766 Set input to output plane mapping. Default is @code{0}.
13768 The mappings is specified as a bitmap. It should be specified as a
13769 hexadecimal number in the form 0xAa[Bb[Cc[Dd]]]. 'Aa' describes the
13770 mapping for the first plane of the output stream. 'A' sets the number of
13771 the input stream to use (from 0 to 3), and 'a' the plane number of the
13772 corresponding input to use (from 0 to 3). The rest of the mappings is
13773 similar, 'Bb' describes the mapping for the output stream second
13774 plane, 'Cc' describes the mapping for the output stream third plane and
13775 'Dd' describes the mapping for the output stream fourth plane.
13778 Set output pixel format. Default is @code{yuva444p}.
13781 @subsection Examples
13785 Merge three gray video streams of same width and height into single video stream:
13787 [a0][a1][a2]mergeplanes=0x001020:yuv444p
13791 Merge 1st yuv444p stream and 2nd gray video stream into yuva444p video stream:
13793 [a0][a1]mergeplanes=0x00010210:yuva444p
13797 Swap Y and A plane in yuva444p stream:
13799 format=yuva444p,mergeplanes=0x03010200:yuva444p
13803 Swap U and V plane in yuv420p stream:
13805 format=yuv420p,mergeplanes=0x000201:yuv420p
13809 Cast a rgb24 clip to yuv444p:
13811 format=rgb24,mergeplanes=0x000102:yuv444p
13817 Estimate and export motion vectors using block matching algorithms.
13818 Motion vectors are stored in frame side data to be used by other filters.
13820 This filter accepts the following options:
13823 Specify the motion estimation method. Accepts one of the following values:
13827 Exhaustive search algorithm.
13829 Three step search algorithm.
13831 Two dimensional logarithmic search algorithm.
13833 New three step search algorithm.
13835 Four step search algorithm.
13837 Diamond search algorithm.
13839 Hexagon-based search algorithm.
13841 Enhanced predictive zonal search algorithm.
13843 Uneven multi-hexagon search algorithm.
13845 Default value is @samp{esa}.
13848 Macroblock size. Default @code{16}.
13851 Search parameter. Default @code{7}.
13854 @section midequalizer
13856 Apply Midway Image Equalization effect using two video streams.
13858 Midway Image Equalization adjusts a pair of images to have the same
13859 histogram, while maintaining their dynamics as much as possible. It's
13860 useful for e.g. matching exposures from a pair of stereo cameras.
13862 This filter has two inputs and one output, which must be of same pixel format, but
13863 may be of different sizes. The output of filter is first input adjusted with
13864 midway histogram of both inputs.
13866 This filter accepts the following option:
13870 Set which planes to process. Default is @code{15}, which is all available planes.
13873 @section minterpolate
13875 Convert the video to specified frame rate using motion interpolation.
13877 This filter accepts the following options:
13880 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}.
13883 Motion interpolation mode. Following values are accepted:
13886 Duplicate previous or next frame for interpolating new ones.
13888 Blend source frames. Interpolated frame is mean of previous and next frames.
13890 Motion compensated interpolation. Following options are effective when this mode is selected:
13894 Motion compensation mode. Following values are accepted:
13897 Overlapped block motion compensation.
13899 Adaptive overlapped block motion compensation. Window weighting coefficients are controlled adaptively according to the reliabilities of the neighboring motion vectors to reduce oversmoothing.
13901 Default mode is @samp{obmc}.
13904 Motion estimation mode. Following values are accepted:
13907 Bidirectional motion estimation. Motion vectors are estimated for each source frame in both forward and backward directions.
13909 Bilateral motion estimation. Motion vectors are estimated directly for interpolated frame.
13911 Default mode is @samp{bilat}.
13914 The algorithm to be used for motion estimation. Following values are accepted:
13917 Exhaustive search algorithm.
13919 Three step search algorithm.
13921 Two dimensional logarithmic search algorithm.
13923 New three step search algorithm.
13925 Four step search algorithm.
13927 Diamond search algorithm.
13929 Hexagon-based search algorithm.
13931 Enhanced predictive zonal search algorithm.
13933 Uneven multi-hexagon search algorithm.
13935 Default algorithm is @samp{epzs}.
13938 Macroblock size. Default @code{16}.
13941 Motion estimation search parameter. Default @code{32}.
13944 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).
13949 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:
13952 Disable scene change detection.
13954 Frame difference. Corresponding pixel values are compared and if it satisfies @var{scd_threshold} scene change is detected.
13956 Default method is @samp{fdiff}.
13958 @item scd_threshold
13959 Scene change detection threshold. Default is @code{10.}.
13964 Mix several video input streams into one video stream.
13966 A description of the accepted options follows.
13970 The number of inputs. If unspecified, it defaults to 2.
13973 Specify weight of each input video stream as sequence.
13974 Each weight is separated by space. If number of weights
13975 is smaller than number of @var{frames} last specified
13976 weight will be used for all remaining unset weights.
13979 Specify scale, if it is set it will be multiplied with sum
13980 of each weight multiplied with pixel values to give final destination
13981 pixel value. By default @var{scale} is auto scaled to sum of weights.
13984 Specify how end of stream is determined.
13987 The duration of the longest input. (default)
13990 The duration of the shortest input.
13993 The duration of the first input.
13997 @section mpdecimate
13999 Drop frames that do not differ greatly from the previous frame in
14000 order to reduce frame rate.
14002 The main use of this filter is for very-low-bitrate encoding
14003 (e.g. streaming over dialup modem), but it could in theory be used for
14004 fixing movies that were inverse-telecined incorrectly.
14006 A description of the accepted options follows.
14010 Set the maximum number of consecutive frames which can be dropped (if
14011 positive), or the minimum interval between dropped frames (if
14012 negative). If the value is 0, the frame is dropped disregarding the
14013 number of previous sequentially dropped frames.
14015 Default value is 0.
14020 Set the dropping threshold values.
14022 Values for @option{hi} and @option{lo} are for 8x8 pixel blocks and
14023 represent actual pixel value differences, so a threshold of 64
14024 corresponds to 1 unit of difference for each pixel, or the same spread
14025 out differently over the block.
14027 A frame is a candidate for dropping if no 8x8 blocks differ by more
14028 than a threshold of @option{hi}, and if no more than @option{frac} blocks (1
14029 meaning the whole image) differ by more than a threshold of @option{lo}.
14031 Default value for @option{hi} is 64*12, default value for @option{lo} is
14032 64*5, and default value for @option{frac} is 0.33.
14038 Negate (invert) the input video.
14040 It accepts the following option:
14045 With value 1, it negates the alpha component, if present. Default value is 0.
14051 Denoise frames using Non-Local Means algorithm.
14053 Each pixel is adjusted by looking for other pixels with similar contexts. This
14054 context similarity is defined by comparing their surrounding patches of size
14055 @option{p}x@option{p}. Patches are searched in an area of @option{r}x@option{r}
14058 Note that the research area defines centers for patches, which means some
14059 patches will be made of pixels outside that research area.
14061 The filter accepts the following options.
14065 Set denoising strength. Default is 1.0. Must be in range [1.0, 30.0].
14068 Set patch size. Default is 7. Must be odd number in range [0, 99].
14071 Same as @option{p} but for chroma planes.
14073 The default value is @var{0} and means automatic.
14076 Set research size. Default is 15. Must be odd number in range [0, 99].
14079 Same as @option{r} but for chroma planes.
14081 The default value is @var{0} and means automatic.
14086 Deinterlace video using neural network edge directed interpolation.
14088 This filter accepts the following options:
14092 Mandatory option, without binary file filter can not work.
14093 Currently file can be found here:
14094 https://github.com/dubhater/vapoursynth-nnedi3/blob/master/src/nnedi3_weights.bin
14097 Set which frames to deinterlace, by default it is @code{all}.
14098 Can be @code{all} or @code{interlaced}.
14101 Set mode of operation.
14103 Can be one of the following:
14107 Use frame flags, both fields.
14109 Use frame flags, single field.
14111 Use top field only.
14113 Use bottom field only.
14115 Use both fields, top first.
14117 Use both fields, bottom first.
14121 Set which planes to process, by default filter process all frames.
14124 Set size of local neighborhood around each pixel, used by the predictor neural
14127 Can be one of the following:
14140 Set the number of neurons in predictor neural network.
14141 Can be one of the following:
14152 Controls the number of different neural network predictions that are blended
14153 together to compute the final output value. Can be @code{fast}, default or
14157 Set which set of weights to use in the predictor.
14158 Can be one of the following:
14162 weights trained to minimize absolute error
14164 weights trained to minimize squared error
14168 Controls whether or not the prescreener neural network is used to decide
14169 which pixels should be processed by the predictor neural network and which
14170 can be handled by simple cubic interpolation.
14171 The prescreener is trained to know whether cubic interpolation will be
14172 sufficient for a pixel or whether it should be predicted by the predictor nn.
14173 The computational complexity of the prescreener nn is much less than that of
14174 the predictor nn. Since most pixels can be handled by cubic interpolation,
14175 using the prescreener generally results in much faster processing.
14176 The prescreener is pretty accurate, so the difference between using it and not
14177 using it is almost always unnoticeable.
14179 Can be one of the following:
14187 Default is @code{new}.
14190 Set various debugging flags.
14195 Force libavfilter not to use any of the specified pixel formats for the
14196 input to the next filter.
14198 It accepts the following parameters:
14202 A '|'-separated list of pixel format names, such as
14203 pix_fmts=yuv420p|monow|rgb24".
14207 @subsection Examples
14211 Force libavfilter to use a format different from @var{yuv420p} for the
14212 input to the vflip filter:
14214 noformat=pix_fmts=yuv420p,vflip
14218 Convert the input video to any of the formats not contained in the list:
14220 noformat=yuv420p|yuv444p|yuv410p
14226 Add noise on video input frame.
14228 The filter accepts the following options:
14236 Set noise seed for specific pixel component or all pixel components in case
14237 of @var{all_seed}. Default value is @code{123457}.
14239 @item all_strength, alls
14240 @item c0_strength, c0s
14241 @item c1_strength, c1s
14242 @item c2_strength, c2s
14243 @item c3_strength, c3s
14244 Set noise strength for specific pixel component or all pixel components in case
14245 @var{all_strength}. Default value is @code{0}. Allowed range is [0, 100].
14247 @item all_flags, allf
14248 @item c0_flags, c0f
14249 @item c1_flags, c1f
14250 @item c2_flags, c2f
14251 @item c3_flags, c3f
14252 Set pixel component flags or set flags for all components if @var{all_flags}.
14253 Available values for component flags are:
14256 averaged temporal noise (smoother)
14258 mix random noise with a (semi)regular pattern
14260 temporal noise (noise pattern changes between frames)
14262 uniform noise (gaussian otherwise)
14266 @subsection Examples
14268 Add temporal and uniform noise to input video:
14270 noise=alls=20:allf=t+u
14275 Normalize RGB video (aka histogram stretching, contrast stretching).
14276 See: https://en.wikipedia.org/wiki/Normalization_(image_processing)
14278 For each channel of each frame, the filter computes the input range and maps
14279 it linearly to the user-specified output range. The output range defaults
14280 to the full dynamic range from pure black to pure white.
14282 Temporal smoothing can be used on the input range to reduce flickering (rapid
14283 changes in brightness) caused when small dark or bright objects enter or leave
14284 the scene. This is similar to the auto-exposure (automatic gain control) on a
14285 video camera, and, like a video camera, it may cause a period of over- or
14286 under-exposure of the video.
14288 The R,G,B channels can be normalized independently, which may cause some
14289 color shifting, or linked together as a single channel, which prevents
14290 color shifting. Linked normalization preserves hue. Independent normalization
14291 does not, so it can be used to remove some color casts. Independent and linked
14292 normalization can be combined in any ratio.
14294 The normalize filter accepts the following options:
14299 Colors which define the output range. The minimum input value is mapped to
14300 the @var{blackpt}. The maximum input value is mapped to the @var{whitept}.
14301 The defaults are black and white respectively. Specifying white for
14302 @var{blackpt} and black for @var{whitept} will give color-inverted,
14303 normalized video. Shades of grey can be used to reduce the dynamic range
14304 (contrast). Specifying saturated colors here can create some interesting
14308 The number of previous frames to use for temporal smoothing. The input range
14309 of each channel is smoothed using a rolling average over the current frame
14310 and the @var{smoothing} previous frames. The default is 0 (no temporal
14314 Controls the ratio of independent (color shifting) channel normalization to
14315 linked (color preserving) normalization. 0.0 is fully linked, 1.0 is fully
14316 independent. Defaults to 1.0 (fully independent).
14319 Overall strength of the filter. 1.0 is full strength. 0.0 is a rather
14320 expensive no-op. Defaults to 1.0 (full strength).
14324 @subsection Commands
14325 This filter supports same @ref{commands} as options, excluding @var{smoothing} option.
14326 The command accepts the same syntax of the corresponding option.
14328 If the specified expression is not valid, it is kept at its current
14331 @subsection Examples
14333 Stretch video contrast to use the full dynamic range, with no temporal
14334 smoothing; may flicker depending on the source content:
14336 normalize=blackpt=black:whitept=white:smoothing=0
14339 As above, but with 50 frames of temporal smoothing; flicker should be
14340 reduced, depending on the source content:
14342 normalize=blackpt=black:whitept=white:smoothing=50
14345 As above, but with hue-preserving linked channel normalization:
14347 normalize=blackpt=black:whitept=white:smoothing=50:independence=0
14350 As above, but with half strength:
14352 normalize=blackpt=black:whitept=white:smoothing=50:independence=0:strength=0.5
14355 Map the darkest input color to red, the brightest input color to cyan:
14357 normalize=blackpt=red:whitept=cyan
14362 Pass the video source unchanged to the output.
14365 Optical Character Recognition
14367 This filter uses Tesseract for optical character recognition. To enable
14368 compilation of this filter, you need to configure FFmpeg with
14369 @code{--enable-libtesseract}.
14371 It accepts the following options:
14375 Set datapath to tesseract data. Default is to use whatever was
14376 set at installation.
14379 Set language, default is "eng".
14382 Set character whitelist.
14385 Set character blacklist.
14388 The filter exports recognized text as the frame metadata @code{lavfi.ocr.text}.
14389 The filter exports confidence of recognized words as the frame metadata @code{lavfi.ocr.confidence}.
14393 Apply a video transform using libopencv.
14395 To enable this filter, install the libopencv library and headers and
14396 configure FFmpeg with @code{--enable-libopencv}.
14398 It accepts the following parameters:
14403 The name of the libopencv filter to apply.
14405 @item filter_params
14406 The parameters to pass to the libopencv filter. If not specified, the default
14407 values are assumed.
14411 Refer to the official libopencv documentation for more precise
14413 @url{http://docs.opencv.org/master/modules/imgproc/doc/filtering.html}
14415 Several libopencv filters are supported; see the following subsections.
14420 Dilate an image by using a specific structuring element.
14421 It corresponds to the libopencv function @code{cvDilate}.
14423 It accepts the parameters: @var{struct_el}|@var{nb_iterations}.
14425 @var{struct_el} represents a structuring element, and has the syntax:
14426 @var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape}
14428 @var{cols} and @var{rows} represent the number of columns and rows of
14429 the structuring element, @var{anchor_x} and @var{anchor_y} the anchor
14430 point, and @var{shape} the shape for the structuring element. @var{shape}
14431 must be "rect", "cross", "ellipse", or "custom".
14433 If the value for @var{shape} is "custom", it must be followed by a
14434 string of the form "=@var{filename}". The file with name
14435 @var{filename} is assumed to represent a binary image, with each
14436 printable character corresponding to a bright pixel. When a custom
14437 @var{shape} is used, @var{cols} and @var{rows} are ignored, the number
14438 or columns and rows of the read file are assumed instead.
14440 The default value for @var{struct_el} is "3x3+0x0/rect".
14442 @var{nb_iterations} specifies the number of times the transform is
14443 applied to the image, and defaults to 1.
14447 # Use the default values
14450 # Dilate using a structuring element with a 5x5 cross, iterating two times
14451 ocv=filter_name=dilate:filter_params=5x5+2x2/cross|2
14453 # Read the shape from the file diamond.shape, iterating two times.
14454 # The file diamond.shape may contain a pattern of characters like this
14460 # The specified columns and rows are ignored
14461 # but the anchor point coordinates are not
14462 ocv=dilate:0x0+2x2/custom=diamond.shape|2
14467 Erode an image by using a specific structuring element.
14468 It corresponds to the libopencv function @code{cvErode}.
14470 It accepts the parameters: @var{struct_el}:@var{nb_iterations},
14471 with the same syntax and semantics as the @ref{dilate} filter.
14475 Smooth the input video.
14477 The filter takes the following parameters:
14478 @var{type}|@var{param1}|@var{param2}|@var{param3}|@var{param4}.
14480 @var{type} is the type of smooth filter to apply, and must be one of
14481 the following values: "blur", "blur_no_scale", "median", "gaussian",
14482 or "bilateral". The default value is "gaussian".
14484 The meaning of @var{param1}, @var{param2}, @var{param3}, and @var{param4}
14485 depends on the smooth type. @var{param1} and
14486 @var{param2} accept integer positive values or 0. @var{param3} and
14487 @var{param4} accept floating point values.
14489 The default value for @var{param1} is 3. The default value for the
14490 other parameters is 0.
14492 These parameters correspond to the parameters assigned to the
14493 libopencv function @code{cvSmooth}.
14495 @section oscilloscope
14497 2D Video Oscilloscope.
14499 Useful to measure spatial impulse, step responses, chroma delays, etc.
14501 It accepts the following parameters:
14505 Set scope center x position.
14508 Set scope center y position.
14511 Set scope size, relative to frame diagonal.
14514 Set scope tilt/rotation.
14520 Set trace center x position.
14523 Set trace center y position.
14526 Set trace width, relative to width of frame.
14529 Set trace height, relative to height of frame.
14532 Set which components to trace. By default it traces first three components.
14535 Draw trace grid. By default is enabled.
14538 Draw some statistics. By default is enabled.
14541 Draw scope. By default is enabled.
14544 @subsection Commands
14545 This filter supports same @ref{commands} as options.
14546 The command accepts the same syntax of the corresponding option.
14548 If the specified expression is not valid, it is kept at its current
14551 @subsection Examples
14555 Inspect full first row of video frame.
14557 oscilloscope=x=0.5:y=0:s=1
14561 Inspect full last row of video frame.
14563 oscilloscope=x=0.5:y=1:s=1
14567 Inspect full 5th line of video frame of height 1080.
14569 oscilloscope=x=0.5:y=5/1080:s=1
14573 Inspect full last column of video frame.
14575 oscilloscope=x=1:y=0.5:s=1:t=1
14583 Overlay one video on top of another.
14585 It takes two inputs and has one output. The first input is the "main"
14586 video on which the second input is overlaid.
14588 It accepts the following parameters:
14590 A description of the accepted options follows.
14595 Set the expression for the x and y coordinates of the overlaid video
14596 on the main video. Default value is "0" for both expressions. In case
14597 the expression is invalid, it is set to a huge value (meaning that the
14598 overlay will not be displayed within the output visible area).
14601 See @ref{framesync}.
14604 Set when the expressions for @option{x}, and @option{y} are evaluated.
14606 It accepts the following values:
14609 only evaluate expressions once during the filter initialization or
14610 when a command is processed
14613 evaluate expressions for each incoming frame
14616 Default value is @samp{frame}.
14619 See @ref{framesync}.
14622 Set the format for the output video.
14624 It accepts the following values:
14627 force YUV420 output
14630 force YUV420p10 output
14633 force YUV422 output
14636 force YUV422p10 output
14639 force YUV444 output
14642 force packed RGB output
14645 force planar RGB output
14648 automatically pick format
14651 Default value is @samp{yuv420}.
14654 See @ref{framesync}.
14657 Set format of alpha of the overlaid video, it can be @var{straight} or
14658 @var{premultiplied}. Default is @var{straight}.
14661 The @option{x}, and @option{y} expressions can contain the following
14667 The main input width and height.
14671 The overlay input width and height.
14675 The computed values for @var{x} and @var{y}. They are evaluated for
14680 horizontal and vertical chroma subsample values of the output
14681 format. For example for the pixel format "yuv422p" @var{hsub} is 2 and
14685 the number of input frame, starting from 0
14688 the position in the file of the input frame, NAN if unknown
14691 The timestamp, expressed in seconds. It's NAN if the input timestamp is unknown.
14695 This filter also supports the @ref{framesync} options.
14697 Note that the @var{n}, @var{pos}, @var{t} variables are available only
14698 when evaluation is done @emph{per frame}, and will evaluate to NAN
14699 when @option{eval} is set to @samp{init}.
14701 Be aware that frames are taken from each input video in timestamp
14702 order, hence, if their initial timestamps differ, it is a good idea
14703 to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to
14704 have them begin in the same zero timestamp, as the example for
14705 the @var{movie} filter does.
14707 You can chain together more overlays but you should test the
14708 efficiency of such approach.
14710 @subsection Commands
14712 This filter supports the following commands:
14716 Modify the x and y of the overlay input.
14717 The command accepts the same syntax of the corresponding option.
14719 If the specified expression is not valid, it is kept at its current
14723 @subsection Examples
14727 Draw the overlay at 10 pixels from the bottom right corner of the main
14730 overlay=main_w-overlay_w-10:main_h-overlay_h-10
14733 Using named options the example above becomes:
14735 overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10
14739 Insert a transparent PNG logo in the bottom left corner of the input,
14740 using the @command{ffmpeg} tool with the @code{-filter_complex} option:
14742 ffmpeg -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output
14746 Insert 2 different transparent PNG logos (second logo on bottom
14747 right corner) using the @command{ffmpeg} tool:
14749 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
14753 Add a transparent color layer on top of the main video; @code{WxH}
14754 must specify the size of the main input to the overlay filter:
14756 color=color=red@@.3:size=WxH [over]; [in][over] overlay [out]
14760 Play an original video and a filtered version (here with the deshake
14761 filter) side by side using the @command{ffplay} tool:
14763 ffplay input.avi -vf 'split[a][b]; [a]pad=iw*2:ih[src]; [b]deshake[filt]; [src][filt]overlay=w'
14766 The above command is the same as:
14768 ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w'
14772 Make a sliding overlay appearing from the left to the right top part of the
14773 screen starting since time 2:
14775 overlay=x='if(gte(t,2), -w+(t-2)*20, NAN)':y=0
14779 Compose output by putting two input videos side to side:
14781 ffmpeg -i left.avi -i right.avi -filter_complex "
14782 nullsrc=size=200x100 [background];
14783 [0:v] setpts=PTS-STARTPTS, scale=100x100 [left];
14784 [1:v] setpts=PTS-STARTPTS, scale=100x100 [right];
14785 [background][left] overlay=shortest=1 [background+left];
14786 [background+left][right] overlay=shortest=1:x=100 [left+right]
14791 Mask 10-20 seconds of a video by applying the delogo filter to a section
14793 ffmpeg -i test.avi -codec:v:0 wmv2 -ar 11025 -b:v 9000k
14794 -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]'
14799 Chain several overlays in cascade:
14801 nullsrc=s=200x200 [bg];
14802 testsrc=s=100x100, split=4 [in0][in1][in2][in3];
14803 [in0] lutrgb=r=0, [bg] overlay=0:0 [mid0];
14804 [in1] lutrgb=g=0, [mid0] overlay=100:0 [mid1];
14805 [in2] lutrgb=b=0, [mid1] overlay=0:100 [mid2];
14806 [in3] null, [mid2] overlay=100:100 [out0]
14811 @anchor{overlay_cuda}
14812 @section overlay_cuda
14814 Overlay one video on top of another.
14816 This is the CUDA cariant of the @ref{overlay} filter.
14817 It only accepts CUDA frames. The underlying input pixel formats have to match.
14819 It takes two inputs and has one output. The first input is the "main"
14820 video on which the second input is overlaid.
14822 It accepts the following parameters:
14827 Set the x and y coordinates of the overlaid video on the main video.
14828 Default value is "0" for both expressions.
14831 See @ref{framesync}.
14834 See @ref{framesync}.
14837 See @ref{framesync}.
14841 This filter also supports the @ref{framesync} options.
14845 Apply Overcomplete Wavelet denoiser.
14847 The filter accepts the following options:
14853 Larger depth values will denoise lower frequency components more, but
14854 slow down filtering.
14856 Must be an int in the range 8-16, default is @code{8}.
14858 @item luma_strength, ls
14861 Must be a double value in the range 0-1000, default is @code{1.0}.
14863 @item chroma_strength, cs
14864 Set chroma strength.
14866 Must be a double value in the range 0-1000, default is @code{1.0}.
14872 Add paddings to the input image, and place the original input at the
14873 provided @var{x}, @var{y} coordinates.
14875 It accepts the following parameters:
14880 Specify an expression for the size of the output image with the
14881 paddings added. If the value for @var{width} or @var{height} is 0, the
14882 corresponding input size is used for the output.
14884 The @var{width} expression can reference the value set by the
14885 @var{height} expression, and vice versa.
14887 The default value of @var{width} and @var{height} is 0.
14891 Specify the offsets to place the input image at within the padded area,
14892 with respect to the top/left border of the output image.
14894 The @var{x} expression can reference the value set by the @var{y}
14895 expression, and vice versa.
14897 The default value of @var{x} and @var{y} is 0.
14899 If @var{x} or @var{y} evaluate to a negative number, they'll be changed
14900 so the input image is centered on the padded area.
14903 Specify the color of the padded area. For the syntax of this option,
14904 check the @ref{color syntax,,"Color" section in the ffmpeg-utils
14905 manual,ffmpeg-utils}.
14907 The default value of @var{color} is "black".
14910 Specify when to evaluate @var{width}, @var{height}, @var{x} and @var{y} expression.
14912 It accepts the following values:
14916 Only evaluate expressions once during the filter initialization or when
14917 a command is processed.
14920 Evaluate expressions for each incoming frame.
14924 Default value is @samp{init}.
14927 Pad to aspect instead to a resolution.
14931 The value for the @var{width}, @var{height}, @var{x}, and @var{y}
14932 options are expressions containing the following constants:
14937 The input video width and height.
14941 These are the same as @var{in_w} and @var{in_h}.
14945 The output width and height (the size of the padded area), as
14946 specified by the @var{width} and @var{height} expressions.
14950 These are the same as @var{out_w} and @var{out_h}.
14954 The x and y offsets as specified by the @var{x} and @var{y}
14955 expressions, or NAN if not yet specified.
14958 same as @var{iw} / @var{ih}
14961 input sample aspect ratio
14964 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
14968 The horizontal and vertical chroma subsample values. For example for the
14969 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
14972 @subsection Examples
14976 Add paddings with the color "violet" to the input video. The output video
14977 size is 640x480, and the top-left corner of the input video is placed at
14980 pad=640:480:0:40:violet
14983 The example above is equivalent to the following command:
14985 pad=width=640:height=480:x=0:y=40:color=violet
14989 Pad the input to get an output with dimensions increased by 3/2,
14990 and put the input video at the center of the padded area:
14992 pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2"
14996 Pad the input to get a squared output with size equal to the maximum
14997 value between the input width and height, and put the input video at
14998 the center of the padded area:
15000 pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2"
15004 Pad the input to get a final w/h ratio of 16:9:
15006 pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2"
15010 In case of anamorphic video, in order to set the output display aspect
15011 correctly, it is necessary to use @var{sar} in the expression,
15012 according to the relation:
15014 (ih * X / ih) * sar = output_dar
15015 X = output_dar / sar
15018 Thus the previous example needs to be modified to:
15020 pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2"
15024 Double the output size and put the input video in the bottom-right
15025 corner of the output padded area:
15027 pad="2*iw:2*ih:ow-iw:oh-ih"
15031 @anchor{palettegen}
15032 @section palettegen
15034 Generate one palette for a whole video stream.
15036 It accepts the following options:
15040 Set the maximum number of colors to quantize in the palette.
15041 Note: the palette will still contain 256 colors; the unused palette entries
15044 @item reserve_transparent
15045 Create a palette of 255 colors maximum and reserve the last one for
15046 transparency. Reserving the transparency color is useful for GIF optimization.
15047 If not set, the maximum of colors in the palette will be 256. You probably want
15048 to disable this option for a standalone image.
15051 @item transparency_color
15052 Set the color that will be used as background for transparency.
15055 Set statistics mode.
15057 It accepts the following values:
15060 Compute full frame histograms.
15062 Compute histograms only for the part that differs from previous frame. This
15063 might be relevant to give more importance to the moving part of your input if
15064 the background is static.
15066 Compute new histogram for each frame.
15069 Default value is @var{full}.
15072 The filter also exports the frame metadata @code{lavfi.color_quant_ratio}
15073 (@code{nb_color_in / nb_color_out}) which you can use to evaluate the degree of
15074 color quantization of the palette. This information is also visible at
15075 @var{info} logging level.
15077 @subsection Examples
15081 Generate a representative palette of a given video using @command{ffmpeg}:
15083 ffmpeg -i input.mkv -vf palettegen palette.png
15087 @section paletteuse
15089 Use a palette to downsample an input video stream.
15091 The filter takes two inputs: one video stream and a palette. The palette must
15092 be a 256 pixels image.
15094 It accepts the following options:
15098 Select dithering mode. Available algorithms are:
15101 Ordered 8x8 bayer dithering (deterministic)
15103 Dithering as defined by Paul Heckbert in 1982 (simple error diffusion).
15104 Note: this dithering is sometimes considered "wrong" and is included as a
15106 @item floyd_steinberg
15107 Floyd and Steingberg dithering (error diffusion)
15109 Frankie Sierra dithering v2 (error diffusion)
15111 Frankie Sierra dithering v2 "Lite" (error diffusion)
15114 Default is @var{sierra2_4a}.
15117 When @var{bayer} dithering is selected, this option defines the scale of the
15118 pattern (how much the crosshatch pattern is visible). A low value means more
15119 visible pattern for less banding, and higher value means less visible pattern
15120 at the cost of more banding.
15122 The option must be an integer value in the range [0,5]. Default is @var{2}.
15125 If set, define the zone to process
15129 Only the changing rectangle will be reprocessed. This is similar to GIF
15130 cropping/offsetting compression mechanism. This option can be useful for speed
15131 if only a part of the image is changing, and has use cases such as limiting the
15132 scope of the error diffusal @option{dither} to the rectangle that bounds the
15133 moving scene (it leads to more deterministic output if the scene doesn't change
15134 much, and as a result less moving noise and better GIF compression).
15137 Default is @var{none}.
15140 Take new palette for each output frame.
15142 @item alpha_threshold
15143 Sets the alpha threshold for transparency. Alpha values above this threshold
15144 will be treated as completely opaque, and values below this threshold will be
15145 treated as completely transparent.
15147 The option must be an integer value in the range [0,255]. Default is @var{128}.
15150 @subsection Examples
15154 Use a palette (generated for example with @ref{palettegen}) to encode a GIF
15155 using @command{ffmpeg}:
15157 ffmpeg -i input.mkv -i palette.png -lavfi paletteuse output.gif
15161 @section perspective
15163 Correct perspective of video not recorded perpendicular to the screen.
15165 A description of the accepted parameters follows.
15176 Set coordinates expression for top left, top right, bottom left and bottom right corners.
15177 Default values are @code{0:0:W:0:0:H:W:H} with which perspective will remain unchanged.
15178 If the @code{sense} option is set to @code{source}, then the specified points will be sent
15179 to the corners of the destination. If the @code{sense} option is set to @code{destination},
15180 then the corners of the source will be sent to the specified coordinates.
15182 The expressions can use the following variables:
15187 the width and height of video frame.
15191 Output frame count.
15194 @item interpolation
15195 Set interpolation for perspective correction.
15197 It accepts the following values:
15203 Default value is @samp{linear}.
15206 Set interpretation of coordinate options.
15208 It accepts the following values:
15212 Send point in the source specified by the given coordinates to
15213 the corners of the destination.
15215 @item 1, destination
15217 Send the corners of the source to the point in the destination specified
15218 by the given coordinates.
15220 Default value is @samp{source}.
15224 Set when the expressions for coordinates @option{x0,y0,...x3,y3} are evaluated.
15226 It accepts the following values:
15229 only evaluate expressions once during the filter initialization or
15230 when a command is processed
15233 evaluate expressions for each incoming frame
15236 Default value is @samp{init}.
15241 Delay interlaced video by one field time so that the field order changes.
15243 The intended use is to fix PAL movies that have been captured with the
15244 opposite field order to the film-to-video transfer.
15246 A description of the accepted parameters follows.
15252 It accepts the following values:
15255 Capture field order top-first, transfer bottom-first.
15256 Filter will delay the bottom field.
15259 Capture field order bottom-first, transfer top-first.
15260 Filter will delay the top field.
15263 Capture and transfer with the same field order. This mode only exists
15264 for the documentation of the other options to refer to, but if you
15265 actually select it, the filter will faithfully do nothing.
15268 Capture field order determined automatically by field flags, transfer
15270 Filter selects among @samp{t} and @samp{b} modes on a frame by frame
15271 basis using field flags. If no field information is available,
15272 then this works just like @samp{u}.
15275 Capture unknown or varying, transfer opposite.
15276 Filter selects among @samp{t} and @samp{b} on a frame by frame basis by
15277 analyzing the images and selecting the alternative that produces best
15278 match between the fields.
15281 Capture top-first, transfer unknown or varying.
15282 Filter selects among @samp{t} and @samp{p} using image analysis.
15285 Capture bottom-first, transfer unknown or varying.
15286 Filter selects among @samp{b} and @samp{p} using image analysis.
15289 Capture determined by field flags, transfer unknown or varying.
15290 Filter selects among @samp{t}, @samp{b} and @samp{p} using field flags and
15291 image analysis. If no field information is available, then this works just
15292 like @samp{U}. This is the default mode.
15295 Both capture and transfer unknown or varying.
15296 Filter selects among @samp{t}, @samp{b} and @samp{p} using image analysis only.
15300 @section photosensitivity
15301 Reduce various flashes in video, so to help users with epilepsy.
15303 It accepts the following options:
15306 Set how many frames to use when filtering. Default is 30.
15309 Set detection threshold factor. Default is 1.
15313 Set how many pixels to skip when sampling frames. Default is 1.
15314 Allowed range is from 1 to 1024.
15317 Leave frames unchanged. Default is disabled.
15320 @section pixdesctest
15322 Pixel format descriptor test filter, mainly useful for internal
15323 testing. The output video should be equal to the input video.
15327 format=monow, pixdesctest
15330 can be used to test the monowhite pixel format descriptor definition.
15334 Display sample values of color channels. Mainly useful for checking color
15335 and levels. Minimum supported resolution is 640x480.
15337 The filters accept the following options:
15341 Set scope X position, relative offset on X axis.
15344 Set scope Y position, relative offset on Y axis.
15353 Set window opacity. This window also holds statistics about pixel area.
15356 Set window X position, relative offset on X axis.
15359 Set window Y position, relative offset on Y axis.
15364 Enable the specified chain of postprocessing subfilters using libpostproc. This
15365 library should be automatically selected with a GPL build (@code{--enable-gpl}).
15366 Subfilters must be separated by '/' and can be disabled by prepending a '-'.
15367 Each subfilter and some options have a short and a long name that can be used
15368 interchangeably, i.e. dr/dering are the same.
15370 The filters accept the following options:
15374 Set postprocessing subfilters string.
15377 All subfilters share common options to determine their scope:
15381 Honor the quality commands for this subfilter.
15384 Do chrominance filtering, too (default).
15387 Do luminance filtering only (no chrominance).
15390 Do chrominance filtering only (no luminance).
15393 These options can be appended after the subfilter name, separated by a '|'.
15395 Available subfilters are:
15398 @item hb/hdeblock[|difference[|flatness]]
15399 Horizontal deblocking filter
15402 Difference factor where higher values mean more deblocking (default: @code{32}).
15404 Flatness threshold where lower values mean more deblocking (default: @code{39}).
15407 @item vb/vdeblock[|difference[|flatness]]
15408 Vertical deblocking filter
15411 Difference factor where higher values mean more deblocking (default: @code{32}).
15413 Flatness threshold where lower values mean more deblocking (default: @code{39}).
15416 @item ha/hadeblock[|difference[|flatness]]
15417 Accurate horizontal deblocking filter
15420 Difference factor where higher values mean more deblocking (default: @code{32}).
15422 Flatness threshold where lower values mean more deblocking (default: @code{39}).
15425 @item va/vadeblock[|difference[|flatness]]
15426 Accurate vertical deblocking filter
15429 Difference factor where higher values mean more deblocking (default: @code{32}).
15431 Flatness threshold where lower values mean more deblocking (default: @code{39}).
15435 The horizontal and vertical deblocking filters share the difference and
15436 flatness values so you cannot set different horizontal and vertical
15440 @item h1/x1hdeblock
15441 Experimental horizontal deblocking filter
15443 @item v1/x1vdeblock
15444 Experimental vertical deblocking filter
15449 @item tn/tmpnoise[|threshold1[|threshold2[|threshold3]]], temporal noise reducer
15452 larger -> stronger filtering
15454 larger -> stronger filtering
15456 larger -> stronger filtering
15459 @item al/autolevels[:f/fullyrange], automatic brightness / contrast correction
15462 Stretch luminance to @code{0-255}.
15465 @item lb/linblenddeint
15466 Linear blend deinterlacing filter that deinterlaces the given block by
15467 filtering all lines with a @code{(1 2 1)} filter.
15469 @item li/linipoldeint
15470 Linear interpolating deinterlacing filter that deinterlaces the given block by
15471 linearly interpolating every second line.
15473 @item ci/cubicipoldeint
15474 Cubic interpolating deinterlacing filter deinterlaces the given block by
15475 cubically interpolating every second line.
15477 @item md/mediandeint
15478 Median deinterlacing filter that deinterlaces the given block by applying a
15479 median filter to every second line.
15481 @item fd/ffmpegdeint
15482 FFmpeg deinterlacing filter that deinterlaces the given block by filtering every
15483 second line with a @code{(-1 4 2 4 -1)} filter.
15486 Vertically applied FIR lowpass deinterlacing filter that deinterlaces the given
15487 block by filtering all lines with a @code{(-1 2 6 2 -1)} filter.
15489 @item fq/forceQuant[|quantizer]
15490 Overrides the quantizer table from the input with the constant quantizer you
15498 Default pp filter combination (@code{hb|a,vb|a,dr|a})
15501 Fast pp filter combination (@code{h1|a,v1|a,dr|a})
15504 High quality pp filter combination (@code{ha|a|128|7,va|a,dr|a})
15507 @subsection Examples
15511 Apply horizontal and vertical deblocking, deringing and automatic
15512 brightness/contrast:
15518 Apply default filters without brightness/contrast correction:
15524 Apply default filters and temporal denoiser:
15526 pp=default/tmpnoise|1|2|3
15530 Apply deblocking on luminance only, and switch vertical deblocking on or off
15531 automatically depending on available CPU time:
15538 Apply Postprocessing filter 7. It is variant of the @ref{spp} filter,
15539 similar to spp = 6 with 7 point DCT, where only the center sample is
15542 The filter accepts the following options:
15546 Force a constant quantization parameter. It accepts an integer in range
15547 0 to 63. If not set, the filter will use the QP from the video stream
15551 Set thresholding mode. Available modes are:
15555 Set hard thresholding.
15557 Set soft thresholding (better de-ringing effect, but likely blurrier).
15559 Set medium thresholding (good results, default).
15563 @section premultiply
15564 Apply alpha premultiply effect to input video stream using first plane
15565 of second stream as alpha.
15567 Both streams must have same dimensions and same pixel format.
15569 The filter accepts the following option:
15573 Set which planes will be processed, unprocessed planes will be copied.
15574 By default value 0xf, all planes will be processed.
15577 Do not require 2nd input for processing, instead use alpha plane from input stream.
15581 Apply prewitt operator to input video stream.
15583 The filter accepts the following option:
15587 Set which planes will be processed, unprocessed planes will be copied.
15588 By default value 0xf, all planes will be processed.
15591 Set value which will be multiplied with filtered result.
15594 Set value which will be added to filtered result.
15597 @section pseudocolor
15599 Alter frame colors in video with pseudocolors.
15601 This filter accepts the following options:
15605 set pixel first component expression
15608 set pixel second component expression
15611 set pixel third component expression
15614 set pixel fourth component expression, corresponds to the alpha component
15617 set component to use as base for altering colors
15620 Each of them specifies the expression to use for computing the lookup table for
15621 the corresponding pixel component values.
15623 The expressions can contain the following constants and functions:
15628 The input width and height.
15631 The input value for the pixel component.
15633 @item ymin, umin, vmin, amin
15634 The minimum allowed component value.
15636 @item ymax, umax, vmax, amax
15637 The maximum allowed component value.
15640 All expressions default to "val".
15642 @subsection Examples
15646 Change too high luma values to gradient:
15648 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'"
15654 Obtain the average, maximum and minimum PSNR (Peak Signal to Noise
15655 Ratio) between two input videos.
15657 This filter takes in input two input videos, the first input is
15658 considered the "main" source and is passed unchanged to the
15659 output. The second input is used as a "reference" video for computing
15662 Both video inputs must have the same resolution and pixel format for
15663 this filter to work correctly. Also it assumes that both inputs
15664 have the same number of frames, which are compared one by one.
15666 The obtained average PSNR is printed through the logging system.
15668 The filter stores the accumulated MSE (mean squared error) of each
15669 frame, and at the end of the processing it is averaged across all frames
15670 equally, and the following formula is applied to obtain the PSNR:
15673 PSNR = 10*log10(MAX^2/MSE)
15676 Where MAX is the average of the maximum values of each component of the
15679 The description of the accepted parameters follows.
15682 @item stats_file, f
15683 If specified the filter will use the named file to save the PSNR of
15684 each individual frame. When filename equals "-" the data is sent to
15687 @item stats_version
15688 Specifies which version of the stats file format to use. Details of
15689 each format are written below.
15690 Default value is 1.
15692 @item stats_add_max
15693 Determines whether the max value is output to the stats log.
15694 Default value is 0.
15695 Requires stats_version >= 2. If this is set and stats_version < 2,
15696 the filter will return an error.
15699 This filter also supports the @ref{framesync} options.
15701 The file printed if @var{stats_file} is selected, contains a sequence of
15702 key/value pairs of the form @var{key}:@var{value} for each compared
15705 If a @var{stats_version} greater than 1 is specified, a header line precedes
15706 the list of per-frame-pair stats, with key value pairs following the frame
15707 format with the following parameters:
15710 @item psnr_log_version
15711 The version of the log file format. Will match @var{stats_version}.
15714 A comma separated list of the per-frame-pair parameters included in
15718 A description of each shown per-frame-pair parameter follows:
15722 sequential number of the input frame, starting from 1
15725 Mean Square Error pixel-by-pixel average difference of the compared
15726 frames, averaged over all the image components.
15728 @item mse_y, mse_u, mse_v, mse_r, mse_g, mse_b, mse_a
15729 Mean Square Error pixel-by-pixel average difference of the compared
15730 frames for the component specified by the suffix.
15732 @item psnr_y, psnr_u, psnr_v, psnr_r, psnr_g, psnr_b, psnr_a
15733 Peak Signal to Noise ratio of the compared frames for the component
15734 specified by the suffix.
15736 @item max_avg, max_y, max_u, max_v
15737 Maximum allowed value for each channel, and average over all
15741 @subsection Examples
15746 movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
15747 [main][ref] psnr="stats_file=stats.log" [out]
15750 On this example the input file being processed is compared with the
15751 reference file @file{ref_movie.mpg}. The PSNR of each individual frame
15752 is stored in @file{stats.log}.
15755 Another example with different containers:
15757 ffmpeg -i main.mpg -i ref.mkv -lavfi "[0:v]settb=AVTB,setpts=PTS-STARTPTS[main];[1:v]settb=AVTB,setpts=PTS-STARTPTS[ref];[main][ref]psnr" -f null -
15764 Pulldown reversal (inverse telecine) filter, capable of handling mixed
15765 hard-telecine, 24000/1001 fps progressive, and 30000/1001 fps progressive
15768 The pullup filter is designed to take advantage of future context in making
15769 its decisions. This filter is stateless in the sense that it does not lock
15770 onto a pattern to follow, but it instead looks forward to the following
15771 fields in order to identify matches and rebuild progressive frames.
15773 To produce content with an even framerate, insert the fps filter after
15774 pullup, use @code{fps=24000/1001} if the input frame rate is 29.97fps,
15775 @code{fps=24} for 30fps and the (rare) telecined 25fps input.
15777 The filter accepts the following options:
15784 These options set the amount of "junk" to ignore at the left, right, top, and
15785 bottom of the image, respectively. Left and right are in units of 8 pixels,
15786 while top and bottom are in units of 2 lines.
15787 The default is 8 pixels on each side.
15790 Set the strict breaks. Setting this option to 1 will reduce the chances of
15791 filter generating an occasional mismatched frame, but it may also cause an
15792 excessive number of frames to be dropped during high motion sequences.
15793 Conversely, setting it to -1 will make filter match fields more easily.
15794 This may help processing of video where there is slight blurring between
15795 the fields, but may also cause there to be interlaced frames in the output.
15796 Default value is @code{0}.
15799 Set the metric plane to use. It accepts the following values:
15805 Use chroma blue plane.
15808 Use chroma red plane.
15811 This option may be set to use chroma plane instead of the default luma plane
15812 for doing filter's computations. This may improve accuracy on very clean
15813 source material, but more likely will decrease accuracy, especially if there
15814 is chroma noise (rainbow effect) or any grayscale video.
15815 The main purpose of setting @option{mp} to a chroma plane is to reduce CPU
15816 load and make pullup usable in realtime on slow machines.
15819 For best results (without duplicated frames in the output file) it is
15820 necessary to change the output frame rate. For example, to inverse
15821 telecine NTSC input:
15823 ffmpeg -i input -vf pullup -r 24000/1001 ...
15828 Change video quantization parameters (QP).
15830 The filter accepts the following option:
15834 Set expression for quantization parameter.
15837 The expression is evaluated through the eval API and can contain, among others,
15838 the following constants:
15842 1 if index is not 129, 0 otherwise.
15845 Sequential index starting from -129 to 128.
15848 @subsection Examples
15852 Some equation like:
15860 Flush video frames from internal cache of frames into a random order.
15861 No frame is discarded.
15862 Inspired by @ref{frei0r} nervous filter.
15866 Set size in number of frames of internal cache, in range from @code{2} to
15867 @code{512}. Default is @code{30}.
15870 Set seed for random number generator, must be an integer included between
15871 @code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to
15872 less than @code{0}, the filter will try to use a good random seed on a
15876 @section readeia608
15878 Read closed captioning (EIA-608) information from the top lines of a video frame.
15880 This filter adds frame metadata for @code{lavfi.readeia608.X.cc} and
15881 @code{lavfi.readeia608.X.line}, where @code{X} is the number of the identified line
15882 with EIA-608 data (starting from 0). A description of each metadata value follows:
15885 @item lavfi.readeia608.X.cc
15886 The two bytes stored as EIA-608 data (printed in hexadecimal).
15888 @item lavfi.readeia608.X.line
15889 The number of the line on which the EIA-608 data was identified and read.
15892 This filter accepts the following options:
15896 Set the line to start scanning for EIA-608 data. Default is @code{0}.
15899 Set the line to end scanning for EIA-608 data. Default is @code{29}.
15902 Set the ratio of width reserved for sync code detection.
15903 Default is @code{0.27}. Allowed range is @code{[0.1 - 0.7]}.
15906 Enable checking the parity bit. In the event of a parity error, the filter will output
15907 @code{0x00} for that character. Default is false.
15910 Lowpass lines prior to further processing. Default is enabled.
15913 @subsection Commands
15915 This filter supports the all above options as @ref{commands}.
15917 @subsection Examples
15921 Output a csv with presentation time and the first two lines of identified EIA-608 captioning data.
15923 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
15929 Read vertical interval timecode (VITC) information from the top lines of a
15932 The filter adds frame metadata key @code{lavfi.readvitc.tc_str} with the
15933 timecode value, if a valid timecode has been detected. Further metadata key
15934 @code{lavfi.readvitc.found} is set to 0/1 depending on whether
15935 timecode data has been found or not.
15937 This filter accepts the following options:
15941 Set the maximum number of lines to scan for VITC data. If the value is set to
15942 @code{-1} the full video frame is scanned. Default is @code{45}.
15945 Set the luma threshold for black. Accepts float numbers in the range [0.0,1.0],
15946 default value is @code{0.2}. The value must be equal or less than @code{thr_w}.
15949 Set the luma threshold for white. Accepts float numbers in the range [0.0,1.0],
15950 default value is @code{0.6}. The value must be equal or greater than @code{thr_b}.
15953 @subsection Examples
15957 Detect and draw VITC data onto the video frame; if no valid VITC is detected,
15958 draw @code{--:--:--:--} as a placeholder:
15960 ffmpeg -i input.avi -filter:v 'readvitc,drawtext=fontfile=FreeMono.ttf:text=%@{metadata\\:lavfi.readvitc.tc_str\\:--\\\\\\:--\\\\\\:--\\\\\\:--@}:x=(w-tw)/2:y=400-ascent'
15966 Remap pixels using 2nd: Xmap and 3rd: Ymap input video stream.
15968 Destination pixel at position (X, Y) will be picked from source (x, y) position
15969 where x = Xmap(X, Y) and y = Ymap(X, Y). If mapping values are out of range, zero
15970 value for pixel will be used for destination pixel.
15972 Xmap and Ymap input video streams must be of same dimensions. Output video stream
15973 will have Xmap/Ymap video stream dimensions.
15974 Xmap and Ymap input video streams are 16bit depth, single channel.
15978 Specify pixel format of output from this filter. Can be @code{color} or @code{gray}.
15979 Default is @code{color}.
15982 Specify the color of the unmapped pixels. For the syntax of this option,
15983 check the @ref{color syntax,,"Color" section in the ffmpeg-utils
15984 manual,ffmpeg-utils}. Default color is @code{black}.
15987 @section removegrain
15989 The removegrain filter is a spatial denoiser for progressive video.
15993 Set mode for the first plane.
15996 Set mode for the second plane.
15999 Set mode for the third plane.
16002 Set mode for the fourth plane.
16005 Range of mode is from 0 to 24. Description of each mode follows:
16009 Leave input plane unchanged. Default.
16012 Clips the pixel with the minimum and maximum of the 8 neighbour pixels.
16015 Clips the pixel with the second minimum and maximum of the 8 neighbour pixels.
16018 Clips the pixel with the third minimum and maximum of the 8 neighbour pixels.
16021 Clips the pixel with the fourth minimum and maximum of the 8 neighbour pixels.
16022 This is equivalent to a median filter.
16025 Line-sensitive clipping giving the minimal change.
16028 Line-sensitive clipping, intermediate.
16031 Line-sensitive clipping, intermediate.
16034 Line-sensitive clipping, intermediate.
16037 Line-sensitive clipping on a line where the neighbours pixels are the closest.
16040 Replaces the target pixel with the closest neighbour.
16043 [1 2 1] horizontal and vertical kernel blur.
16049 Bob mode, interpolates top field from the line where the neighbours
16050 pixels are the closest.
16053 Bob mode, interpolates bottom field from the line where the neighbours
16054 pixels are the closest.
16057 Bob mode, interpolates top field. Same as 13 but with a more complicated
16058 interpolation formula.
16061 Bob mode, interpolates bottom field. Same as 14 but with a more complicated
16062 interpolation formula.
16065 Clips the pixel with the minimum and maximum of respectively the maximum and
16066 minimum of each pair of opposite neighbour pixels.
16069 Line-sensitive clipping using opposite neighbours whose greatest distance from
16070 the current pixel is minimal.
16073 Replaces the pixel with the average of its 8 neighbours.
16076 Averages the 9 pixels ([1 1 1] horizontal and vertical blur).
16079 Clips pixels using the averages of opposite neighbour.
16082 Same as mode 21 but simpler and faster.
16085 Small edge and halo removal, but reputed useless.
16091 @section removelogo
16093 Suppress a TV station logo, using an image file to determine which
16094 pixels comprise the logo. It works by filling in the pixels that
16095 comprise the logo with neighboring pixels.
16097 The filter accepts the following options:
16101 Set the filter bitmap file, which can be any image format supported by
16102 libavformat. The width and height of the image file must match those of the
16103 video stream being processed.
16106 Pixels in the provided bitmap image with a value of zero are not
16107 considered part of the logo, non-zero pixels are considered part of
16108 the logo. If you use white (255) for the logo and black (0) for the
16109 rest, you will be safe. For making the filter bitmap, it is
16110 recommended to take a screen capture of a black frame with the logo
16111 visible, and then using a threshold filter followed by the erode
16112 filter once or twice.
16114 If needed, little splotches can be fixed manually. Remember that if
16115 logo pixels are not covered, the filter quality will be much
16116 reduced. Marking too many pixels as part of the logo does not hurt as
16117 much, but it will increase the amount of blurring needed to cover over
16118 the image and will destroy more information than necessary, and extra
16119 pixels will slow things down on a large logo.
16121 @section repeatfields
16123 This filter uses the repeat_field flag from the Video ES headers and hard repeats
16124 fields based on its value.
16128 Reverse a video clip.
16130 Warning: This filter requires memory to buffer the entire clip, so trimming
16133 @subsection Examples
16137 Take the first 5 seconds of a clip, and reverse it.
16144 Shift R/G/B/A pixels horizontally and/or vertically.
16146 The filter accepts the following options:
16149 Set amount to shift red horizontally.
16151 Set amount to shift red vertically.
16153 Set amount to shift green horizontally.
16155 Set amount to shift green vertically.
16157 Set amount to shift blue horizontally.
16159 Set amount to shift blue vertically.
16161 Set amount to shift alpha horizontally.
16163 Set amount to shift alpha vertically.
16165 Set edge mode, can be @var{smear}, default, or @var{warp}.
16168 @subsection Commands
16170 This filter supports the all above options as @ref{commands}.
16173 Apply roberts cross operator to input video stream.
16175 The filter accepts the following option:
16179 Set which planes will be processed, unprocessed planes will be copied.
16180 By default value 0xf, all planes will be processed.
16183 Set value which will be multiplied with filtered result.
16186 Set value which will be added to filtered result.
16191 Rotate video by an arbitrary angle expressed in radians.
16193 The filter accepts the following options:
16195 A description of the optional parameters follows.
16198 Set an expression for the angle by which to rotate the input video
16199 clockwise, expressed as a number of radians. A negative value will
16200 result in a counter-clockwise rotation. By default it is set to "0".
16202 This expression is evaluated for each frame.
16205 Set the output width expression, default value is "iw".
16206 This expression is evaluated just once during configuration.
16209 Set the output height expression, default value is "ih".
16210 This expression is evaluated just once during configuration.
16213 Enable bilinear interpolation if set to 1, a value of 0 disables
16214 it. Default value is 1.
16217 Set the color used to fill the output area not covered by the rotated
16218 image. For the general syntax of this option, check the
16219 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
16220 If the special value "none" is selected then no
16221 background is printed (useful for example if the background is never shown).
16223 Default value is "black".
16226 The expressions for the angle and the output size can contain the
16227 following constants and functions:
16231 sequential number of the input frame, starting from 0. It is always NAN
16232 before the first frame is filtered.
16235 time in seconds of the input frame, it is set to 0 when the filter is
16236 configured. It is always NAN before the first frame is filtered.
16240 horizontal and vertical chroma subsample values. For example for the
16241 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
16245 the input video width and height
16249 the output width and height, that is the size of the padded area as
16250 specified by the @var{width} and @var{height} expressions
16254 the minimal width/height required for completely containing the input
16255 video rotated by @var{a} radians.
16257 These are only available when computing the @option{out_w} and
16258 @option{out_h} expressions.
16261 @subsection Examples
16265 Rotate the input by PI/6 radians clockwise:
16271 Rotate the input by PI/6 radians counter-clockwise:
16277 Rotate the input by 45 degrees clockwise:
16283 Apply a constant rotation with period T, starting from an angle of PI/3:
16285 rotate=PI/3+2*PI*t/T
16289 Make the input video rotation oscillating with a period of T
16290 seconds and an amplitude of A radians:
16292 rotate=A*sin(2*PI/T*t)
16296 Rotate the video, output size is chosen so that the whole rotating
16297 input video is always completely contained in the output:
16299 rotate='2*PI*t:ow=hypot(iw,ih):oh=ow'
16303 Rotate the video, reduce the output size so that no background is ever
16306 rotate=2*PI*t:ow='min(iw,ih)/sqrt(2)':oh=ow:c=none
16310 @subsection Commands
16312 The filter supports the following commands:
16316 Set the angle expression.
16317 The command accepts the same syntax of the corresponding option.
16319 If the specified expression is not valid, it is kept at its current
16325 Apply Shape Adaptive Blur.
16327 The filter accepts the following options:
16330 @item luma_radius, lr
16331 Set luma blur filter strength, must be a value in range 0.1-4.0, default
16332 value is 1.0. A greater value will result in a more blurred image, and
16333 in slower processing.
16335 @item luma_pre_filter_radius, lpfr
16336 Set luma pre-filter radius, must be a value in the 0.1-2.0 range, default
16339 @item luma_strength, ls
16340 Set luma maximum difference between pixels to still be considered, must
16341 be a value in the 0.1-100.0 range, default value is 1.0.
16343 @item chroma_radius, cr
16344 Set chroma blur filter strength, must be a value in range -0.9-4.0. A
16345 greater value will result in a more blurred image, and in slower
16348 @item chroma_pre_filter_radius, cpfr
16349 Set chroma pre-filter radius, must be a value in the -0.9-2.0 range.
16351 @item chroma_strength, cs
16352 Set chroma maximum difference between pixels to still be considered,
16353 must be a value in the -0.9-100.0 range.
16356 Each chroma option value, if not explicitly specified, is set to the
16357 corresponding luma option value.
16362 Scale (resize) the input video, using the libswscale library.
16364 The scale filter forces the output display aspect ratio to be the same
16365 of the input, by changing the output sample aspect ratio.
16367 If the input image format is different from the format requested by
16368 the next filter, the scale filter will convert the input to the
16371 @subsection Options
16372 The filter accepts the following options, or any of the options
16373 supported by the libswscale scaler.
16375 See @ref{scaler_options,,the ffmpeg-scaler manual,ffmpeg-scaler} for
16376 the complete list of scaler options.
16381 Set the output video dimension expression. Default value is the input
16384 If the @var{width} or @var{w} value is 0, the input width is used for
16385 the output. If the @var{height} or @var{h} value is 0, the input height
16386 is used for the output.
16388 If one and only one of the values is -n with n >= 1, the scale filter
16389 will use a value that maintains the aspect ratio of the input image,
16390 calculated from the other specified dimension. After that it will,
16391 however, make sure that the calculated dimension is divisible by n and
16392 adjust the value if necessary.
16394 If both values are -n with n >= 1, the behavior will be identical to
16395 both values being set to 0 as previously detailed.
16397 See below for the list of accepted constants for use in the dimension
16401 Specify when to evaluate @var{width} and @var{height} expression. It accepts the following values:
16405 Only evaluate expressions once during the filter initialization or when a command is processed.
16408 Evaluate expressions for each incoming frame.
16412 Default value is @samp{init}.
16416 Set the interlacing mode. It accepts the following values:
16420 Force interlaced aware scaling.
16423 Do not apply interlaced scaling.
16426 Select interlaced aware scaling depending on whether the source frames
16427 are flagged as interlaced or not.
16430 Default value is @samp{0}.
16433 Set libswscale scaling flags. See
16434 @ref{sws_flags,,the ffmpeg-scaler manual,ffmpeg-scaler} for the
16435 complete list of values. If not explicitly specified the filter applies
16439 @item param0, param1
16440 Set libswscale input parameters for scaling algorithms that need them. See
16441 @ref{sws_params,,the ffmpeg-scaler manual,ffmpeg-scaler} for the
16442 complete documentation. If not explicitly specified the filter applies
16448 Set the video size. For the syntax of this option, check the
16449 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
16451 @item in_color_matrix
16452 @item out_color_matrix
16453 Set in/output YCbCr color space type.
16455 This allows the autodetected value to be overridden as well as allows forcing
16456 a specific value used for the output and encoder.
16458 If not specified, the color space type depends on the pixel format.
16464 Choose automatically.
16467 Format conforming to International Telecommunication Union (ITU)
16468 Recommendation BT.709.
16471 Set color space conforming to the United States Federal Communications
16472 Commission (FCC) Code of Federal Regulations (CFR) Title 47 (2003) 73.682 (a).
16477 Set color space conforming to:
16481 ITU Radiocommunication Sector (ITU-R) Recommendation BT.601
16484 ITU-R Rec. BT.470-6 (1998) Systems B, B1, and G
16487 Society of Motion Picture and Television Engineers (SMPTE) ST 170:2004
16492 Set color space conforming to SMPTE ST 240:1999.
16495 Set color space conforming to ITU-R BT.2020 non-constant luminance system.
16500 Set in/output YCbCr sample range.
16502 This allows the autodetected value to be overridden as well as allows forcing
16503 a specific value used for the output and encoder. If not specified, the
16504 range depends on the pixel format. Possible values:
16508 Choose automatically.
16511 Set full range (0-255 in case of 8-bit luma).
16513 @item mpeg/limited/tv
16514 Set "MPEG" range (16-235 in case of 8-bit luma).
16517 @item force_original_aspect_ratio
16518 Enable decreasing or increasing output video width or height if necessary to
16519 keep the original aspect ratio. Possible values:
16523 Scale the video as specified and disable this feature.
16526 The output video dimensions will automatically be decreased if needed.
16529 The output video dimensions will automatically be increased if needed.
16533 One useful instance of this option is that when you know a specific device's
16534 maximum allowed resolution, you can use this to limit the output video to
16535 that, while retaining the aspect ratio. For example, device A allows
16536 1280x720 playback, and your video is 1920x800. Using this option (set it to
16537 decrease) and specifying 1280x720 to the command line makes the output
16540 Please note that this is a different thing than specifying -1 for @option{w}
16541 or @option{h}, you still need to specify the output resolution for this option
16544 @item force_divisible_by
16545 Ensures that both the output dimensions, width and height, are divisible by the
16546 given integer when used together with @option{force_original_aspect_ratio}. This
16547 works similar to using @code{-n} in the @option{w} and @option{h} options.
16549 This option respects the value set for @option{force_original_aspect_ratio},
16550 increasing or decreasing the resolution accordingly. The video's aspect ratio
16551 may be slightly modified.
16553 This option can be handy if you need to have a video fit within or exceed
16554 a defined resolution using @option{force_original_aspect_ratio} but also have
16555 encoder restrictions on width or height divisibility.
16559 The values of the @option{w} and @option{h} options are expressions
16560 containing the following constants:
16565 The input width and height
16569 These are the same as @var{in_w} and @var{in_h}.
16573 The output (scaled) width and height
16577 These are the same as @var{out_w} and @var{out_h}
16580 The same as @var{iw} / @var{ih}
16583 input sample aspect ratio
16586 The input display aspect ratio. Calculated from @code{(iw / ih) * sar}.
16590 horizontal and vertical input chroma subsample values. For example for the
16591 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
16595 horizontal and vertical output chroma subsample values. For example for the
16596 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
16599 The (sequential) number of the input frame, starting from 0.
16600 Only available with @code{eval=frame}.
16603 The presentation timestamp of the input frame, expressed as a number of
16604 seconds. Only available with @code{eval=frame}.
16607 The position (byte offset) of the frame in the input stream, or NaN if
16608 this information is unavailable and/or meaningless (for example in case of synthetic video).
16609 Only available with @code{eval=frame}.
16612 @subsection Examples
16616 Scale the input video to a size of 200x100
16621 This is equivalent to:
16632 Specify a size abbreviation for the output size:
16637 which can also be written as:
16643 Scale the input to 2x:
16645 scale=w=2*iw:h=2*ih
16649 The above is the same as:
16651 scale=2*in_w:2*in_h
16655 Scale the input to 2x with forced interlaced scaling:
16657 scale=2*iw:2*ih:interl=1
16661 Scale the input to half size:
16663 scale=w=iw/2:h=ih/2
16667 Increase the width, and set the height to the same size:
16673 Seek Greek harmony:
16680 Increase the height, and set the width to 3/2 of the height:
16682 scale=w=3/2*oh:h=3/5*ih
16686 Increase the size, making the size a multiple of the chroma
16689 scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub"
16693 Increase the width to a maximum of 500 pixels,
16694 keeping the same aspect ratio as the input:
16696 scale=w='min(500\, iw*3/2):h=-1'
16700 Make pixels square by combining scale and setsar:
16702 scale='trunc(ih*dar):ih',setsar=1/1
16706 Make pixels square by combining scale and setsar,
16707 making sure the resulting resolution is even (required by some codecs):
16709 scale='trunc(ih*dar/2)*2:trunc(ih/2)*2',setsar=1/1
16713 @subsection Commands
16715 This filter supports the following commands:
16719 Set the output video dimension expression.
16720 The command accepts the same syntax of the corresponding option.
16722 If the specified expression is not valid, it is kept at its current
16728 Use the NVIDIA Performance Primitives (libnpp) to perform scaling and/or pixel
16729 format conversion on CUDA video frames. Setting the output width and height
16730 works in the same way as for the @var{scale} filter.
16732 The following additional options are accepted:
16735 The pixel format of the output CUDA frames. If set to the string "same" (the
16736 default), the input format will be kept. Note that automatic format negotiation
16737 and conversion is not yet supported for hardware frames
16740 The interpolation algorithm used for resizing. One of the following:
16747 @item cubic2p_bspline
16748 2-parameter cubic (B=1, C=0)
16750 @item cubic2p_catmullrom
16751 2-parameter cubic (B=0, C=1/2)
16753 @item cubic2p_b05c03
16754 2-parameter cubic (B=1/2, C=3/10)
16762 @item force_original_aspect_ratio
16763 Enable decreasing or increasing output video width or height if necessary to
16764 keep the original aspect ratio. Possible values:
16768 Scale the video as specified and disable this feature.
16771 The output video dimensions will automatically be decreased if needed.
16774 The output video dimensions will automatically be increased if needed.
16778 One useful instance of this option is that when you know a specific device's
16779 maximum allowed resolution, you can use this to limit the output video to
16780 that, while retaining the aspect ratio. For example, device A allows
16781 1280x720 playback, and your video is 1920x800. Using this option (set it to
16782 decrease) and specifying 1280x720 to the command line makes the output
16785 Please note that this is a different thing than specifying -1 for @option{w}
16786 or @option{h}, you still need to specify the output resolution for this option
16789 @item force_divisible_by
16790 Ensures that both the output dimensions, width and height, are divisible by the
16791 given integer when used together with @option{force_original_aspect_ratio}. This
16792 works similar to using @code{-n} in the @option{w} and @option{h} options.
16794 This option respects the value set for @option{force_original_aspect_ratio},
16795 increasing or decreasing the resolution accordingly. The video's aspect ratio
16796 may be slightly modified.
16798 This option can be handy if you need to have a video fit within or exceed
16799 a defined resolution using @option{force_original_aspect_ratio} but also have
16800 encoder restrictions on width or height divisibility.
16806 Scale (resize) the input video, based on a reference video.
16808 See the scale filter for available options, scale2ref supports the same but
16809 uses the reference video instead of the main input as basis. scale2ref also
16810 supports the following additional constants for the @option{w} and
16811 @option{h} options:
16816 The main input video's width and height
16819 The same as @var{main_w} / @var{main_h}
16822 The main input video's sample aspect ratio
16824 @item main_dar, mdar
16825 The main input video's display aspect ratio. Calculated from
16826 @code{(main_w / main_h) * main_sar}.
16830 The main input video's horizontal and vertical chroma subsample values.
16831 For example for the pixel format "yuv422p" @var{hsub} is 2 and @var{vsub}
16835 The (sequential) number of the main input frame, starting from 0.
16836 Only available with @code{eval=frame}.
16839 The presentation timestamp of the main input frame, expressed as a number of
16840 seconds. Only available with @code{eval=frame}.
16843 The position (byte offset) of the frame in the main input stream, or NaN if
16844 this information is unavailable and/or meaningless (for example in case of synthetic video).
16845 Only available with @code{eval=frame}.
16848 @subsection Examples
16852 Scale a subtitle stream (b) to match the main video (a) in size before overlaying
16854 'scale2ref[b][a];[a][b]overlay'
16858 Scale a logo to 1/10th the height of a video, while preserving its display aspect ratio.
16860 [logo-in][video-in]scale2ref=w=oh*mdar:h=ih/10[logo-out][video-out]
16864 @subsection Commands
16866 This filter supports the following commands:
16870 Set the output video dimension expression.
16871 The command accepts the same syntax of the corresponding option.
16873 If the specified expression is not valid, it is kept at its current
16878 Scroll input video horizontally and/or vertically by constant speed.
16880 The filter accepts the following options:
16882 @item horizontal, h
16883 Set the horizontal scrolling speed. Default is 0. Allowed range is from -1 to 1.
16884 Negative values changes scrolling direction.
16887 Set the vertical scrolling speed. Default is 0. Allowed range is from -1 to 1.
16888 Negative values changes scrolling direction.
16891 Set the initial horizontal scrolling position. Default is 0. Allowed range is from 0 to 1.
16894 Set the initial vertical scrolling position. Default is 0. Allowed range is from 0 to 1.
16897 @subsection Commands
16899 This filter supports the following @ref{commands}:
16901 @item horizontal, h
16902 Set the horizontal scrolling speed.
16904 Set the vertical scrolling speed.
16910 Detect video scene change.
16912 This filter sets frame metadata with mafd between frame, the scene score, and
16913 forward the frame to the next filter, so they can use these metadata to detect
16914 scene change or others.
16916 In addition, this filter logs a message and sets frame metadata when it detects
16917 a scene change by @option{threshold}.
16919 @code{lavfi.scd.mafd} metadata keys are set with mafd for every frame.
16921 @code{lavfi.scd.score} metadata keys are set with scene change score for every frame
16922 to detect scene change.
16924 @code{lavfi.scd.time} metadata keys are set with current filtered frame time which
16925 detect scene change with @option{threshold}.
16927 The filter accepts the following options:
16931 Set the scene change detection threshold as a percentage of maximum change. Good
16932 values are in the @code{[8.0, 14.0]} range. The range for @option{threshold} is
16935 Default value is @code{10.}.
16938 Set the flag to pass scene change frames to the next filter. Default value is @code{0}
16939 You can enable it if you want to get snapshot of scene change frames only.
16942 @anchor{selectivecolor}
16943 @section selectivecolor
16945 Adjust cyan, magenta, yellow and black (CMYK) to certain ranges of colors (such
16946 as "reds", "yellows", "greens", "cyans", ...). The adjustment range is defined
16947 by the "purity" of the color (that is, how saturated it already is).
16949 This filter is similar to the Adobe Photoshop Selective Color tool.
16951 The filter accepts the following options:
16954 @item correction_method
16955 Select color correction method.
16957 Available values are:
16960 Specified adjustments are applied "as-is" (added/subtracted to original pixel
16963 Specified adjustments are relative to the original component value.
16965 Default is @code{absolute}.
16967 Adjustments for red pixels (pixels where the red component is the maximum)
16969 Adjustments for yellow pixels (pixels where the blue component is the minimum)
16971 Adjustments for green pixels (pixels where the green component is the maximum)
16973 Adjustments for cyan pixels (pixels where the red component is the minimum)
16975 Adjustments for blue pixels (pixels where the blue component is the maximum)
16977 Adjustments for magenta pixels (pixels where the green component is the minimum)
16979 Adjustments for white pixels (pixels where all components are greater than 128)
16981 Adjustments for all pixels except pure black and pure white
16983 Adjustments for black pixels (pixels where all components are lesser than 128)
16985 Specify a Photoshop selective color file (@code{.asv}) to import the settings from.
16988 All the adjustment settings (@option{reds}, @option{yellows}, ...) accept up to
16989 4 space separated floating point adjustment values in the [-1,1] range,
16990 respectively to adjust the amount of cyan, magenta, yellow and black for the
16991 pixels of its range.
16993 @subsection Examples
16997 Increase cyan by 50% and reduce yellow by 33% in every green areas, and
16998 increase magenta by 27% in blue areas:
17000 selectivecolor=greens=.5 0 -.33 0:blues=0 .27
17004 Use a Photoshop selective color preset:
17006 selectivecolor=psfile=MySelectiveColorPresets/Misty.asv
17010 @anchor{separatefields}
17011 @section separatefields
17013 The @code{separatefields} takes a frame-based video input and splits
17014 each frame into its components fields, producing a new half height clip
17015 with twice the frame rate and twice the frame count.
17017 This filter use field-dominance information in frame to decide which
17018 of each pair of fields to place first in the output.
17019 If it gets it wrong use @ref{setfield} filter before @code{separatefields} filter.
17021 @section setdar, setsar
17023 The @code{setdar} filter sets the Display Aspect Ratio for the filter
17026 This is done by changing the specified Sample (aka Pixel) Aspect
17027 Ratio, according to the following equation:
17029 @var{DAR} = @var{HORIZONTAL_RESOLUTION} / @var{VERTICAL_RESOLUTION} * @var{SAR}
17032 Keep in mind that the @code{setdar} filter does not modify the pixel
17033 dimensions of the video frame. Also, the display aspect ratio set by
17034 this filter may be changed by later filters in the filterchain,
17035 e.g. in case of scaling or if another "setdar" or a "setsar" filter is
17038 The @code{setsar} filter sets the Sample (aka Pixel) Aspect Ratio for
17039 the filter output video.
17041 Note that as a consequence of the application of this filter, the
17042 output display aspect ratio will change according to the equation
17045 Keep in mind that the sample aspect ratio set by the @code{setsar}
17046 filter may be changed by later filters in the filterchain, e.g. if
17047 another "setsar" or a "setdar" filter is applied.
17049 It accepts the following parameters:
17052 @item r, ratio, dar (@code{setdar} only), sar (@code{setsar} only)
17053 Set the aspect ratio used by the filter.
17055 The parameter can be a floating point number string, an expression, or
17056 a string of the form @var{num}:@var{den}, where @var{num} and
17057 @var{den} are the numerator and denominator of the aspect ratio. If
17058 the parameter is not specified, it is assumed the value "0".
17059 In case the form "@var{num}:@var{den}" is used, the @code{:} character
17063 Set the maximum integer value to use for expressing numerator and
17064 denominator when reducing the expressed aspect ratio to a rational.
17065 Default value is @code{100}.
17069 The parameter @var{sar} is an expression containing
17070 the following constants:
17074 These are approximated values for the mathematical constants e
17075 (Euler's number), pi (Greek pi), and phi (the golden ratio).
17078 The input width and height.
17081 These are the same as @var{w} / @var{h}.
17084 The input sample aspect ratio.
17087 The input display aspect ratio. It is the same as
17088 (@var{w} / @var{h}) * @var{sar}.
17091 Horizontal and vertical chroma subsample values. For example, for the
17092 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
17095 @subsection Examples
17100 To change the display aspect ratio to 16:9, specify one of the following:
17107 To change the sample aspect ratio to 10:11, specify:
17113 To set a display aspect ratio of 16:9, and specify a maximum integer value of
17114 1000 in the aspect ratio reduction, use the command:
17116 setdar=ratio=16/9:max=1000
17124 Force field for the output video frame.
17126 The @code{setfield} filter marks the interlace type field for the
17127 output frames. It does not change the input frame, but only sets the
17128 corresponding property, which affects how the frame is treated by
17129 following filters (e.g. @code{fieldorder} or @code{yadif}).
17131 The filter accepts the following options:
17136 Available values are:
17140 Keep the same field property.
17143 Mark the frame as bottom-field-first.
17146 Mark the frame as top-field-first.
17149 Mark the frame as progressive.
17156 Force frame parameter for the output video frame.
17158 The @code{setparams} filter marks interlace and color range for the
17159 output frames. It does not change the input frame, but only sets the
17160 corresponding property, which affects how the frame is treated by
17165 Available values are:
17169 Keep the same field property (default).
17172 Mark the frame as bottom-field-first.
17175 Mark the frame as top-field-first.
17178 Mark the frame as progressive.
17182 Available values are:
17186 Keep the same color range property (default).
17188 @item unspecified, unknown
17189 Mark the frame as unspecified color range.
17191 @item limited, tv, mpeg
17192 Mark the frame as limited range.
17194 @item full, pc, jpeg
17195 Mark the frame as full range.
17198 @item color_primaries
17199 Set the color primaries.
17200 Available values are:
17204 Keep the same color primaries property (default).
17221 Set the color transfer.
17222 Available values are:
17226 Keep the same color trc property (default).
17248 Set the colorspace.
17249 Available values are:
17253 Keep the same colorspace property (default).
17266 @item chroma-derived-nc
17267 @item chroma-derived-c
17274 Show a line containing various information for each input video frame.
17275 The input video is not modified.
17277 This filter supports the following options:
17281 Calculate checksums of each plane. By default enabled.
17284 The shown line contains a sequence of key/value pairs of the form
17285 @var{key}:@var{value}.
17287 The following values are shown in the output:
17291 The (sequential) number of the input frame, starting from 0.
17294 The Presentation TimeStamp of the input frame, expressed as a number of
17295 time base units. The time base unit depends on the filter input pad.
17298 The Presentation TimeStamp of the input frame, expressed as a number of
17302 The position of the frame in the input stream, or -1 if this information is
17303 unavailable and/or meaningless (for example in case of synthetic video).
17306 The pixel format name.
17309 The sample aspect ratio of the input frame, expressed in the form
17310 @var{num}/@var{den}.
17313 The size of the input frame. For the syntax of this option, check the
17314 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
17317 The type of interlaced mode ("P" for "progressive", "T" for top field first, "B"
17318 for bottom field first).
17321 This is 1 if the frame is a key frame, 0 otherwise.
17324 The picture type of the input frame ("I" for an I-frame, "P" for a
17325 P-frame, "B" for a B-frame, or "?" for an unknown type).
17326 Also refer to the documentation of the @code{AVPictureType} enum and of
17327 the @code{av_get_picture_type_char} function defined in
17328 @file{libavutil/avutil.h}.
17331 The Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame.
17333 @item plane_checksum
17334 The Adler-32 checksum (printed in hexadecimal) of each plane of the input frame,
17335 expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3}]".
17338 The mean value of pixels in each plane of the input frame, expressed in the form
17339 "[@var{mean0} @var{mean1} @var{mean2} @var{mean3}]".
17342 The standard deviation of pixel values in each plane of the input frame, expressed
17343 in the form "[@var{stdev0} @var{stdev1} @var{stdev2} @var{stdev3}]".
17347 @section showpalette
17349 Displays the 256 colors palette of each frame. This filter is only relevant for
17350 @var{pal8} pixel format frames.
17352 It accepts the following option:
17356 Set the size of the box used to represent one palette color entry. Default is
17357 @code{30} (for a @code{30x30} pixel box).
17360 @section shuffleframes
17362 Reorder and/or duplicate and/or drop video frames.
17364 It accepts the following parameters:
17368 Set the destination indexes of input frames.
17369 This is space or '|' separated list of indexes that maps input frames to output
17370 frames. Number of indexes also sets maximal value that each index may have.
17371 '-1' index have special meaning and that is to drop frame.
17374 The first frame has the index 0. The default is to keep the input unchanged.
17376 @subsection Examples
17380 Swap second and third frame of every three frames of the input:
17382 ffmpeg -i INPUT -vf "shuffleframes=0 2 1" OUTPUT
17386 Swap 10th and 1st frame of every ten frames of the input:
17388 ffmpeg -i INPUT -vf "shuffleframes=9 1 2 3 4 5 6 7 8 0" OUTPUT
17392 @section shuffleplanes
17394 Reorder and/or duplicate video planes.
17396 It accepts the following parameters:
17401 The index of the input plane to be used as the first output plane.
17404 The index of the input plane to be used as the second output plane.
17407 The index of the input plane to be used as the third output plane.
17410 The index of the input plane to be used as the fourth output plane.
17414 The first plane has the index 0. The default is to keep the input unchanged.
17416 @subsection Examples
17420 Swap the second and third planes of the input:
17422 ffmpeg -i INPUT -vf shuffleplanes=0:2:1:3 OUTPUT
17426 @anchor{signalstats}
17427 @section signalstats
17428 Evaluate various visual metrics that assist in determining issues associated
17429 with the digitization of analog video media.
17431 By default the filter will log these metadata values:
17435 Display the minimal Y value contained within the input frame. Expressed in
17439 Display the Y value at the 10% percentile within the input frame. Expressed in
17443 Display the average Y value within the input frame. Expressed in range of
17447 Display the Y value at the 90% percentile within the input frame. Expressed in
17451 Display the maximum Y value contained within the input frame. Expressed in
17455 Display the minimal U value contained within the input frame. Expressed in
17459 Display the U value at the 10% percentile within the input frame. Expressed in
17463 Display the average U value within the input frame. Expressed in range of
17467 Display the U value at the 90% percentile within the input frame. Expressed in
17471 Display the maximum U value contained within the input frame. Expressed in
17475 Display the minimal V value contained within the input frame. Expressed in
17479 Display the V value at the 10% percentile within the input frame. Expressed in
17483 Display the average V value within the input frame. Expressed in range of
17487 Display the V value at the 90% percentile within the input frame. Expressed in
17491 Display the maximum V value contained within the input frame. Expressed in
17495 Display the minimal saturation value contained within the input frame.
17496 Expressed in range of [0-~181.02].
17499 Display the saturation value at the 10% percentile within the input frame.
17500 Expressed in range of [0-~181.02].
17503 Display the average saturation value within the input frame. Expressed in range
17507 Display the saturation value at the 90% percentile within the input frame.
17508 Expressed in range of [0-~181.02].
17511 Display the maximum saturation value contained within the input frame.
17512 Expressed in range of [0-~181.02].
17515 Display the median value for hue within the input frame. Expressed in range of
17519 Display the average value for hue within the input frame. Expressed in range of
17523 Display the average of sample value difference between all values of the Y
17524 plane in the current frame and corresponding values of the previous input frame.
17525 Expressed in range of [0-255].
17528 Display the average of sample value difference between all values of the U
17529 plane in the current frame and corresponding values of the previous input frame.
17530 Expressed in range of [0-255].
17533 Display the average of sample value difference between all values of the V
17534 plane in the current frame and corresponding values of the previous input frame.
17535 Expressed in range of [0-255].
17538 Display bit depth of Y plane in current frame.
17539 Expressed in range of [0-16].
17542 Display bit depth of U plane in current frame.
17543 Expressed in range of [0-16].
17546 Display bit depth of V plane in current frame.
17547 Expressed in range of [0-16].
17550 The filter accepts the following options:
17556 @option{stat} specify an additional form of image analysis.
17557 @option{out} output video with the specified type of pixel highlighted.
17559 Both options accept the following values:
17563 Identify @var{temporal outliers} pixels. A @var{temporal outlier} is a pixel
17564 unlike the neighboring pixels of the same field. Examples of temporal outliers
17565 include the results of video dropouts, head clogs, or tape tracking issues.
17568 Identify @var{vertical line repetition}. Vertical line repetition includes
17569 similar rows of pixels within a frame. In born-digital video vertical line
17570 repetition is common, but this pattern is uncommon in video digitized from an
17571 analog source. When it occurs in video that results from the digitization of an
17572 analog source it can indicate concealment from a dropout compensator.
17575 Identify pixels that fall outside of legal broadcast range.
17579 Set the highlight color for the @option{out} option. The default color is
17583 @subsection Examples
17587 Output data of various video metrics:
17589 ffprobe -f lavfi movie=example.mov,signalstats="stat=tout+vrep+brng" -show_frames
17593 Output specific data about the minimum and maximum values of the Y plane per frame:
17595 ffprobe -f lavfi movie=example.mov,signalstats -show_entries frame_tags=lavfi.signalstats.YMAX,lavfi.signalstats.YMIN
17599 Playback video while highlighting pixels that are outside of broadcast range in red.
17601 ffplay example.mov -vf signalstats="out=brng:color=red"
17605 Playback video with signalstats metadata drawn over the frame.
17607 ffplay example.mov -vf signalstats=stat=brng+vrep+tout,drawtext=fontfile=FreeSerif.ttf:textfile=signalstat_drawtext.txt
17610 The contents of signalstat_drawtext.txt used in the command are:
17613 Y (%@{metadata:lavfi.signalstats.YMIN@}-%@{metadata:lavfi.signalstats.YMAX@})
17614 U (%@{metadata:lavfi.signalstats.UMIN@}-%@{metadata:lavfi.signalstats.UMAX@})
17615 V (%@{metadata:lavfi.signalstats.VMIN@}-%@{metadata:lavfi.signalstats.VMAX@})
17616 saturation maximum: %@{metadata:lavfi.signalstats.SATMAX@}
17624 Calculates the MPEG-7 Video Signature. The filter can handle more than one
17625 input. In this case the matching between the inputs can be calculated additionally.
17626 The filter always passes through the first input. The signature of each stream can
17627 be written into a file.
17629 It accepts the following options:
17633 Enable or disable the matching process.
17635 Available values are:
17639 Disable the calculation of a matching (default).
17641 Calculate the matching for the whole video and output whether the whole video
17642 matches or only parts.
17644 Calculate only until a matching is found or the video ends. Should be faster in
17649 Set the number of inputs. The option value must be a non negative integer.
17650 Default value is 1.
17653 Set the path to which the output is written. If there is more than one input,
17654 the path must be a prototype, i.e. must contain %d or %0nd (where n is a positive
17655 integer), that will be replaced with the input number. If no filename is
17656 specified, no output will be written. This is the default.
17659 Choose the output format.
17661 Available values are:
17665 Use the specified binary representation (default).
17667 Use the specified xml representation.
17671 Set threshold to detect one word as similar. The option value must be an integer
17672 greater than zero. The default value is 9000.
17675 Set threshold to detect all words as similar. The option value must be an integer
17676 greater than zero. The default value is 60000.
17679 Set threshold to detect frames as similar. The option value must be an integer
17680 greater than zero. The default value is 116.
17683 Set the minimum length of a sequence in frames to recognize it as matching
17684 sequence. The option value must be a non negative integer value.
17685 The default value is 0.
17688 Set the minimum relation, that matching frames to all frames must have.
17689 The option value must be a double value between 0 and 1. The default value is 0.5.
17692 @subsection Examples
17696 To calculate the signature of an input video and store it in signature.bin:
17698 ffmpeg -i input.mkv -vf signature=filename=signature.bin -map 0:v -f null -
17702 To detect whether two videos match and store the signatures in XML format in
17703 signature0.xml and signature1.xml:
17705 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 -
17713 Blur the input video without impacting the outlines.
17715 It accepts the following options:
17718 @item luma_radius, lr
17719 Set the luma radius. The option value must be a float number in
17720 the range [0.1,5.0] that specifies the variance of the gaussian filter
17721 used to blur the image (slower if larger). Default value is 1.0.
17723 @item luma_strength, ls
17724 Set the luma strength. The option value must be a float number
17725 in the range [-1.0,1.0] that configures the blurring. A value included
17726 in [0.0,1.0] will blur the image whereas a value included in
17727 [-1.0,0.0] will sharpen the image. Default value is 1.0.
17729 @item luma_threshold, lt
17730 Set the luma threshold used as a coefficient to determine
17731 whether a pixel should be blurred or not. The option value must be an
17732 integer in the range [-30,30]. A value of 0 will filter all the image,
17733 a value included in [0,30] will filter flat areas and a value included
17734 in [-30,0] will filter edges. Default value is 0.
17736 @item chroma_radius, cr
17737 Set the chroma radius. The option value must be a float number in
17738 the range [0.1,5.0] that specifies the variance of the gaussian filter
17739 used to blur the image (slower if larger). Default value is @option{luma_radius}.
17741 @item chroma_strength, cs
17742 Set the chroma strength. The option value must be a float number
17743 in the range [-1.0,1.0] that configures the blurring. A value included
17744 in [0.0,1.0] will blur the image whereas a value included in
17745 [-1.0,0.0] will sharpen the image. Default value is @option{luma_strength}.
17747 @item chroma_threshold, ct
17748 Set the chroma threshold used as a coefficient to determine
17749 whether a pixel should be blurred or not. The option value must be an
17750 integer in the range [-30,30]. A value of 0 will filter all the image,
17751 a value included in [0,30] will filter flat areas and a value included
17752 in [-30,0] will filter edges. Default value is @option{luma_threshold}.
17755 If a chroma option is not explicitly set, the corresponding luma value
17759 Apply sobel operator to input video stream.
17761 The filter accepts the following option:
17765 Set which planes will be processed, unprocessed planes will be copied.
17766 By default value 0xf, all planes will be processed.
17769 Set value which will be multiplied with filtered result.
17772 Set value which will be added to filtered result.
17778 Apply a simple postprocessing filter that compresses and decompresses the image
17779 at several (or - in the case of @option{quality} level @code{6} - all) shifts
17780 and average the results.
17782 The filter accepts the following options:
17786 Set quality. This option defines the number of levels for averaging. It accepts
17787 an integer in the range 0-6. If set to @code{0}, the filter will have no
17788 effect. A value of @code{6} means the higher quality. For each increment of
17789 that value the speed drops by a factor of approximately 2. Default value is
17793 Force a constant quantization parameter. If not set, the filter will use the QP
17794 from the video stream (if available).
17797 Set thresholding mode. Available modes are:
17801 Set hard thresholding (default).
17803 Set soft thresholding (better de-ringing effect, but likely blurrier).
17806 @item use_bframe_qp
17807 Enable the use of the QP from the B-Frames if set to @code{1}. Using this
17808 option may cause flicker since the B-Frames have often larger QP. Default is
17809 @code{0} (not enabled).
17812 @subsection Commands
17814 This filter supports the following commands:
17816 @item quality, level
17817 Set quality level. The value @code{max} can be used to set the maximum level,
17818 currently @code{6}.
17824 Scale the input by applying one of the super-resolution methods based on
17825 convolutional neural networks. Supported models:
17829 Super-Resolution Convolutional Neural Network model (SRCNN).
17830 See @url{https://arxiv.org/abs/1501.00092}.
17833 Efficient Sub-Pixel Convolutional Neural Network model (ESPCN).
17834 See @url{https://arxiv.org/abs/1609.05158}.
17837 Training scripts as well as scripts for model file (.pb) saving can be found at
17838 @url{https://github.com/XueweiMeng/sr/tree/sr_dnn_native}. Original repository
17839 is at @url{https://github.com/HighVoltageRocknRoll/sr.git}.
17841 Native model files (.model) can be generated from TensorFlow model
17842 files (.pb) by using tools/python/convert.py
17844 The filter accepts the following options:
17848 Specify which DNN backend to use for model loading and execution. This option accepts
17849 the following values:
17853 Native implementation of DNN loading and execution.
17856 TensorFlow backend. To enable this backend you
17857 need to install the TensorFlow for C library (see
17858 @url{https://www.tensorflow.org/install/install_c}) and configure FFmpeg with
17859 @code{--enable-libtensorflow}
17862 Default value is @samp{native}.
17865 Set path to model file specifying network architecture and its parameters.
17866 Note that different backends use different file formats. TensorFlow backend
17867 can load files for both formats, while native backend can load files for only
17871 Set scale factor for SRCNN model. Allowed values are @code{2}, @code{3} and @code{4}.
17872 Default value is @code{2}. Scale factor is necessary for SRCNN model, because it accepts
17873 input upscaled using bicubic upscaling with proper scale factor.
17876 This feature can also be finished with @ref{dnn_processing} filter.
17880 Obtain the SSIM (Structural SImilarity Metric) between two input videos.
17882 This filter takes in input two input videos, the first input is
17883 considered the "main" source and is passed unchanged to the
17884 output. The second input is used as a "reference" video for computing
17887 Both video inputs must have the same resolution and pixel format for
17888 this filter to work correctly. Also it assumes that both inputs
17889 have the same number of frames, which are compared one by one.
17891 The filter stores the calculated SSIM of each frame.
17893 The description of the accepted parameters follows.
17896 @item stats_file, f
17897 If specified the filter will use the named file to save the SSIM of
17898 each individual frame. When filename equals "-" the data is sent to
17902 The file printed if @var{stats_file} is selected, contains a sequence of
17903 key/value pairs of the form @var{key}:@var{value} for each compared
17906 A description of each shown parameter follows:
17910 sequential number of the input frame, starting from 1
17912 @item Y, U, V, R, G, B
17913 SSIM of the compared frames for the component specified by the suffix.
17916 SSIM of the compared frames for the whole frame.
17919 Same as above but in dB representation.
17922 This filter also supports the @ref{framesync} options.
17924 @subsection Examples
17929 movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
17930 [main][ref] ssim="stats_file=stats.log" [out]
17933 On this example the input file being processed is compared with the
17934 reference file @file{ref_movie.mpg}. The SSIM of each individual frame
17935 is stored in @file{stats.log}.
17938 Another example with both psnr and ssim at same time:
17940 ffmpeg -i main.mpg -i ref.mpg -lavfi "ssim;[0:v][1:v]psnr" -f null -
17944 Another example with different containers:
17946 ffmpeg -i main.mpg -i ref.mkv -lavfi "[0:v]settb=AVTB,setpts=PTS-STARTPTS[main];[1:v]settb=AVTB,setpts=PTS-STARTPTS[ref];[main][ref]ssim" -f null -
17952 Convert between different stereoscopic image formats.
17954 The filters accept the following options:
17958 Set stereoscopic image format of input.
17960 Available values for input image formats are:
17963 side by side parallel (left eye left, right eye right)
17966 side by side crosseye (right eye left, left eye right)
17969 side by side parallel with half width resolution
17970 (left eye left, right eye right)
17973 side by side crosseye with half width resolution
17974 (right eye left, left eye right)
17978 above-below (left eye above, right eye below)
17982 above-below (right eye above, left eye below)
17986 above-below with half height resolution
17987 (left eye above, right eye below)
17991 above-below with half height resolution
17992 (right eye above, left eye below)
17995 alternating frames (left eye first, right eye second)
17998 alternating frames (right eye first, left eye second)
18001 interleaved rows (left eye has top row, right eye starts on next row)
18004 interleaved rows (right eye has top row, left eye starts on next row)
18007 interleaved columns, left eye first
18010 interleaved columns, right eye first
18012 Default value is @samp{sbsl}.
18016 Set stereoscopic image format of output.
18020 side by side parallel (left eye left, right eye right)
18023 side by side crosseye (right eye left, left eye right)
18026 side by side parallel with half width resolution
18027 (left eye left, right eye right)
18030 side by side crosseye with half width resolution
18031 (right eye left, left eye right)
18035 above-below (left eye above, right eye below)
18039 above-below (right eye above, left eye below)
18043 above-below with half height resolution
18044 (left eye above, right eye below)
18048 above-below with half height resolution
18049 (right eye above, left eye below)
18052 alternating frames (left eye first, right eye second)
18055 alternating frames (right eye first, left eye second)
18058 interleaved rows (left eye has top row, right eye starts on next row)
18061 interleaved rows (right eye has top row, left eye starts on next row)
18064 anaglyph red/blue gray
18065 (red filter on left eye, blue filter on right eye)
18068 anaglyph red/green gray
18069 (red filter on left eye, green filter on right eye)
18072 anaglyph red/cyan gray
18073 (red filter on left eye, cyan filter on right eye)
18076 anaglyph red/cyan half colored
18077 (red filter on left eye, cyan filter on right eye)
18080 anaglyph red/cyan color
18081 (red filter on left eye, cyan filter on right eye)
18084 anaglyph red/cyan color optimized with the least squares projection of dubois
18085 (red filter on left eye, cyan filter on right eye)
18088 anaglyph green/magenta gray
18089 (green filter on left eye, magenta filter on right eye)
18092 anaglyph green/magenta half colored
18093 (green filter on left eye, magenta filter on right eye)
18096 anaglyph green/magenta colored
18097 (green filter on left eye, magenta filter on right eye)
18100 anaglyph green/magenta color optimized with the least squares projection of dubois
18101 (green filter on left eye, magenta filter on right eye)
18104 anaglyph yellow/blue gray
18105 (yellow filter on left eye, blue filter on right eye)
18108 anaglyph yellow/blue half colored
18109 (yellow filter on left eye, blue filter on right eye)
18112 anaglyph yellow/blue colored
18113 (yellow filter on left eye, blue filter on right eye)
18116 anaglyph yellow/blue color optimized with the least squares projection of dubois
18117 (yellow filter on left eye, blue filter on right eye)
18120 mono output (left eye only)
18123 mono output (right eye only)
18126 checkerboard, left eye first
18129 checkerboard, right eye first
18132 interleaved columns, left eye first
18135 interleaved columns, right eye first
18141 Default value is @samp{arcd}.
18144 @subsection Examples
18148 Convert input video from side by side parallel to anaglyph yellow/blue dubois:
18154 Convert input video from above below (left eye above, right eye below) to side by side crosseye.
18160 @section streamselect, astreamselect
18161 Select video or audio streams.
18163 The filter accepts the following options:
18167 Set number of inputs. Default is 2.
18170 Set input indexes to remap to outputs.
18173 @subsection Commands
18175 The @code{streamselect} and @code{astreamselect} filter supports the following
18180 Set input indexes to remap to outputs.
18183 @subsection Examples
18187 Select first 5 seconds 1st stream and rest of time 2nd stream:
18189 sendcmd='5.0 streamselect map 1',streamselect=inputs=2:map=0
18193 Same as above, but for audio:
18195 asendcmd='5.0 astreamselect map 1',astreamselect=inputs=2:map=0
18202 Draw subtitles on top of input video using the libass library.
18204 To enable compilation of this filter you need to configure FFmpeg with
18205 @code{--enable-libass}. This filter also requires a build with libavcodec and
18206 libavformat to convert the passed subtitles file to ASS (Advanced Substation
18207 Alpha) subtitles format.
18209 The filter accepts the following options:
18213 Set the filename of the subtitle file to read. It must be specified.
18215 @item original_size
18216 Specify the size of the original video, the video for which the ASS file
18217 was composed. For the syntax of this option, check the
18218 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
18219 Due to a misdesign in ASS aspect ratio arithmetic, this is necessary to
18220 correctly scale the fonts if the aspect ratio has been changed.
18223 Set a directory path containing fonts that can be used by the filter.
18224 These fonts will be used in addition to whatever the font provider uses.
18227 Process alpha channel, by default alpha channel is untouched.
18230 Set subtitles input character encoding. @code{subtitles} filter only. Only
18231 useful if not UTF-8.
18233 @item stream_index, si
18234 Set subtitles stream index. @code{subtitles} filter only.
18237 Override default style or script info parameters of the subtitles. It accepts a
18238 string containing ASS style format @code{KEY=VALUE} couples separated by ",".
18241 If the first key is not specified, it is assumed that the first value
18242 specifies the @option{filename}.
18244 For example, to render the file @file{sub.srt} on top of the input
18245 video, use the command:
18250 which is equivalent to:
18252 subtitles=filename=sub.srt
18255 To render the default subtitles stream from file @file{video.mkv}, use:
18257 subtitles=video.mkv
18260 To render the second subtitles stream from that file, use:
18262 subtitles=video.mkv:si=1
18265 To make the subtitles stream from @file{sub.srt} appear in 80% transparent blue
18266 @code{DejaVu Serif}, use:
18268 subtitles=sub.srt:force_style='Fontname=DejaVu Serif,PrimaryColour=&HCCFF0000'
18271 @section super2xsai
18273 Scale the input by 2x and smooth using the Super2xSaI (Scale and
18274 Interpolate) pixel art scaling algorithm.
18276 Useful for enlarging pixel art images without reducing sharpness.
18280 Swap two rectangular objects in video.
18282 This filter accepts the following options:
18292 Set 1st rect x coordinate.
18295 Set 1st rect y coordinate.
18298 Set 2nd rect x coordinate.
18301 Set 2nd rect y coordinate.
18303 All expressions are evaluated once for each frame.
18306 The all options are expressions containing the following constants:
18311 The input width and height.
18314 same as @var{w} / @var{h}
18317 input sample aspect ratio
18320 input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
18323 The number of the input frame, starting from 0.
18326 The timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
18329 the position in the file of the input frame, NAN if unknown
18336 Blend successive video frames.
18342 Apply telecine process to the video.
18344 This filter accepts the following options:
18353 The default value is @code{top}.
18357 A string of numbers representing the pulldown pattern you wish to apply.
18358 The default value is @code{23}.
18362 Some typical patterns:
18367 24p: 2332 (preferred)
18374 24p: 222222222223 ("Euro pulldown")
18379 @section thistogram
18381 Compute and draw a color distribution histogram for the input video across time.
18383 Unlike @ref{histogram} video filter which only shows histogram of single input frame
18384 at certain time, this filter shows also past histograms of number of frames defined
18385 by @code{width} option.
18387 The computed histogram is a representation of the color component
18388 distribution in an image.
18390 The filter accepts the following options:
18394 Set width of single color component output. Default value is @code{0}.
18395 Value of @code{0} means width will be picked from input video.
18396 This also set number of passed histograms to keep.
18397 Allowed range is [0, 8192].
18399 @item display_mode, d
18401 It accepts the following values:
18404 Per color component graphs are placed below each other.
18407 Per color component graphs are placed side by side.
18410 Presents information identical to that in the @code{parade}, except
18411 that the graphs representing color components are superimposed directly
18414 Default is @code{stack}.
18416 @item levels_mode, m
18417 Set mode. Can be either @code{linear}, or @code{logarithmic}.
18418 Default is @code{linear}.
18420 @item components, c
18421 Set what color components to display.
18422 Default is @code{7}.
18425 Set background opacity. Default is @code{0.9}.
18428 Show envelope. Default is disabled.
18431 Set envelope color. Default is @code{gold}.
18436 Available values for slide is:
18439 Draw new frame when right border is reached.
18442 Replace old columns with new ones.
18445 Scroll from right to left.
18448 Scroll from left to right.
18451 Draw single picture.
18454 Default is @code{replace}.
18459 Apply threshold effect to video stream.
18461 This filter needs four video streams to perform thresholding.
18462 First stream is stream we are filtering.
18463 Second stream is holding threshold values, third stream is holding min values,
18464 and last, fourth stream is holding max values.
18466 The filter accepts the following option:
18470 Set which planes will be processed, unprocessed planes will be copied.
18471 By default value 0xf, all planes will be processed.
18474 For example if first stream pixel's component value is less then threshold value
18475 of pixel component from 2nd threshold stream, third stream value will picked,
18476 otherwise fourth stream pixel component value will be picked.
18478 Using color source filter one can perform various types of thresholding:
18480 @subsection Examples
18484 Binary threshold, using gray color as threshold:
18486 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=black -f lavfi -i color=white -lavfi threshold output.avi
18490 Inverted binary threshold, using gray color as threshold:
18492 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -f lavfi -i color=black -lavfi threshold output.avi
18496 Truncate binary threshold, using gray color as threshold:
18498 ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=gray -lavfi threshold output.avi
18502 Threshold to zero, using gray color as threshold:
18504 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -i 320x240.avi -lavfi threshold output.avi
18508 Inverted threshold to zero, using gray color as threshold:
18510 ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=white -lavfi threshold output.avi
18515 Select the most representative frame in a given sequence of consecutive frames.
18517 The filter accepts the following options:
18521 Set the frames batch size to analyze; in a set of @var{n} frames, the filter
18522 will pick one of them, and then handle the next batch of @var{n} frames until
18523 the end. Default is @code{100}.
18526 Since the filter keeps track of the whole frames sequence, a bigger @var{n}
18527 value will result in a higher memory usage, so a high value is not recommended.
18529 @subsection Examples
18533 Extract one picture each 50 frames:
18539 Complete example of a thumbnail creation with @command{ffmpeg}:
18541 ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png
18548 Tile several successive frames together.
18550 The @ref{untile} filter can do the reverse.
18552 The filter accepts the following options:
18557 Set the grid size (i.e. the number of lines and columns). For the syntax of
18558 this option, check the
18559 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
18562 Set the maximum number of frames to render in the given area. It must be less
18563 than or equal to @var{w}x@var{h}. The default value is @code{0}, meaning all
18564 the area will be used.
18567 Set the outer border margin in pixels.
18570 Set the inner border thickness (i.e. the number of pixels between frames). For
18571 more advanced padding options (such as having different values for the edges),
18572 refer to the pad video filter.
18575 Specify the color of the unused area. For the syntax of this option, check the
18576 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
18577 The default value of @var{color} is "black".
18580 Set the number of frames to overlap when tiling several successive frames together.
18581 The value must be between @code{0} and @var{nb_frames - 1}.
18584 Set the number of frames to initially be empty before displaying first output frame.
18585 This controls how soon will one get first output frame.
18586 The value must be between @code{0} and @var{nb_frames - 1}.
18589 @subsection Examples
18593 Produce 8x8 PNG tiles of all keyframes (@option{-skip_frame nokey}) in a movie:
18595 ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -vsync 0 keyframes%03d.png
18597 The @option{-vsync 0} is necessary to prevent @command{ffmpeg} from
18598 duplicating each output frame to accommodate the originally detected frame
18602 Display @code{5} pictures in an area of @code{3x2} frames,
18603 with @code{7} pixels between them, and @code{2} pixels of initial margin, using
18604 mixed flat and named options:
18606 tile=3x2:nb_frames=5:padding=7:margin=2
18610 @section tinterlace
18612 Perform various types of temporal field interlacing.
18614 Frames are counted starting from 1, so the first input frame is
18617 The filter accepts the following options:
18622 Specify the mode of the interlacing. This option can also be specified
18623 as a value alone. See below for a list of values for this option.
18625 Available values are:
18629 Move odd frames into the upper field, even into the lower field,
18630 generating a double height frame at half frame rate.
18634 Frame 1 Frame 2 Frame 3 Frame 4
18636 11111 22222 33333 44444
18637 11111 22222 33333 44444
18638 11111 22222 33333 44444
18639 11111 22222 33333 44444
18653 Only output odd frames, even frames are dropped, generating a frame with
18654 unchanged height at half frame rate.
18659 Frame 1 Frame 2 Frame 3 Frame 4
18661 11111 22222 33333 44444
18662 11111 22222 33333 44444
18663 11111 22222 33333 44444
18664 11111 22222 33333 44444
18674 Only output even frames, odd frames are dropped, generating a frame with
18675 unchanged height at half frame rate.
18680 Frame 1 Frame 2 Frame 3 Frame 4
18682 11111 22222 33333 44444
18683 11111 22222 33333 44444
18684 11111 22222 33333 44444
18685 11111 22222 33333 44444
18695 Expand each frame to full height, but pad alternate lines with black,
18696 generating a frame with double height at the same input frame rate.
18701 Frame 1 Frame 2 Frame 3 Frame 4
18703 11111 22222 33333 44444
18704 11111 22222 33333 44444
18705 11111 22222 33333 44444
18706 11111 22222 33333 44444
18709 11111 ..... 33333 .....
18710 ..... 22222 ..... 44444
18711 11111 ..... 33333 .....
18712 ..... 22222 ..... 44444
18713 11111 ..... 33333 .....
18714 ..... 22222 ..... 44444
18715 11111 ..... 33333 .....
18716 ..... 22222 ..... 44444
18720 @item interleave_top, 4
18721 Interleave the upper field from odd frames with the lower field from
18722 even frames, generating a frame with unchanged height at half frame rate.
18727 Frame 1 Frame 2 Frame 3 Frame 4
18729 11111<- 22222 33333<- 44444
18730 11111 22222<- 33333 44444<-
18731 11111<- 22222 33333<- 44444
18732 11111 22222<- 33333 44444<-
18742 @item interleave_bottom, 5
18743 Interleave the lower field from odd frames with the upper field from
18744 even frames, generating a frame with unchanged height at half frame rate.
18749 Frame 1 Frame 2 Frame 3 Frame 4
18751 11111 22222<- 33333 44444<-
18752 11111<- 22222 33333<- 44444
18753 11111 22222<- 33333 44444<-
18754 11111<- 22222 33333<- 44444
18764 @item interlacex2, 6
18765 Double frame rate with unchanged height. Frames are inserted each
18766 containing the second temporal field from the previous input frame and
18767 the first temporal field from the next input frame. This mode relies on
18768 the top_field_first flag. Useful for interlaced video displays with no
18769 field synchronisation.
18774 Frame 1 Frame 2 Frame 3 Frame 4
18776 11111 22222 33333 44444
18777 11111 22222 33333 44444
18778 11111 22222 33333 44444
18779 11111 22222 33333 44444
18782 11111 22222 22222 33333 33333 44444 44444
18783 11111 11111 22222 22222 33333 33333 44444
18784 11111 22222 22222 33333 33333 44444 44444
18785 11111 11111 22222 22222 33333 33333 44444
18790 Move odd frames into the upper field, even into the lower field,
18791 generating a double height frame at same frame rate.
18796 Frame 1 Frame 2 Frame 3 Frame 4
18798 11111 22222 33333 44444
18799 11111 22222 33333 44444
18800 11111 22222 33333 44444
18801 11111 22222 33333 44444
18804 11111 33333 33333 55555
18805 22222 22222 44444 44444
18806 11111 33333 33333 55555
18807 22222 22222 44444 44444
18808 11111 33333 33333 55555
18809 22222 22222 44444 44444
18810 11111 33333 33333 55555
18811 22222 22222 44444 44444
18816 Numeric values are deprecated but are accepted for backward
18817 compatibility reasons.
18819 Default mode is @code{merge}.
18822 Specify flags influencing the filter process.
18824 Available value for @var{flags} is:
18827 @item low_pass_filter, vlpf
18828 Enable linear vertical low-pass filtering in the filter.
18829 Vertical low-pass filtering is required when creating an interlaced
18830 destination from a progressive source which contains high-frequency
18831 vertical detail. Filtering will reduce interlace 'twitter' and Moire
18834 @item complex_filter, cvlpf
18835 Enable complex vertical low-pass filtering.
18836 This will slightly less reduce interlace 'twitter' and Moire
18837 patterning but better retain detail and subjective sharpness impression.
18840 Bypass already interlaced frames, only adjust the frame rate.
18843 Vertical low-pass filtering and bypassing already interlaced frames can only be
18844 enabled for @option{mode} @var{interleave_top} and @var{interleave_bottom}.
18849 Pick median pixels from several successive input video frames.
18851 The filter accepts the following options:
18855 Set radius of median filter.
18856 Default is 1. Allowed range is from 1 to 127.
18859 Set which planes to filter. Default value is @code{15}, by which all planes are processed.
18862 Set median percentile. Default value is @code{0.5}.
18863 Default value of @code{0.5} will pick always median values, while @code{0} will pick
18864 minimum values, and @code{1} maximum values.
18869 Mix successive video frames.
18871 A description of the accepted options follows.
18875 The number of successive frames to mix. If unspecified, it defaults to 3.
18878 Specify weight of each input video frame.
18879 Each weight is separated by space. If number of weights is smaller than
18880 number of @var{frames} last specified weight will be used for all remaining
18884 Specify scale, if it is set it will be multiplied with sum
18885 of each weight multiplied with pixel values to give final destination
18886 pixel value. By default @var{scale} is auto scaled to sum of weights.
18889 @subsection Examples
18893 Average 7 successive frames:
18895 tmix=frames=7:weights="1 1 1 1 1 1 1"
18899 Apply simple temporal convolution:
18901 tmix=frames=3:weights="-1 3 -1"
18905 Similar as above but only showing temporal differences:
18907 tmix=frames=3:weights="-1 2 -1":scale=1
18913 Tone map colors from different dynamic ranges.
18915 This filter expects data in single precision floating point, as it needs to
18916 operate on (and can output) out-of-range values. Another filter, such as
18917 @ref{zscale}, is needed to convert the resulting frame to a usable format.
18919 The tonemapping algorithms implemented only work on linear light, so input
18920 data should be linearized beforehand (and possibly correctly tagged).
18923 ffmpeg -i INPUT -vf zscale=transfer=linear,tonemap=clip,zscale=transfer=bt709,format=yuv420p OUTPUT
18926 @subsection Options
18927 The filter accepts the following options.
18931 Set the tone map algorithm to use.
18933 Possible values are:
18936 Do not apply any tone map, only desaturate overbright pixels.
18939 Hard-clip any out-of-range values. Use it for perfect color accuracy for
18940 in-range values, while distorting out-of-range values.
18943 Stretch the entire reference gamut to a linear multiple of the display.
18946 Fit a logarithmic transfer between the tone curves.
18949 Preserve overall image brightness with a simple curve, using nonlinear
18950 contrast, which results in flattening details and degrading color accuracy.
18953 Preserve both dark and bright details better than @var{reinhard}, at the cost
18954 of slightly darkening everything. Use it when detail preservation is more
18955 important than color and brightness accuracy.
18958 Smoothly map out-of-range values, while retaining contrast and colors for
18959 in-range material as much as possible. Use it when color accuracy is more
18960 important than detail preservation.
18966 Tune the tone mapping algorithm.
18968 This affects the following algorithms:
18974 Specifies the scale factor to use while stretching.
18978 Specifies the exponent of the function.
18982 Specify an extra linear coefficient to multiply into the signal before clipping.
18986 Specify the local contrast coefficient at the display peak.
18987 Default to 0.5, which means that in-gamut values will be about half as bright
18994 Specify the transition point from linear to mobius transform. Every value
18995 below this point is guaranteed to be mapped 1:1. The higher the value, the
18996 more accurate the result will be, at the cost of losing bright details.
18997 Default to 0.3, which due to the steep initial slope still preserves in-range
18998 colors fairly accurately.
19002 Apply desaturation for highlights that exceed this level of brightness. The
19003 higher the parameter, the more color information will be preserved. This
19004 setting helps prevent unnaturally blown-out colors for super-highlights, by
19005 (smoothly) turning into white instead. This makes images feel more natural,
19006 at the cost of reducing information about out-of-range colors.
19008 The default of 2.0 is somewhat conservative and will mostly just apply to
19009 skies or directly sunlit surfaces. A setting of 0.0 disables this option.
19011 This option works only if the input frame has a supported color tag.
19014 Override signal/nominal/reference peak with this value. Useful when the
19015 embedded peak information in display metadata is not reliable or when tone
19016 mapping from a lower range to a higher range.
19021 Temporarily pad video frames.
19023 The filter accepts the following options:
19027 Specify number of delay frames before input video stream. Default is 0.
19030 Specify number of padding frames after input video stream.
19031 Set to -1 to pad indefinitely. Default is 0.
19034 Set kind of frames added to beginning of stream.
19035 Can be either @var{add} or @var{clone}.
19036 With @var{add} frames of solid-color are added.
19037 With @var{clone} frames are clones of first frame.
19038 Default is @var{add}.
19041 Set kind of frames added to end of stream.
19042 Can be either @var{add} or @var{clone}.
19043 With @var{add} frames of solid-color are added.
19044 With @var{clone} frames are clones of last frame.
19045 Default is @var{add}.
19047 @item start_duration, stop_duration
19048 Specify the duration of the start/stop delay. See
19049 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
19050 for the accepted syntax.
19051 These options override @var{start} and @var{stop}. Default is 0.
19054 Specify the color of the padded area. For the syntax of this option,
19055 check the @ref{color syntax,,"Color" section in the ffmpeg-utils
19056 manual,ffmpeg-utils}.
19058 The default value of @var{color} is "black".
19064 Transpose rows with columns in the input video and optionally flip it.
19066 It accepts the following parameters:
19071 Specify the transposition direction.
19073 Can assume the following values:
19075 @item 0, 4, cclock_flip
19076 Rotate by 90 degrees counterclockwise and vertically flip (default), that is:
19084 Rotate by 90 degrees clockwise, that is:
19092 Rotate by 90 degrees counterclockwise, that is:
19099 @item 3, 7, clock_flip
19100 Rotate by 90 degrees clockwise and vertically flip, that is:
19108 For values between 4-7, the transposition is only done if the input
19109 video geometry is portrait and not landscape. These values are
19110 deprecated, the @code{passthrough} option should be used instead.
19112 Numerical values are deprecated, and should be dropped in favor of
19113 symbolic constants.
19116 Do not apply the transposition if the input geometry matches the one
19117 specified by the specified value. It accepts the following values:
19120 Always apply transposition.
19122 Preserve portrait geometry (when @var{height} >= @var{width}).
19124 Preserve landscape geometry (when @var{width} >= @var{height}).
19127 Default value is @code{none}.
19130 For example to rotate by 90 degrees clockwise and preserve portrait
19133 transpose=dir=1:passthrough=portrait
19136 The command above can also be specified as:
19138 transpose=1:portrait
19141 @section transpose_npp
19143 Transpose rows with columns in the input video and optionally flip it.
19144 For more in depth examples see the @ref{transpose} video filter, which shares mostly the same options.
19146 It accepts the following parameters:
19151 Specify the transposition direction.
19153 Can assume the following values:
19156 Rotate by 90 degrees counterclockwise and vertically flip. (default)
19159 Rotate by 90 degrees clockwise.
19162 Rotate by 90 degrees counterclockwise.
19165 Rotate by 90 degrees clockwise and vertically flip.
19169 Do not apply the transposition if the input geometry matches the one
19170 specified by the specified value. It accepts the following values:
19173 Always apply transposition. (default)
19175 Preserve portrait geometry (when @var{height} >= @var{width}).
19177 Preserve landscape geometry (when @var{width} >= @var{height}).
19183 Trim the input so that the output contains one continuous subpart of the input.
19185 It accepts the following parameters:
19188 Specify the time of the start of the kept section, i.e. the frame with the
19189 timestamp @var{start} will be the first frame in the output.
19192 Specify the time of the first frame that will be dropped, i.e. the frame
19193 immediately preceding the one with the timestamp @var{end} will be the last
19194 frame in the output.
19197 This is the same as @var{start}, except this option sets the start timestamp
19198 in timebase units instead of seconds.
19201 This is the same as @var{end}, except this option sets the end timestamp
19202 in timebase units instead of seconds.
19205 The maximum duration of the output in seconds.
19208 The number of the first frame that should be passed to the output.
19211 The number of the first frame that should be dropped.
19214 @option{start}, @option{end}, and @option{duration} are expressed as time
19215 duration specifications; see
19216 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
19217 for the accepted syntax.
19219 Note that the first two sets of the start/end options and the @option{duration}
19220 option look at the frame timestamp, while the _frame variants simply count the
19221 frames that pass through the filter. Also note that this filter does not modify
19222 the timestamps. If you wish for the output timestamps to start at zero, insert a
19223 setpts filter after the trim filter.
19225 If multiple start or end options are set, this filter tries to be greedy and
19226 keep all the frames that match at least one of the specified constraints. To keep
19227 only the part that matches all the constraints at once, chain multiple trim
19230 The defaults are such that all the input is kept. So it is possible to set e.g.
19231 just the end values to keep everything before the specified time.
19236 Drop everything except the second minute of input:
19238 ffmpeg -i INPUT -vf trim=60:120
19242 Keep only the first second:
19244 ffmpeg -i INPUT -vf trim=duration=1
19249 @section unpremultiply
19250 Apply alpha unpremultiply effect to input video stream using first plane
19251 of second stream as alpha.
19253 Both streams must have same dimensions and same pixel format.
19255 The filter accepts the following option:
19259 Set which planes will be processed, unprocessed planes will be copied.
19260 By default value 0xf, all planes will be processed.
19262 If the format has 1 or 2 components, then luma is bit 0.
19263 If the format has 3 or 4 components:
19264 for RGB formats bit 0 is green, bit 1 is blue and bit 2 is red;
19265 for YUV formats bit 0 is luma, bit 1 is chroma-U and bit 2 is chroma-V.
19266 If present, the alpha channel is always the last bit.
19269 Do not require 2nd input for processing, instead use alpha plane from input stream.
19275 Sharpen or blur the input video.
19277 It accepts the following parameters:
19280 @item luma_msize_x, lx
19281 Set the luma matrix horizontal size. It must be an odd integer between
19282 3 and 23. The default value is 5.
19284 @item luma_msize_y, ly
19285 Set the luma matrix vertical size. It must be an odd integer between 3
19286 and 23. The default value is 5.
19288 @item luma_amount, la
19289 Set the luma effect strength. It must be a floating point number, reasonable
19290 values lay between -1.5 and 1.5.
19292 Negative values will blur the input video, while positive values will
19293 sharpen it, a value of zero will disable the effect.
19295 Default value is 1.0.
19297 @item chroma_msize_x, cx
19298 Set the chroma matrix horizontal size. It must be an odd integer
19299 between 3 and 23. The default value is 5.
19301 @item chroma_msize_y, cy
19302 Set the chroma matrix vertical size. It must be an odd integer
19303 between 3 and 23. The default value is 5.
19305 @item chroma_amount, ca
19306 Set the chroma effect strength. It must be a floating point number, reasonable
19307 values lay between -1.5 and 1.5.
19309 Negative values will blur the input video, while positive values will
19310 sharpen it, a value of zero will disable the effect.
19312 Default value is 0.0.
19316 All parameters are optional and default to the equivalent of the
19317 string '5:5:1.0:5:5:0.0'.
19319 @subsection Examples
19323 Apply strong luma sharpen effect:
19325 unsharp=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5
19329 Apply a strong blur of both luma and chroma parameters:
19331 unsharp=7:7:-2:7:7:-2
19338 Decompose a video made of tiled images into the individual images.
19340 The frame rate of the output video is the frame rate of the input video
19341 multiplied by the number of tiles.
19343 This filter does the reverse of @ref{tile}.
19345 The filter accepts the following options:
19350 Set the grid size (i.e. the number of lines and columns). For the syntax of
19351 this option, check the
19352 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
19355 @subsection Examples
19359 Produce a 1-second video from a still image file made of 25 frames stacked
19360 vertically, like an analogic film reel:
19362 ffmpeg -r 1 -i image.jpg -vf untile=1x25 movie.mkv
19368 Apply ultra slow/simple postprocessing filter that compresses and decompresses
19369 the image at several (or - in the case of @option{quality} level @code{8} - all)
19370 shifts and average the results.
19372 The way this differs from the behavior of spp is that uspp actually encodes &
19373 decodes each case with libavcodec Snow, whereas spp uses a simplified intra only 8x8
19374 DCT similar to MJPEG.
19376 The filter accepts the following options:
19380 Set quality. This option defines the number of levels for averaging. It accepts
19381 an integer in the range 0-8. If set to @code{0}, the filter will have no
19382 effect. A value of @code{8} means the higher quality. For each increment of
19383 that value the speed drops by a factor of approximately 2. Default value is
19387 Force a constant quantization parameter. If not set, the filter will use the QP
19388 from the video stream (if available).
19393 Convert 360 videos between various formats.
19395 The filter accepts the following options:
19401 Set format of the input/output video.
19409 Equirectangular projection.
19414 Cubemap with 3x2/6x1/1x6 layout.
19416 Format specific options:
19421 Set padding proportion for the input/output cubemap. Values in decimals.
19428 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)
19431 Default value is @b{@samp{0}}.
19432 Maximum value is @b{@samp{0.1}}.
19436 Set fixed padding for the input/output cubemap. Values in pixels.
19438 Default value is @b{@samp{0}}. If greater than zero it overrides other padding options.
19442 Set order of faces for the input/output cubemap. Choose one direction for each position.
19444 Designation of directions:
19460 Default value is @b{@samp{rludfb}}.
19464 Set rotation of faces for the input/output cubemap. Choose one angle for each position.
19466 Designation of angles:
19469 0 degrees clockwise
19471 90 degrees clockwise
19473 180 degrees clockwise
19475 270 degrees clockwise
19478 Default value is @b{@samp{000000}}.
19482 Equi-Angular Cubemap.
19489 Format specific options:
19494 Set output horizontal/vertical/diagonal field of view. Values in degrees.
19496 If diagonal field of view is set it overrides horizontal and vertical field of view.
19501 Set input horizontal/vertical/diagonal field of view. Values in degrees.
19503 If diagonal field of view is set it overrides horizontal and vertical field of view.
19509 Format specific options:
19514 Set output horizontal/vertical/diagonal field of view. Values in degrees.
19516 If diagonal field of view is set it overrides horizontal and vertical field of view.
19521 Set input horizontal/vertical/diagonal field of view. Values in degrees.
19523 If diagonal field of view is set it overrides horizontal and vertical field of view.
19529 Facebook's 360 formats.
19532 Stereographic format.
19534 Format specific options:
19539 Set output horizontal/vertical/diagonal field of view. Values in degrees.
19541 If diagonal field of view is set it overrides horizontal and vertical field of view.
19546 Set input horizontal/vertical/diagonal field of view. Values in degrees.
19548 If diagonal field of view is set it overrides horizontal and vertical field of view.
19555 Ball format, gives significant distortion toward the back.
19558 Hammer-Aitoff map projection format.
19561 Sinusoidal map projection format.
19564 Fisheye projection.
19566 Format specific options:
19571 Set output horizontal/vertical/diagonal field of view. Values in degrees.
19573 If diagonal field of view is set it overrides horizontal and vertical field of view.
19578 Set input horizontal/vertical/diagonal field of view. Values in degrees.
19580 If diagonal field of view is set it overrides horizontal and vertical field of view.
19584 Pannini projection.
19586 Format specific options:
19589 Set output pannini parameter.
19592 Set input pannini parameter.
19596 Cylindrical projection.
19598 Format specific options:
19603 Set output horizontal/vertical/diagonal field of view. Values in degrees.
19605 If diagonal field of view is set it overrides horizontal and vertical field of view.
19610 Set input horizontal/vertical/diagonal field of view. Values in degrees.
19612 If diagonal field of view is set it overrides horizontal and vertical field of view.
19616 Perspective projection. @i{(output only)}
19618 Format specific options:
19621 Set perspective parameter.
19625 Tetrahedron projection.
19628 Truncated square pyramid projection.
19632 Half equirectangular projection.
19637 Format specific options:
19642 Set output horizontal/vertical/diagonal field of view. Values in degrees.
19644 If diagonal field of view is set it overrides horizontal and vertical field of view.
19649 Set input horizontal/vertical/diagonal field of view. Values in degrees.
19651 If diagonal field of view is set it overrides horizontal and vertical field of view.
19655 Orthographic format.
19657 Format specific options:
19662 Set output horizontal/vertical/diagonal field of view. Values in degrees.
19664 If diagonal field of view is set it overrides horizontal and vertical field of view.
19669 Set input horizontal/vertical/diagonal field of view. Values in degrees.
19671 If diagonal field of view is set it overrides horizontal and vertical field of view.
19675 Octahedron projection.
19679 Set interpolation method.@*
19680 @i{Note: more complex interpolation methods require much more memory to run.}
19690 Bilinear interpolation.
19692 Lagrange9 interpolation.
19695 Bicubic interpolation.
19698 Lanczos interpolation.
19701 Spline16 interpolation.
19704 Gaussian interpolation.
19706 Mitchell interpolation.
19709 Default value is @b{@samp{line}}.
19713 Set the output video resolution.
19715 Default resolution depends on formats.
19719 Set the input/output stereo format.
19730 Default value is @b{@samp{2d}} for input and output format.
19735 Set rotation for the output video. Values in degrees.
19738 Set rotation order for the output video. Choose one item for each position.
19749 Default value is @b{@samp{ypr}}.
19754 Flip the output video horizontally(swaps left-right)/vertically(swaps up-down)/in-depth(swaps back-forward). Boolean values.
19758 Set if input video is flipped horizontally/vertically. Boolean values.
19761 Set if input video is transposed. Boolean value, by default disabled.
19764 Set if output video needs to be transposed. Boolean value, by default disabled.
19767 Build mask in alpha plane for all unmapped pixels by marking them fully transparent. Boolean value, by default disabled.
19770 @subsection Examples
19774 Convert equirectangular video to cubemap with 3x2 layout and 1% padding using bicubic interpolation:
19776 ffmpeg -i input.mkv -vf v360=e:c3x2:cubic:out_pad=0.01 output.mkv
19779 Extract back view of Equi-Angular Cubemap:
19781 ffmpeg -i input.mkv -vf v360=eac:flat:yaw=180 output.mkv
19784 Convert transposed and horizontally flipped Equi-Angular Cubemap in side-by-side stereo format to equirectangular top-bottom stereo format:
19786 v360=eac:equirect:in_stereo=sbs:in_trans=1:ih_flip=1:out_stereo=tb
19790 @subsection Commands
19792 This filter supports subset of above options as @ref{commands}.
19794 @section vaguedenoiser
19796 Apply a wavelet based denoiser.
19798 It transforms each frame from the video input into the wavelet domain,
19799 using Cohen-Daubechies-Feauveau 9/7. Then it applies some filtering to
19800 the obtained coefficients. It does an inverse wavelet transform after.
19801 Due to wavelet properties, it should give a nice smoothed result, and
19802 reduced noise, without blurring picture features.
19804 This filter accepts the following options:
19808 The filtering strength. The higher, the more filtered the video will be.
19809 Hard thresholding can use a higher threshold than soft thresholding
19810 before the video looks overfiltered. Default value is 2.
19813 The filtering method the filter will use.
19815 It accepts the following values:
19818 All values under the threshold will be zeroed.
19821 All values under the threshold will be zeroed. All values above will be
19822 reduced by the threshold.
19825 Scales or nullifies coefficients - intermediary between (more) soft and
19826 (less) hard thresholding.
19829 Default is garrote.
19832 Number of times, the wavelet will decompose the picture. Picture can't
19833 be decomposed beyond a particular point (typically, 8 for a 640x480
19834 frame - as 2^9 = 512 > 480). Valid values are integers between 1 and 32. Default value is 6.
19837 Partial of full denoising (limited coefficients shrinking), from 0 to 100. Default value is 85.
19840 A list of the planes to process. By default all planes are processed.
19843 The threshold type the filter will use.
19845 It accepts the following values:
19848 Threshold used is same for all decompositions.
19851 Threshold used depends also on each decomposition coefficients.
19854 Default is universal.
19857 @section vectorscope
19859 Display 2 color component values in the two dimensional graph (which is called
19862 This filter accepts the following options:
19866 Set vectorscope mode.
19868 It accepts the following values:
19872 Gray values are displayed on graph, higher brightness means more pixels have
19873 same component color value on location in graph. This is the default mode.
19876 Gray values are displayed on graph. Surrounding pixels values which are not
19877 present in video frame are drawn in gradient of 2 color components which are
19878 set by option @code{x} and @code{y}. The 3rd color component is static.
19881 Actual color components values present in video frame are displayed on graph.
19884 Similar as color2 but higher frequency of same values @code{x} and @code{y}
19885 on graph increases value of another color component, which is luminance by
19886 default values of @code{x} and @code{y}.
19889 Actual colors present in video frame are displayed on graph. If two different
19890 colors map to same position on graph then color with higher value of component
19891 not present in graph is picked.
19894 Gray values are displayed on graph. Similar to @code{color} but with 3rd color
19895 component picked from radial gradient.
19899 Set which color component will be represented on X-axis. Default is @code{1}.
19902 Set which color component will be represented on Y-axis. Default is @code{2}.
19905 Set intensity, used by modes: gray, color, color3 and color5 for increasing brightness
19906 of color component which represents frequency of (X, Y) location in graph.
19911 No envelope, this is default.
19914 Instant envelope, even darkest single pixel will be clearly highlighted.
19917 Hold maximum and minimum values presented in graph over time. This way you
19918 can still spot out of range values without constantly looking at vectorscope.
19921 Peak and instant envelope combined together.
19925 Set what kind of graticule to draw.
19934 Set graticule opacity.
19937 Set graticule flags.
19941 Draw graticule for white point.
19944 Draw graticule for black point.
19947 Draw color points short names.
19951 Set background opacity.
19953 @item lthreshold, l
19954 Set low threshold for color component not represented on X or Y axis.
19955 Values lower than this value will be ignored. Default is 0.
19956 Note this value is multiplied with actual max possible value one pixel component
19957 can have. So for 8-bit input and low threshold value of 0.1 actual threshold
19960 @item hthreshold, h
19961 Set high threshold for color component not represented on X or Y axis.
19962 Values higher than this value will be ignored. Default is 1.
19963 Note this value is multiplied with actual max possible value one pixel component
19964 can have. So for 8-bit input and high threshold value of 0.9 actual threshold
19965 is 0.9 * 255 = 230.
19967 @item colorspace, c
19968 Set what kind of colorspace to use when drawing graticule.
19978 Set color tint for gray/tint vectorscope mode. By default both options are zero.
19979 This means no tint, and output will remain gray.
19982 @anchor{vidstabdetect}
19983 @section vidstabdetect
19985 Analyze video stabilization/deshaking. Perform pass 1 of 2, see
19986 @ref{vidstabtransform} for pass 2.
19988 This filter generates a file with relative translation and rotation
19989 transform information about subsequent frames, which is then used by
19990 the @ref{vidstabtransform} filter.
19992 To enable compilation of this filter you need to configure FFmpeg with
19993 @code{--enable-libvidstab}.
19995 This filter accepts the following options:
19999 Set the path to the file used to write the transforms information.
20000 Default value is @file{transforms.trf}.
20003 Set how shaky the video is and how quick the camera is. It accepts an
20004 integer in the range 1-10, a value of 1 means little shakiness, a
20005 value of 10 means strong shakiness. Default value is 5.
20008 Set the accuracy of the detection process. It must be a value in the
20009 range 1-15. A value of 1 means low accuracy, a value of 15 means high
20010 accuracy. Default value is 15.
20013 Set stepsize of the search process. The region around minimum is
20014 scanned with 1 pixel resolution. Default value is 6.
20017 Set minimum contrast. Below this value a local measurement field is
20018 discarded. Must be a floating point value in the range 0-1. Default
20022 Set reference frame number for tripod mode.
20024 If enabled, the motion of the frames is compared to a reference frame
20025 in the filtered stream, identified by the specified number. The idea
20026 is to compensate all movements in a more-or-less static scene and keep
20027 the camera view absolutely still.
20029 If set to 0, it is disabled. The frames are counted starting from 1.
20032 Show fields and transforms in the resulting frames. It accepts an
20033 integer in the range 0-2. Default value is 0, which disables any
20037 @subsection Examples
20041 Use default values:
20047 Analyze strongly shaky movie and put the results in file
20048 @file{mytransforms.trf}:
20050 vidstabdetect=shakiness=10:accuracy=15:result="mytransforms.trf"
20054 Visualize the result of internal transformations in the resulting
20057 vidstabdetect=show=1
20061 Analyze a video with medium shakiness using @command{ffmpeg}:
20063 ffmpeg -i input -vf vidstabdetect=shakiness=5:show=1 dummy.avi
20067 @anchor{vidstabtransform}
20068 @section vidstabtransform
20070 Video stabilization/deshaking: pass 2 of 2,
20071 see @ref{vidstabdetect} for pass 1.
20073 Read a file with transform information for each frame and
20074 apply/compensate them. Together with the @ref{vidstabdetect}
20075 filter this can be used to deshake videos. See also
20076 @url{http://public.hronopik.de/vid.stab}. It is important to also use
20077 the @ref{unsharp} filter, see below.
20079 To enable compilation of this filter you need to configure FFmpeg with
20080 @code{--enable-libvidstab}.
20082 @subsection Options
20086 Set path to the file used to read the transforms. Default value is
20087 @file{transforms.trf}.
20090 Set the number of frames (value*2 + 1) used for lowpass filtering the
20091 camera movements. Default value is 10.
20093 For example a number of 10 means that 21 frames are used (10 in the
20094 past and 10 in the future) to smoothen the motion in the video. A
20095 larger value leads to a smoother video, but limits the acceleration of
20096 the camera (pan/tilt movements). 0 is a special case where a static
20097 camera is simulated.
20100 Set the camera path optimization algorithm.
20102 Accepted values are:
20105 gaussian kernel low-pass filter on camera motion (default)
20107 averaging on transformations
20111 Set maximal number of pixels to translate frames. Default value is -1,
20115 Set maximal angle in radians (degree*PI/180) to rotate frames. Default
20116 value is -1, meaning no limit.
20119 Specify how to deal with borders that may be visible due to movement
20122 Available values are:
20125 keep image information from previous frame (default)
20127 fill the border black
20131 Invert transforms if set to 1. Default value is 0.
20134 Consider transforms as relative to previous frame if set to 1,
20135 absolute if set to 0. Default value is 0.
20138 Set percentage to zoom. A positive value will result in a zoom-in
20139 effect, a negative value in a zoom-out effect. Default value is 0 (no
20143 Set optimal zooming to avoid borders.
20145 Accepted values are:
20150 optimal static zoom value is determined (only very strong movements
20151 will lead to visible borders) (default)
20153 optimal adaptive zoom value is determined (no borders will be
20154 visible), see @option{zoomspeed}
20157 Note that the value given at zoom is added to the one calculated here.
20160 Set percent to zoom maximally each frame (enabled when
20161 @option{optzoom} is set to 2). Range is from 0 to 5, default value is
20165 Specify type of interpolation.
20167 Available values are:
20172 linear only horizontal
20174 linear in both directions (default)
20176 cubic in both directions (slow)
20180 Enable virtual tripod mode if set to 1, which is equivalent to
20181 @code{relative=0:smoothing=0}. Default value is 0.
20183 Use also @code{tripod} option of @ref{vidstabdetect}.
20186 Increase log verbosity if set to 1. Also the detected global motions
20187 are written to the temporary file @file{global_motions.trf}. Default
20191 @subsection Examples
20195 Use @command{ffmpeg} for a typical stabilization with default values:
20197 ffmpeg -i inp.mpeg -vf vidstabtransform,unsharp=5:5:0.8:3:3:0.4 inp_stabilized.mpeg
20200 Note the use of the @ref{unsharp} filter which is always recommended.
20203 Zoom in a bit more and load transform data from a given file:
20205 vidstabtransform=zoom=5:input="mytransforms.trf"
20209 Smoothen the video even more:
20211 vidstabtransform=smoothing=30
20217 Flip the input video vertically.
20219 For example, to vertically flip a video with @command{ffmpeg}:
20221 ffmpeg -i in.avi -vf "vflip" out.avi
20226 Detect variable frame rate video.
20228 This filter tries to detect if the input is variable or constant frame rate.
20230 At end it will output number of frames detected as having variable delta pts,
20231 and ones with constant delta pts.
20232 If there was frames with variable delta, than it will also show min, max and
20233 average delta encountered.
20237 Boost or alter saturation.
20239 The filter accepts the following options:
20242 Set strength of boost if positive value or strength of alter if negative value.
20243 Default is 0. Allowed range is from -2 to 2.
20246 Set the red balance. Default is 1. Allowed range is from -10 to 10.
20249 Set the green balance. Default is 1. Allowed range is from -10 to 10.
20252 Set the blue balance. Default is 1. Allowed range is from -10 to 10.
20255 Set the red luma coefficient.
20258 Set the green luma coefficient.
20261 Set the blue luma coefficient.
20264 If @code{intensity} is negative and this is set to 1, colors will change,
20265 otherwise colors will be less saturated, more towards gray.
20268 @subsection Commands
20270 This filter supports the all above options as @ref{commands}.
20275 Make or reverse a natural vignetting effect.
20277 The filter accepts the following options:
20281 Set lens angle expression as a number of radians.
20283 The value is clipped in the @code{[0,PI/2]} range.
20285 Default value: @code{"PI/5"}
20289 Set center coordinates expressions. Respectively @code{"w/2"} and @code{"h/2"}
20293 Set forward/backward mode.
20295 Available modes are:
20298 The larger the distance from the central point, the darker the image becomes.
20301 The larger the distance from the central point, the brighter the image becomes.
20302 This can be used to reverse a vignette effect, though there is no automatic
20303 detection to extract the lens @option{angle} and other settings (yet). It can
20304 also be used to create a burning effect.
20307 Default value is @samp{forward}.
20310 Set evaluation mode for the expressions (@option{angle}, @option{x0}, @option{y0}).
20312 It accepts the following values:
20315 Evaluate expressions only once during the filter initialization.
20318 Evaluate expressions for each incoming frame. This is way slower than the
20319 @samp{init} mode since it requires all the scalers to be re-computed, but it
20320 allows advanced dynamic expressions.
20323 Default value is @samp{init}.
20326 Set dithering to reduce the circular banding effects. Default is @code{1}
20330 Set vignette aspect. This setting allows one to adjust the shape of the vignette.
20331 Setting this value to the SAR of the input will make a rectangular vignetting
20332 following the dimensions of the video.
20334 Default is @code{1/1}.
20337 @subsection Expressions
20339 The @option{alpha}, @option{x0} and @option{y0} expressions can contain the
20340 following parameters.
20345 input width and height
20348 the number of input frame, starting from 0
20351 the PTS (Presentation TimeStamp) time of the filtered video frame, expressed in
20352 @var{TB} units, NAN if undefined
20355 frame rate of the input video, NAN if the input frame rate is unknown
20358 the PTS (Presentation TimeStamp) of the filtered video frame,
20359 expressed in seconds, NAN if undefined
20362 time base of the input video
20366 @subsection Examples
20370 Apply simple strong vignetting effect:
20376 Make a flickering vignetting:
20378 vignette='PI/4+random(1)*PI/50':eval=frame
20383 @section vmafmotion
20385 Obtain the average VMAF motion score of a video.
20386 It is one of the component metrics of VMAF.
20388 The obtained average motion score is printed through the logging system.
20390 The filter accepts the following options:
20394 If specified, the filter will use the named file to save the motion score of
20395 each frame with respect to the previous frame.
20396 When filename equals "-" the data is sent to standard output.
20401 ffmpeg -i ref.mpg -vf vmafmotion -f null -
20405 Stack input videos vertically.
20407 All streams must be of same pixel format and of same width.
20409 Note that this filter is faster than using @ref{overlay} and @ref{pad} filter
20410 to create same output.
20412 The filter accepts the following options:
20416 Set number of input streams. Default is 2.
20419 If set to 1, force the output to terminate when the shortest input
20420 terminates. Default value is 0.
20425 Deinterlace the input video ("w3fdif" stands for "Weston 3 Field
20426 Deinterlacing Filter").
20428 Based on the process described by Martin Weston for BBC R&D, and
20429 implemented based on the de-interlace algorithm written by Jim
20430 Easterbrook for BBC R&D, the Weston 3 field deinterlacing filter
20431 uses filter coefficients calculated by BBC R&D.
20433 This filter uses field-dominance information in frame to decide which
20434 of each pair of fields to place first in the output.
20435 If it gets it wrong use @ref{setfield} filter before @code{w3fdif} filter.
20437 There are two sets of filter coefficients, so called "simple"
20438 and "complex". Which set of filter coefficients is used can
20439 be set by passing an optional parameter:
20443 Set the interlacing filter coefficients. Accepts one of the following values:
20447 Simple filter coefficient set.
20449 More-complex filter coefficient set.
20451 Default value is @samp{complex}.
20454 Specify which frames to deinterlace. Accepts one of the following values:
20458 Deinterlace all frames,
20460 Only deinterlace frames marked as interlaced.
20463 Default value is @samp{all}.
20467 Video waveform monitor.
20469 The waveform monitor plots color component intensity. By default luminance
20470 only. Each column of the waveform corresponds to a column of pixels in the
20473 It accepts the following options:
20477 Can be either @code{row}, or @code{column}. Default is @code{column}.
20478 In row mode, the graph on the left side represents color component value 0 and
20479 the right side represents value = 255. In column mode, the top side represents
20480 color component value = 0 and bottom side represents value = 255.
20483 Set intensity. Smaller values are useful to find out how many values of the same
20484 luminance are distributed across input rows/columns.
20485 Default value is @code{0.04}. Allowed range is [0, 1].
20488 Set mirroring mode. @code{0} means unmirrored, @code{1} means mirrored.
20489 In mirrored mode, higher values will be represented on the left
20490 side for @code{row} mode and at the top for @code{column} mode. Default is
20491 @code{1} (mirrored).
20495 It accepts the following values:
20498 Presents information identical to that in the @code{parade}, except
20499 that the graphs representing color components are superimposed directly
20502 This display mode makes it easier to spot relative differences or similarities
20503 in overlapping areas of the color components that are supposed to be identical,
20504 such as neutral whites, grays, or blacks.
20507 Display separate graph for the color components side by side in
20508 @code{row} mode or one below the other in @code{column} mode.
20511 Display separate graph for the color components side by side in
20512 @code{column} mode or one below the other in @code{row} mode.
20514 Using this display mode makes it easy to spot color casts in the highlights
20515 and shadows of an image, by comparing the contours of the top and the bottom
20516 graphs of each waveform. Since whites, grays, and blacks are characterized
20517 by exactly equal amounts of red, green, and blue, neutral areas of the picture
20518 should display three waveforms of roughly equal width/height. If not, the
20519 correction is easy to perform by making level adjustments the three waveforms.
20521 Default is @code{stack}.
20523 @item components, c
20524 Set which color components to display. Default is 1, which means only luminance
20525 or red color component if input is in RGB colorspace. If is set for example to
20526 7 it will display all 3 (if) available color components.
20531 No envelope, this is default.
20534 Instant envelope, minimum and maximum values presented in graph will be easily
20535 visible even with small @code{step} value.
20538 Hold minimum and maximum values presented in graph across time. This way you
20539 can still spot out of range values without constantly looking at waveforms.
20542 Peak and instant envelope combined together.
20548 No filtering, this is default.
20551 Luma and chroma combined together.
20554 Similar as above, but shows difference between blue and red chroma.
20557 Similar as above, but use different colors.
20560 Similar as above, but again with different colors.
20563 Displays only chroma.
20566 Displays actual color value on waveform.
20569 Similar as above, but with luma showing frequency of chroma values.
20573 Set which graticule to display.
20577 Do not display graticule.
20580 Display green graticule showing legal broadcast ranges.
20583 Display orange graticule showing legal broadcast ranges.
20586 Display invert graticule showing legal broadcast ranges.
20590 Set graticule opacity.
20593 Set graticule flags.
20597 Draw numbers above lines. By default enabled.
20600 Draw dots instead of lines.
20604 Set scale used for displaying graticule.
20611 Default is digital.
20614 Set background opacity.
20618 Set tint for output.
20619 Only used with lowpass filter and when display is not overlay and input
20620 pixel formats are not RGB.
20623 @section weave, doubleweave
20625 The @code{weave} takes a field-based video input and join
20626 each two sequential fields into single frame, producing a new double
20627 height clip with half the frame rate and half the frame count.
20629 The @code{doubleweave} works same as @code{weave} but without
20630 halving frame rate and frame count.
20632 It accepts the following option:
20636 Set first field. Available values are:
20640 Set the frame as top-field-first.
20643 Set the frame as bottom-field-first.
20647 @subsection Examples
20651 Interlace video using @ref{select} and @ref{separatefields} filter:
20653 separatefields,select=eq(mod(n,4),0)+eq(mod(n,4),3),weave
20658 Apply the xBR high-quality magnification filter which is designed for pixel
20659 art. It follows a set of edge-detection rules, see
20660 @url{https://forums.libretro.com/t/xbr-algorithm-tutorial/123}.
20662 It accepts the following option:
20666 Set the scaling dimension: @code{2} for @code{2xBR}, @code{3} for
20667 @code{3xBR} and @code{4} for @code{4xBR}.
20668 Default is @code{3}.
20673 Apply cross fade from one input video stream to another input video stream.
20674 The cross fade is applied for specified duration.
20676 The filter accepts the following options:
20680 Set one of available transition effects:
20728 Default transition effect is fade.
20731 Set cross fade duration in seconds.
20732 Default duration is 1 second.
20735 Set cross fade start relative to first input stream in seconds.
20736 Default offset is 0.
20739 Set expression for custom transition effect.
20741 The expressions can use the following variables and functions:
20746 The coordinates of the current sample.
20750 The width and height of the image.
20753 Progress of transition effect.
20756 Currently processed plane.
20759 Return value of first input at current location and plane.
20762 Return value of second input at current location and plane.
20768 Return the value of the pixel at location (@var{x},@var{y}) of the
20769 first/second/third/fourth component of first input.
20775 Return the value of the pixel at location (@var{x},@var{y}) of the
20776 first/second/third/fourth component of second input.
20780 @subsection Examples
20784 Cross fade from one input video to another input video, with fade transition and duration of transition
20785 of 2 seconds starting at offset of 5 seconds:
20787 ffmpeg -i first.mp4 -i second.mp4 -filter_complex xfade=transition=fade:duration=2:offset=5 output.mp4
20792 Pick median pixels from several input videos.
20794 The filter accepts the following options:
20798 Set number of inputs.
20799 Default is 3. Allowed range is from 3 to 255.
20800 If number of inputs is even number, than result will be mean value between two median values.
20803 Set which planes to filter. Default value is @code{15}, by which all planes are processed.
20806 Set median percentile. Default value is @code{0.5}.
20807 Default value of @code{0.5} will pick always median values, while @code{0} will pick
20808 minimum values, and @code{1} maximum values.
20812 Stack video inputs into custom layout.
20814 All streams must be of same pixel format.
20816 The filter accepts the following options:
20820 Set number of input streams. Default is 2.
20823 Specify layout of inputs.
20824 This option requires the desired layout configuration to be explicitly set by the user.
20825 This sets position of each video input in output. Each input
20826 is separated by '|'.
20827 The first number represents the column, and the second number represents the row.
20828 Numbers start at 0 and are separated by '_'. Optionally one can use wX and hX,
20829 where X is video input from which to take width or height.
20830 Multiple values can be used when separated by '+'. In such
20831 case values are summed together.
20833 Note that if inputs are of different sizes gaps may appear, as not all of
20834 the output video frame will be filled. Similarly, videos can overlap each
20835 other if their position doesn't leave enough space for the full frame of
20838 For 2 inputs, a default layout of @code{0_0|w0_0} is set. In all other cases,
20839 a layout must be set by the user.
20842 If set to 1, force the output to terminate when the shortest input
20843 terminates. Default value is 0.
20846 If set to valid color, all unused pixels will be filled with that color.
20847 By default fill is set to none, so it is disabled.
20850 @subsection Examples
20854 Display 4 inputs into 2x2 grid.
20858 input1(0, 0) | input3(w0, 0)
20859 input2(0, h0) | input4(w0, h0)
20863 xstack=inputs=4:layout=0_0|0_h0|w0_0|w0_h0
20866 Note that if inputs are of different sizes, gaps or overlaps may occur.
20869 Display 4 inputs into 1x4 grid.
20876 input4(0, h0+h1+h2)
20880 xstack=inputs=4:layout=0_0|0_h0|0_h0+h1|0_h0+h1+h2
20883 Note that if inputs are of different widths, unused space will appear.
20886 Display 9 inputs into 3x3 grid.
20890 input1(0, 0) | input4(w0, 0) | input7(w0+w3, 0)
20891 input2(0, h0) | input5(w0, h0) | input8(w0+w3, h0)
20892 input3(0, h0+h1) | input6(w0, h0+h1) | input9(w0+w3, h0+h1)
20896 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
20899 Note that if inputs are of different sizes, gaps or overlaps may occur.
20902 Display 16 inputs into 4x4 grid.
20906 input1(0, 0) | input5(w0, 0) | input9 (w0+w4, 0) | input13(w0+w4+w8, 0)
20907 input2(0, h0) | input6(w0, h0) | input10(w0+w4, h0) | input14(w0+w4+w8, h0)
20908 input3(0, h0+h1) | input7(w0, h0+h1) | input11(w0+w4, h0+h1) | input15(w0+w4+w8, h0+h1)
20909 input4(0, h0+h1+h2)| input8(w0, h0+h1+h2)| input12(w0+w4, h0+h1+h2)| input16(w0+w4+w8, h0+h1+h2)
20913 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|
20914 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
20917 Note that if inputs are of different sizes, gaps or overlaps may occur.
20924 Deinterlace the input video ("yadif" means "yet another deinterlacing
20927 It accepts the following parameters:
20933 The interlacing mode to adopt. It accepts one of the following values:
20936 @item 0, send_frame
20937 Output one frame for each frame.
20938 @item 1, send_field
20939 Output one frame for each field.
20940 @item 2, send_frame_nospatial
20941 Like @code{send_frame}, but it skips the spatial interlacing check.
20942 @item 3, send_field_nospatial
20943 Like @code{send_field}, but it skips the spatial interlacing check.
20946 The default value is @code{send_frame}.
20949 The picture field parity assumed for the input interlaced video. It accepts one
20950 of the following values:
20954 Assume the top field is first.
20956 Assume the bottom field is first.
20958 Enable automatic detection of field parity.
20961 The default value is @code{auto}.
20962 If the interlacing is unknown or the decoder does not export this information,
20963 top field first will be assumed.
20966 Specify which frames to deinterlace. Accepts one of the following
20971 Deinterlace all frames.
20972 @item 1, interlaced
20973 Only deinterlace frames marked as interlaced.
20976 The default value is @code{all}.
20979 @section yadif_cuda
20981 Deinterlace the input video using the @ref{yadif} algorithm, but implemented
20982 in CUDA so that it can work as part of a GPU accelerated pipeline with nvdec
20985 It accepts the following parameters:
20991 The interlacing mode to adopt. It accepts one of the following values:
20994 @item 0, send_frame
20995 Output one frame for each frame.
20996 @item 1, send_field
20997 Output one frame for each field.
20998 @item 2, send_frame_nospatial
20999 Like @code{send_frame}, but it skips the spatial interlacing check.
21000 @item 3, send_field_nospatial
21001 Like @code{send_field}, but it skips the spatial interlacing check.
21004 The default value is @code{send_frame}.
21007 The picture field parity assumed for the input interlaced video. It accepts one
21008 of the following values:
21012 Assume the top field is first.
21014 Assume the bottom field is first.
21016 Enable automatic detection of field parity.
21019 The default value is @code{auto}.
21020 If the interlacing is unknown or the decoder does not export this information,
21021 top field first will be assumed.
21024 Specify which frames to deinterlace. Accepts one of the following
21029 Deinterlace all frames.
21030 @item 1, interlaced
21031 Only deinterlace frames marked as interlaced.
21034 The default value is @code{all}.
21039 Apply blur filter while preserving edges ("yaepblur" means "yet another edge preserving blur filter").
21040 The algorithm is described in
21041 "J. S. Lee, Digital image enhancement and noise filtering by use of local statistics, IEEE Trans. Pattern Anal. Mach. Intell. PAMI-2, 1980."
21043 It accepts the following parameters:
21047 Set the window radius. Default value is 3.
21050 Set which planes to filter. Default is only the first plane.
21053 Set blur strength. Default value is 128.
21056 @subsection Commands
21057 This filter supports same @ref{commands} as options.
21061 Apply Zoom & Pan effect.
21063 This filter accepts the following options:
21067 Set the zoom expression. Range is 1-10. Default is 1.
21071 Set the x and y expression. Default is 0.
21074 Set the duration expression in number of frames.
21075 This sets for how many number of frames effect will last for
21076 single input image.
21079 Set the output image size, default is 'hd720'.
21082 Set the output frame rate, default is '25'.
21085 Each expression can contain the following constants:
21104 Output frame count.
21107 The input timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
21109 @item out_time, time, ot
21110 The output timestamp expressed in seconds.
21114 Last calculated 'x' and 'y' position from 'x' and 'y' expression
21115 for current input frame.
21119 'x' and 'y' of last output frame of previous input frame or 0 when there was
21120 not yet such frame (first input frame).
21123 Last calculated zoom from 'z' expression for current input frame.
21126 Last calculated zoom of last output frame of previous input frame.
21129 Number of output frames for current input frame. Calculated from 'd' expression
21130 for each input frame.
21133 number of output frames created for previous input frame
21136 Rational number: input width / input height
21139 sample aspect ratio
21142 display aspect ratio
21146 @subsection Examples
21150 Zoom in up to 1.5x and pan at same time to some spot near center of picture:
21152 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
21156 Zoom in up to 1.5x and pan always at center of picture:
21158 zoompan=z='min(zoom+0.0015,1.5)':d=700:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
21162 Same as above but without pausing:
21164 zoompan=z='min(max(zoom,pzoom)+0.0015,1.5)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
21168 Zoom in 2x into center of picture only for the first second of the input video:
21170 zoompan=z='if(between(in_time,0,1),2,1)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
21177 Scale (resize) the input video, using the z.lib library:
21178 @url{https://github.com/sekrit-twc/zimg}. To enable compilation of this
21179 filter, you need to configure FFmpeg with @code{--enable-libzimg}.
21181 The zscale filter forces the output display aspect ratio to be the same
21182 as the input, by changing the output sample aspect ratio.
21184 If the input image format is different from the format requested by
21185 the next filter, the zscale filter will convert the input to the
21188 @subsection Options
21189 The filter accepts the following options.
21194 Set the output video dimension expression. Default value is the input
21197 If the @var{width} or @var{w} value is 0, the input width is used for
21198 the output. If the @var{height} or @var{h} value is 0, the input height
21199 is used for the output.
21201 If one and only one of the values is -n with n >= 1, the zscale filter
21202 will use a value that maintains the aspect ratio of the input image,
21203 calculated from the other specified dimension. After that it will,
21204 however, make sure that the calculated dimension is divisible by n and
21205 adjust the value if necessary.
21207 If both values are -n with n >= 1, the behavior will be identical to
21208 both values being set to 0 as previously detailed.
21210 See below for the list of accepted constants for use in the dimension
21214 Set the video size. For the syntax of this option, check the
21215 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
21218 Set the dither type.
21220 Possible values are:
21225 @item error_diffusion
21231 Set the resize filter type.
21233 Possible values are:
21243 Default is bilinear.
21246 Set the color range.
21248 Possible values are:
21255 Default is same as input.
21258 Set the color primaries.
21260 Possible values are:
21270 Default is same as input.
21273 Set the transfer characteristics.
21275 Possible values are:
21289 Default is same as input.
21292 Set the colorspace matrix.
21294 Possible value are:
21305 Default is same as input.
21308 Set the input color range.
21310 Possible values are:
21317 Default is same as input.
21319 @item primariesin, pin
21320 Set the input color primaries.
21322 Possible values are:
21332 Default is same as input.
21334 @item transferin, tin
21335 Set the input transfer characteristics.
21337 Possible values are:
21348 Default is same as input.
21350 @item matrixin, min
21351 Set the input colorspace matrix.
21353 Possible value are:
21365 Set the output chroma location.
21367 Possible values are:
21378 @item chromalin, cin
21379 Set the input chroma location.
21381 Possible values are:
21393 Set the nominal peak luminance.
21396 The values of the @option{w} and @option{h} options are expressions
21397 containing the following constants:
21402 The input width and height
21406 These are the same as @var{in_w} and @var{in_h}.
21410 The output (scaled) width and height
21414 These are the same as @var{out_w} and @var{out_h}
21417 The same as @var{iw} / @var{ih}
21420 input sample aspect ratio
21423 The input display aspect ratio. Calculated from @code{(iw / ih) * sar}.
21427 horizontal and vertical input chroma subsample values. For example for the
21428 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
21432 horizontal and vertical output chroma subsample values. For example for the
21433 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
21436 @subsection Commands
21438 This filter supports the following commands:
21442 Set the output video dimension expression.
21443 The command accepts the same syntax of the corresponding option.
21445 If the specified expression is not valid, it is kept at its current
21449 @c man end VIDEO FILTERS
21451 @chapter OpenCL Video Filters
21452 @c man begin OPENCL VIDEO FILTERS
21454 Below is a description of the currently available OpenCL video filters.
21456 To enable compilation of these filters you need to configure FFmpeg with
21457 @code{--enable-opencl}.
21459 Running OpenCL filters requires you to initialize a hardware device and to pass that device to all filters in any filter graph.
21462 @item -init_hw_device opencl[=@var{name}][:@var{device}[,@var{key=value}...]]
21463 Initialise a new hardware device of type @var{opencl} called @var{name}, using the
21464 given device parameters.
21466 @item -filter_hw_device @var{name}
21467 Pass the hardware device called @var{name} to all filters in any filter graph.
21471 For more detailed information see @url{https://www.ffmpeg.org/ffmpeg.html#Advanced-Video-options}
21475 Example of choosing the first device on the second platform and running avgblur_opencl filter with default parameters on it.
21477 -init_hw_device opencl=gpu:1.0 -filter_hw_device gpu -i INPUT -vf "hwupload, avgblur_opencl, hwdownload" OUTPUT
21481 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.
21483 @section avgblur_opencl
21485 Apply average blur filter.
21487 The filter accepts the following options:
21491 Set horizontal radius size.
21492 Range is @code{[1, 1024]} and default value is @code{1}.
21495 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
21498 Set vertical radius size. Range is @code{[1, 1024]} and default value is @code{0}. If zero, @code{sizeX} value will be used.
21501 @subsection Example
21505 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.
21507 -i INPUT -vf "hwupload, avgblur_opencl=3, hwdownload" OUTPUT
21511 @section boxblur_opencl
21513 Apply a boxblur algorithm to the input video.
21515 It accepts the following parameters:
21519 @item luma_radius, lr
21520 @item luma_power, lp
21521 @item chroma_radius, cr
21522 @item chroma_power, cp
21523 @item alpha_radius, ar
21524 @item alpha_power, ap
21528 A description of the accepted options follows.
21531 @item luma_radius, lr
21532 @item chroma_radius, cr
21533 @item alpha_radius, ar
21534 Set an expression for the box radius in pixels used for blurring the
21535 corresponding input plane.
21537 The radius value must be a non-negative number, and must not be
21538 greater than the value of the expression @code{min(w,h)/2} for the
21539 luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma
21542 Default value for @option{luma_radius} is "2". If not specified,
21543 @option{chroma_radius} and @option{alpha_radius} default to the
21544 corresponding value set for @option{luma_radius}.
21546 The expressions can contain the following constants:
21550 The input width and height in pixels.
21554 The input chroma image width and height in pixels.
21558 The horizontal and vertical chroma subsample values. For example, for the
21559 pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1.
21562 @item luma_power, lp
21563 @item chroma_power, cp
21564 @item alpha_power, ap
21565 Specify how many times the boxblur filter is applied to the
21566 corresponding plane.
21568 Default value for @option{luma_power} is 2. If not specified,
21569 @option{chroma_power} and @option{alpha_power} default to the
21570 corresponding value set for @option{luma_power}.
21572 A value of 0 will disable the effect.
21575 @subsection Examples
21577 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.
21581 Apply a boxblur filter with the luma, chroma, and alpha radius
21582 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.
21584 -i INPUT -vf "hwupload, boxblur_opencl=luma_radius=2:luma_power=3, hwdownload" OUTPUT
21585 -i INPUT -vf "hwupload, boxblur_opencl=2:3, hwdownload" OUTPUT
21589 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.
21591 For the luma plane, a 2x2 box radius will be run once.
21593 For the chroma plane, a 4x4 box radius will be run 5 times.
21595 For the alpha plane, a 3x3 box radius will be run 7 times.
21597 -i INPUT -vf "hwupload, boxblur_opencl=2:1:4:5:3:7, hwdownload" OUTPUT
21601 @section colorkey_opencl
21602 RGB colorspace color keying.
21604 The filter accepts the following options:
21608 The color which will be replaced with transparency.
21611 Similarity percentage with the key color.
21613 0.01 matches only the exact key color, while 1.0 matches everything.
21618 0.0 makes pixels either fully transparent, or not transparent at all.
21620 Higher values result in semi-transparent pixels, with a higher transparency
21621 the more similar the pixels color is to the key color.
21624 @subsection Examples
21628 Make every semi-green pixel in the input transparent with some slight blending:
21630 -i INPUT -vf "hwupload, colorkey_opencl=green:0.3:0.1, hwdownload" OUTPUT
21634 @section convolution_opencl
21636 Apply convolution of 3x3, 5x5, 7x7 matrix.
21638 The filter accepts the following options:
21645 Set matrix for each plane.
21646 Matrix is sequence of 9, 25 or 49 signed numbers.
21647 Default value for each plane is @code{0 0 0 0 1 0 0 0 0}.
21653 Set multiplier for calculated value for each plane.
21654 If unset or 0, it will be sum of all matrix elements.
21655 The option value must be a float number greater or equal to @code{0.0}. Default value is @code{1.0}.
21661 Set bias for each plane. This value is added to the result of the multiplication.
21662 Useful for making the overall image brighter or darker.
21663 The option value must be a float number greater or equal to @code{0.0}. Default value is @code{0.0}.
21667 @subsection Examples
21673 -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
21679 -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
21683 Apply edge enhance:
21685 -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
21691 -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
21695 Apply laplacian edge detector which includes diagonals:
21697 -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
21703 -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
21707 @section erosion_opencl
21709 Apply erosion effect to the video.
21711 This filter replaces the pixel by the local(3x3) minimum.
21713 It accepts the following options:
21720 Limit the maximum change for each plane. Range is @code{[0, 65535]} and default value is @code{65535}.
21721 If @code{0}, plane will remain unchanged.
21724 Flag which specifies the pixel to refer to.
21725 Range is @code{[0, 255]} and default value is @code{255}, i.e. all eight pixels are used.
21727 Flags to local 3x3 coordinates region centered on @code{x}:
21736 @subsection Example
21740 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.
21742 -i INPUT -vf "hwupload, erosion_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT
21746 @section deshake_opencl
21747 Feature-point based video stabilization filter.
21749 The filter accepts the following options:
21753 Simulates a tripod by preventing any camera movement whatsoever from the original frame. Defaults to @code{0}.
21756 Whether or not additional debug info should be displayed, both in the processed output and in the console.
21758 Note that in order to see console debug output you will also need to pass @code{-v verbose} to ffmpeg.
21760 Viewing point matches in the output video is only supported for RGB input.
21762 Defaults to @code{0}.
21764 @item adaptive_crop
21765 Whether or not to do a tiny bit of cropping at the borders to cut down on the amount of mirrored pixels.
21767 Defaults to @code{1}.
21769 @item refine_features
21770 Whether or not feature points should be refined at a sub-pixel level.
21772 This can be turned off for a slight performance gain at the cost of precision.
21774 Defaults to @code{1}.
21776 @item smooth_strength
21777 The strength of the smoothing applied to the camera path from @code{0.0} to @code{1.0}.
21779 @code{1.0} is the maximum smoothing strength while values less than that result in less smoothing.
21781 @code{0.0} causes the filter to adaptively choose a smoothing strength on a per-frame basis.
21783 Defaults to @code{0.0}.
21785 @item smooth_window_multiplier
21786 Controls the size of the smoothing window (the number of frames buffered to determine motion information from).
21788 The size of the smoothing window is determined by multiplying the framerate of the video by this number.
21790 Acceptable values range from @code{0.1} to @code{10.0}.
21792 Larger values increase the amount of motion data available for determining how to smooth the camera path,
21793 potentially improving smoothness, but also increase latency and memory usage.
21795 Defaults to @code{2.0}.
21799 @subsection Examples
21803 Stabilize a video with a fixed, medium smoothing strength:
21805 -i INPUT -vf "hwupload, deshake_opencl=smooth_strength=0.5, hwdownload" OUTPUT
21809 Stabilize a video with debugging (both in console and in rendered video):
21811 -i INPUT -filter_complex "[0:v]format=rgba, hwupload, deshake_opencl=debug=1, hwdownload, format=rgba, format=yuv420p" -v verbose OUTPUT
21815 @section dilation_opencl
21817 Apply dilation effect to the video.
21819 This filter replaces the pixel by the local(3x3) maximum.
21821 It accepts the following options:
21828 Limit the maximum change for each plane. Range is @code{[0, 65535]} and default value is @code{65535}.
21829 If @code{0}, plane will remain unchanged.
21832 Flag which specifies the pixel to refer to.
21833 Range is @code{[0, 255]} and default value is @code{255}, i.e. all eight pixels are used.
21835 Flags to local 3x3 coordinates region centered on @code{x}:
21844 @subsection Example
21848 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.
21850 -i INPUT -vf "hwupload, dilation_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT
21854 @section nlmeans_opencl
21856 Non-local Means denoise filter through OpenCL, this filter accepts same options as @ref{nlmeans}.
21858 @section overlay_opencl
21860 Overlay one video on top of another.
21862 It takes two inputs and has one output. The first input is the "main" video on which the second input is overlaid.
21863 This filter requires same memory layout for all the inputs. So, format conversion may be needed.
21865 The filter accepts the following options:
21870 Set the x coordinate of the overlaid video on the main video.
21871 Default value is @code{0}.
21874 Set the y coordinate of the overlaid video on the main video.
21875 Default value is @code{0}.
21879 @subsection Examples
21883 Overlay an image LOGO at the top-left corner of the INPUT video. Both inputs are yuv420p format.
21885 -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuv420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT
21888 The inputs have same memory layout for color channels , the overlay has additional alpha plane, like INPUT is yuv420p, and the LOGO is yuva420p.
21890 -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuva420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT
21895 @section pad_opencl
21897 Add paddings to the input image, and place the original input at the
21898 provided @var{x}, @var{y} coordinates.
21900 It accepts the following options:
21905 Specify an expression for the size of the output image with the
21906 paddings added. If the value for @var{width} or @var{height} is 0, the
21907 corresponding input size is used for the output.
21909 The @var{width} expression can reference the value set by the
21910 @var{height} expression, and vice versa.
21912 The default value of @var{width} and @var{height} is 0.
21916 Specify the offsets to place the input image at within the padded area,
21917 with respect to the top/left border of the output image.
21919 The @var{x} expression can reference the value set by the @var{y}
21920 expression, and vice versa.
21922 The default value of @var{x} and @var{y} is 0.
21924 If @var{x} or @var{y} evaluate to a negative number, they'll be changed
21925 so the input image is centered on the padded area.
21928 Specify the color of the padded area. For the syntax of this option,
21929 check the @ref{color syntax,,"Color" section in the ffmpeg-utils
21930 manual,ffmpeg-utils}.
21933 Pad to an aspect instead to a resolution.
21936 The value for the @var{width}, @var{height}, @var{x}, and @var{y}
21937 options are expressions containing the following constants:
21942 The input video width and height.
21946 These are the same as @var{in_w} and @var{in_h}.
21950 The output width and height (the size of the padded area), as
21951 specified by the @var{width} and @var{height} expressions.
21955 These are the same as @var{out_w} and @var{out_h}.
21959 The x and y offsets as specified by the @var{x} and @var{y}
21960 expressions, or NAN if not yet specified.
21963 same as @var{iw} / @var{ih}
21966 input sample aspect ratio
21969 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
21972 @section prewitt_opencl
21974 Apply the Prewitt operator (@url{https://en.wikipedia.org/wiki/Prewitt_operator}) to input video stream.
21976 The filter accepts the following option:
21980 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
21983 Set value which will be multiplied with filtered result.
21984 Range is @code{[0.0, 65535]} and default value is @code{1.0}.
21987 Set value which will be added to filtered result.
21988 Range is @code{[-65535, 65535]} and default value is @code{0.0}.
21991 @subsection Example
21995 Apply the Prewitt operator with scale set to 2 and delta set to 10.
21997 -i INPUT -vf "hwupload, prewitt_opencl=scale=2:delta=10, hwdownload" OUTPUT
22001 @anchor{program_opencl}
22002 @section program_opencl
22004 Filter video using an OpenCL program.
22009 OpenCL program source file.
22012 Kernel name in program.
22015 Number of inputs to the filter. Defaults to 1.
22018 Size of output frames. Defaults to the same as the first input.
22022 The @code{program_opencl} filter also supports the @ref{framesync} options.
22024 The program source file must contain a kernel function with the given name,
22025 which will be run once for each plane of the output. Each run on a plane
22026 gets enqueued as a separate 2D global NDRange with one work-item for each
22027 pixel to be generated. The global ID offset for each work-item is therefore
22028 the coordinates of a pixel in the destination image.
22030 The kernel function needs to take the following arguments:
22033 Destination image, @var{__write_only image2d_t}.
22035 This image will become the output; the kernel should write all of it.
22037 Frame index, @var{unsigned int}.
22039 This is a counter starting from zero and increasing by one for each frame.
22041 Source images, @var{__read_only image2d_t}.
22043 These are the most recent images on each input. The kernel may read from
22044 them to generate the output, but they can't be written to.
22051 Copy the input to the output (output must be the same size as the input).
22053 __kernel void copy(__write_only image2d_t destination,
22054 unsigned int index,
22055 __read_only image2d_t source)
22057 const sampler_t sampler = CLK_NORMALIZED_COORDS_FALSE;
22059 int2 location = (int2)(get_global_id(0), get_global_id(1));
22061 float4 value = read_imagef(source, sampler, location);
22063 write_imagef(destination, location, value);
22068 Apply a simple transformation, rotating the input by an amount increasing
22069 with the index counter. Pixel values are linearly interpolated by the
22070 sampler, and the output need not have the same dimensions as the input.
22072 __kernel void rotate_image(__write_only image2d_t dst,
22073 unsigned int index,
22074 __read_only image2d_t src)
22076 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
22077 CLK_FILTER_LINEAR);
22079 float angle = (float)index / 100.0f;
22081 float2 dst_dim = convert_float2(get_image_dim(dst));
22082 float2 src_dim = convert_float2(get_image_dim(src));
22084 float2 dst_cen = dst_dim / 2.0f;
22085 float2 src_cen = src_dim / 2.0f;
22087 int2 dst_loc = (int2)(get_global_id(0), get_global_id(1));
22089 float2 dst_pos = convert_float2(dst_loc) - dst_cen;
22091 cos(angle) * dst_pos.x - sin(angle) * dst_pos.y,
22092 sin(angle) * dst_pos.x + cos(angle) * dst_pos.y
22094 src_pos = src_pos * src_dim / dst_dim;
22096 float2 src_loc = src_pos + src_cen;
22098 if (src_loc.x < 0.0f || src_loc.y < 0.0f ||
22099 src_loc.x > src_dim.x || src_loc.y > src_dim.y)
22100 write_imagef(dst, dst_loc, 0.5f);
22102 write_imagef(dst, dst_loc, read_imagef(src, sampler, src_loc));
22107 Blend two inputs together, with the amount of each input used varying
22108 with the index counter.
22110 __kernel void blend_images(__write_only image2d_t dst,
22111 unsigned int index,
22112 __read_only image2d_t src1,
22113 __read_only image2d_t src2)
22115 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
22116 CLK_FILTER_LINEAR);
22118 float blend = (cos((float)index / 50.0f) + 1.0f) / 2.0f;
22120 int2 dst_loc = (int2)(get_global_id(0), get_global_id(1));
22121 int2 src1_loc = dst_loc * get_image_dim(src1) / get_image_dim(dst);
22122 int2 src2_loc = dst_loc * get_image_dim(src2) / get_image_dim(dst);
22124 float4 val1 = read_imagef(src1, sampler, src1_loc);
22125 float4 val2 = read_imagef(src2, sampler, src2_loc);
22127 write_imagef(dst, dst_loc, val1 * blend + val2 * (1.0f - blend));
22133 @section roberts_opencl
22134 Apply the Roberts cross operator (@url{https://en.wikipedia.org/wiki/Roberts_cross}) to input video stream.
22136 The filter accepts the following option:
22140 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
22143 Set value which will be multiplied with filtered result.
22144 Range is @code{[0.0, 65535]} and default value is @code{1.0}.
22147 Set value which will be added to filtered result.
22148 Range is @code{[-65535, 65535]} and default value is @code{0.0}.
22151 @subsection Example
22155 Apply the Roberts cross operator with scale set to 2 and delta set to 10
22157 -i INPUT -vf "hwupload, roberts_opencl=scale=2:delta=10, hwdownload" OUTPUT
22161 @section sobel_opencl
22163 Apply the Sobel operator (@url{https://en.wikipedia.org/wiki/Sobel_operator}) to input video stream.
22165 The filter accepts the following option:
22169 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
22172 Set value which will be multiplied with filtered result.
22173 Range is @code{[0.0, 65535]} and default value is @code{1.0}.
22176 Set value which will be added to filtered result.
22177 Range is @code{[-65535, 65535]} and default value is @code{0.0}.
22180 @subsection Example
22184 Apply sobel operator with scale set to 2 and delta set to 10
22186 -i INPUT -vf "hwupload, sobel_opencl=scale=2:delta=10, hwdownload" OUTPUT
22190 @section tonemap_opencl
22192 Perform HDR(PQ/HLG) to SDR conversion with tone-mapping.
22194 It accepts the following parameters:
22198 Specify the tone-mapping operator to be used. Same as tonemap option in @ref{tonemap}.
22201 Tune the tone mapping algorithm. same as param option in @ref{tonemap}.
22204 Apply desaturation for highlights that exceed this level of brightness. The
22205 higher the parameter, the more color information will be preserved. This
22206 setting helps prevent unnaturally blown-out colors for super-highlights, by
22207 (smoothly) turning into white instead. This makes images feel more natural,
22208 at the cost of reducing information about out-of-range colors.
22210 The default value is 0.5, and the algorithm here is a little different from
22211 the cpu version tonemap currently. A setting of 0.0 disables this option.
22214 The tonemapping algorithm parameters is fine-tuned per each scene. And a threshold
22215 is used to detect whether the scene has changed or not. If the distance between
22216 the current frame average brightness and the current running average exceeds
22217 a threshold value, we would re-calculate scene average and peak brightness.
22218 The default value is 0.2.
22221 Specify the output pixel format.
22223 Currently supported formats are:
22230 Set the output color range.
22232 Possible values are:
22238 Default is same as input.
22241 Set the output color primaries.
22243 Possible values are:
22249 Default is same as input.
22252 Set the output transfer characteristics.
22254 Possible values are:
22263 Set the output colorspace matrix.
22265 Possible value are:
22271 Default is same as input.
22275 @subsection Example
22279 Convert HDR(PQ/HLG) video to bt2020-transfer-characteristic p010 format using linear operator.
22281 -i INPUT -vf "format=p010,hwupload,tonemap_opencl=t=bt2020:tonemap=linear:format=p010,hwdownload,format=p010" OUTPUT
22285 @section unsharp_opencl
22287 Sharpen or blur the input video.
22289 It accepts the following parameters:
22292 @item luma_msize_x, lx
22293 Set the luma matrix horizontal size.
22294 Range is @code{[1, 23]} and default value is @code{5}.
22296 @item luma_msize_y, ly
22297 Set the luma matrix vertical size.
22298 Range is @code{[1, 23]} and default value is @code{5}.
22300 @item luma_amount, la
22301 Set the luma effect strength.
22302 Range is @code{[-10, 10]} and default value is @code{1.0}.
22304 Negative values will blur the input video, while positive values will
22305 sharpen it, a value of zero will disable the effect.
22307 @item chroma_msize_x, cx
22308 Set the chroma matrix horizontal size.
22309 Range is @code{[1, 23]} and default value is @code{5}.
22311 @item chroma_msize_y, cy
22312 Set the chroma matrix vertical size.
22313 Range is @code{[1, 23]} and default value is @code{5}.
22315 @item chroma_amount, ca
22316 Set the chroma effect strength.
22317 Range is @code{[-10, 10]} and default value is @code{0.0}.
22319 Negative values will blur the input video, while positive values will
22320 sharpen it, a value of zero will disable the effect.
22324 All parameters are optional and default to the equivalent of the
22325 string '5:5:1.0:5:5:0.0'.
22327 @subsection Examples
22331 Apply strong luma sharpen effect:
22333 -i INPUT -vf "hwupload, unsharp_opencl=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5, hwdownload" OUTPUT
22337 Apply a strong blur of both luma and chroma parameters:
22339 -i INPUT -vf "hwupload, unsharp_opencl=7:7:-2:7:7:-2, hwdownload" OUTPUT
22343 @section xfade_opencl
22345 Cross fade two videos with custom transition effect by using OpenCL.
22347 It accepts the following options:
22351 Set one of possible transition effects.
22355 Select custom transition effect, the actual transition description
22356 will be picked from source and kernel options.
22368 Default transition is fade.
22372 OpenCL program source file for custom transition.
22375 Set name of kernel to use for custom transition from program source file.
22378 Set duration of video transition.
22381 Set time of start of transition relative to first video.
22384 The program source file must contain a kernel function with the given name,
22385 which will be run once for each plane of the output. Each run on a plane
22386 gets enqueued as a separate 2D global NDRange with one work-item for each
22387 pixel to be generated. The global ID offset for each work-item is therefore
22388 the coordinates of a pixel in the destination image.
22390 The kernel function needs to take the following arguments:
22393 Destination image, @var{__write_only image2d_t}.
22395 This image will become the output; the kernel should write all of it.
22398 First Source image, @var{__read_only image2d_t}.
22399 Second Source image, @var{__read_only image2d_t}.
22401 These are the most recent images on each input. The kernel may read from
22402 them to generate the output, but they can't be written to.
22405 Transition progress, @var{float}. This value is always between 0 and 1 inclusive.
22412 Apply dots curtain transition effect:
22414 __kernel void blend_images(__write_only image2d_t dst,
22415 __read_only image2d_t src1,
22416 __read_only image2d_t src2,
22419 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
22420 CLK_FILTER_LINEAR);
22421 int2 p = (int2)(get_global_id(0), get_global_id(1));
22422 float2 rp = (float2)(get_global_id(0), get_global_id(1));
22423 float2 dim = (float2)(get_image_dim(src1).x, get_image_dim(src1).y);
22426 float2 dots = (float2)(20.0, 20.0);
22427 float2 center = (float2)(0,0);
22430 float4 val1 = read_imagef(src1, sampler, p);
22431 float4 val2 = read_imagef(src2, sampler, p);
22432 bool next = distance(fract(rp * dots, &unused), (float2)(0.5, 0.5)) < (progress / distance(rp, center));
22434 write_imagef(dst, p, next ? val1 : val2);
22440 @c man end OPENCL VIDEO FILTERS
22442 @chapter VAAPI Video Filters
22443 @c man begin VAAPI VIDEO FILTERS
22445 VAAPI Video filters are usually used with VAAPI decoder and VAAPI encoder. Below is a description of VAAPI video filters.
22447 To enable compilation of these filters you need to configure FFmpeg with
22448 @code{--enable-vaapi}.
22450 To use vaapi filters, you need to setup the vaapi device correctly. For more information, please read @url{https://trac.ffmpeg.org/wiki/Hardware/VAAPI}
22452 @section tonemap_vaapi
22454 Perform HDR(High Dynamic Range) to SDR(Standard Dynamic Range) conversion with tone-mapping.
22455 It maps the dynamic range of HDR10 content to the SDR content.
22456 It currently only accepts HDR10 as input.
22458 It accepts the following parameters:
22462 Specify the output pixel format.
22464 Currently supported formats are:
22473 Set the output color primaries.
22475 Default is same as input.
22478 Set the output transfer characteristics.
22483 Set the output colorspace matrix.
22485 Default is same as input.
22489 @subsection Example
22493 Convert HDR(HDR10) video to bt2020-transfer-characteristic p010 format
22495 tonemap_vaapi=format=p010:t=bt2020-10
22499 @c man end VAAPI VIDEO FILTERS
22501 @chapter Video Sources
22502 @c man begin VIDEO SOURCES
22504 Below is a description of the currently available video sources.
22508 Buffer video frames, and make them available to the filter chain.
22510 This source is mainly intended for a programmatic use, in particular
22511 through the interface defined in @file{libavfilter/buffersrc.h}.
22513 It accepts the following parameters:
22518 Specify the size (width and height) of the buffered video frames. For the
22519 syntax of this option, check the
22520 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
22523 The input video width.
22526 The input video height.
22529 A string representing the pixel format of the buffered video frames.
22530 It may be a number corresponding to a pixel format, or a pixel format
22534 Specify the timebase assumed by the timestamps of the buffered frames.
22537 Specify the frame rate expected for the video stream.
22539 @item pixel_aspect, sar
22540 The sample (pixel) aspect ratio of the input video.
22543 This option is deprecated and ignored. Prepend @code{sws_flags=@var{flags};}
22544 to the filtergraph description to specify swscale flags for automatically
22545 inserted scalers. See @ref{Filtergraph syntax}.
22547 @item hw_frames_ctx
22548 When using a hardware pixel format, this should be a reference to an
22549 AVHWFramesContext describing input frames.
22554 buffer=width=320:height=240:pix_fmt=yuv410p:time_base=1/24:sar=1
22557 will instruct the source to accept video frames with size 320x240 and
22558 with format "yuv410p", assuming 1/24 as the timestamps timebase and
22559 square pixels (1:1 sample aspect ratio).
22560 Since the pixel format with name "yuv410p" corresponds to the number 6
22561 (check the enum AVPixelFormat definition in @file{libavutil/pixfmt.h}),
22562 this example corresponds to:
22564 buffer=size=320x240:pixfmt=6:time_base=1/24:pixel_aspect=1/1
22567 Alternatively, the options can be specified as a flat string, but this
22568 syntax is deprecated:
22570 @var{width}:@var{height}:@var{pix_fmt}:@var{time_base.num}:@var{time_base.den}:@var{pixel_aspect.num}:@var{pixel_aspect.den}
22574 Create a pattern generated by an elementary cellular automaton.
22576 The initial state of the cellular automaton can be defined through the
22577 @option{filename} and @option{pattern} options. If such options are
22578 not specified an initial state is created randomly.
22580 At each new frame a new row in the video is filled with the result of
22581 the cellular automaton next generation. The behavior when the whole
22582 frame is filled is defined by the @option{scroll} option.
22584 This source accepts the following options:
22588 Read the initial cellular automaton state, i.e. the starting row, from
22589 the specified file.
22590 In the file, each non-whitespace character is considered an alive
22591 cell, a newline will terminate the row, and further characters in the
22592 file will be ignored.
22595 Read the initial cellular automaton state, i.e. the starting row, from
22596 the specified string.
22598 Each non-whitespace character in the string is considered an alive
22599 cell, a newline will terminate the row, and further characters in the
22600 string will be ignored.
22603 Set the video rate, that is the number of frames generated per second.
22606 @item random_fill_ratio, ratio
22607 Set the random fill ratio for the initial cellular automaton row. It
22608 is a floating point number value ranging from 0 to 1, defaults to
22611 This option is ignored when a file or a pattern is specified.
22613 @item random_seed, seed
22614 Set the seed for filling randomly the initial row, must be an integer
22615 included between 0 and UINT32_MAX. If not specified, or if explicitly
22616 set to -1, the filter will try to use a good random seed on a best
22620 Set the cellular automaton rule, it is a number ranging from 0 to 255.
22621 Default value is 110.
22624 Set the size of the output video. For the syntax of this option, check the
22625 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
22627 If @option{filename} or @option{pattern} is specified, the size is set
22628 by default to the width of the specified initial state row, and the
22629 height is set to @var{width} * PHI.
22631 If @option{size} is set, it must contain the width of the specified
22632 pattern string, and the specified pattern will be centered in the
22635 If a filename or a pattern string is not specified, the size value
22636 defaults to "320x518" (used for a randomly generated initial state).
22639 If set to 1, scroll the output upward when all the rows in the output
22640 have been already filled. If set to 0, the new generated row will be
22641 written over the top row just after the bottom row is filled.
22644 @item start_full, full
22645 If set to 1, completely fill the output with generated rows before
22646 outputting the first frame.
22647 This is the default behavior, for disabling set the value to 0.
22650 If set to 1, stitch the left and right row edges together.
22651 This is the default behavior, for disabling set the value to 0.
22654 @subsection Examples
22658 Read the initial state from @file{pattern}, and specify an output of
22661 cellauto=f=pattern:s=200x400
22665 Generate a random initial row with a width of 200 cells, with a fill
22668 cellauto=ratio=2/3:s=200x200
22672 Create a pattern generated by rule 18 starting by a single alive cell
22673 centered on an initial row with width 100:
22675 cellauto=p=@@:s=100x400:full=0:rule=18
22679 Specify a more elaborated initial pattern:
22681 cellauto=p='@@@@ @@ @@@@':s=100x400:full=0:rule=18
22686 @anchor{coreimagesrc}
22687 @section coreimagesrc
22688 Video source generated on GPU using Apple's CoreImage API on OSX.
22690 This video source is a specialized version of the @ref{coreimage} video filter.
22691 Use a core image generator at the beginning of the applied filterchain to
22692 generate the content.
22694 The coreimagesrc video source accepts the following options:
22696 @item list_generators
22697 List all available generators along with all their respective options as well as
22698 possible minimum and maximum values along with the default values.
22700 list_generators=true
22704 Specify the size of the sourced video. For the syntax of this option, check the
22705 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
22706 The default value is @code{320x240}.
22709 Specify the frame rate of the sourced video, as the number of frames
22710 generated per second. It has to be a string in the format
22711 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
22712 number or a valid video frame rate abbreviation. The default value is
22716 Set the sample aspect ratio of the sourced video.
22719 Set the duration of the sourced video. See
22720 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
22721 for the accepted syntax.
22723 If not specified, or the expressed duration is negative, the video is
22724 supposed to be generated forever.
22727 Additionally, all options of the @ref{coreimage} video filter are accepted.
22728 A complete filterchain can be used for further processing of the
22729 generated input without CPU-HOST transfer. See @ref{coreimage} documentation
22730 and examples for details.
22732 @subsection Examples
22737 Use CIQRCodeGenerator to create a QR code for the FFmpeg homepage,
22738 given as complete and escaped command-line for Apple's standard bash shell:
22740 ffmpeg -f lavfi -i coreimagesrc=s=100x100:filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png
22742 This example is equivalent to the QRCode example of @ref{coreimage} without the
22743 need for a nullsrc video source.
22748 Generate several gradients.
22752 Set frame size. For the syntax of this option, check the @ref{video size syntax,,"Video
22753 size" section in the ffmpeg-utils manual,ffmpeg-utils}. Default value is "640x480".
22756 Set frame rate, expressed as number of frames per second. Default
22759 @item c0, c1, c2, c3, c4, c5, c6, c7
22760 Set 8 colors. Default values for colors is to pick random one.
22762 @item x0, y0, y0, y1
22763 Set gradient line source and destination points. If negative or out of range, random ones
22767 Set number of colors to use at once. Allowed range is from 2 to 8. Default value is 2.
22770 Set seed for picking gradient line points.
22773 Set the duration of the sourced video. See
22774 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
22775 for the accepted syntax.
22777 If not specified, or the expressed duration is negative, the video is
22778 supposed to be generated forever.
22781 Set speed of gradients rotation.
22785 @section mandelbrot
22787 Generate a Mandelbrot set fractal, and progressively zoom towards the
22788 point specified with @var{start_x} and @var{start_y}.
22790 This source accepts the following options:
22795 Set the terminal pts value. Default value is 400.
22798 Set the terminal scale value.
22799 Must be a floating point value. Default value is 0.3.
22802 Set the inner coloring mode, that is the algorithm used to draw the
22803 Mandelbrot fractal internal region.
22805 It shall assume one of the following values:
22810 Show time until convergence.
22812 Set color based on point closest to the origin of the iterations.
22817 Default value is @var{mincol}.
22820 Set the bailout value. Default value is 10.0.
22823 Set the maximum of iterations performed by the rendering
22824 algorithm. Default value is 7189.
22827 Set outer coloring mode.
22828 It shall assume one of following values:
22830 @item iteration_count
22831 Set iteration count mode.
22832 @item normalized_iteration_count
22833 set normalized iteration count mode.
22835 Default value is @var{normalized_iteration_count}.
22838 Set frame rate, expressed as number of frames per second. Default
22842 Set frame size. For the syntax of this option, check the @ref{video size syntax,,"Video
22843 size" section in the ffmpeg-utils manual,ffmpeg-utils}. Default value is "640x480".
22846 Set the initial scale value. Default value is 3.0.
22849 Set the initial x position. Must be a floating point value between
22850 -100 and 100. Default value is -0.743643887037158704752191506114774.
22853 Set the initial y position. Must be a floating point value between
22854 -100 and 100. Default value is -0.131825904205311970493132056385139.
22859 Generate various test patterns, as generated by the MPlayer test filter.
22861 The size of the generated video is fixed, and is 256x256.
22862 This source is useful in particular for testing encoding features.
22864 This source accepts the following options:
22869 Specify the frame rate of the sourced video, as the number of frames
22870 generated per second. It has to be a string in the format
22871 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
22872 number or a valid video frame rate abbreviation. The default value is
22876 Set the duration of the sourced video. See
22877 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
22878 for the accepted syntax.
22880 If not specified, or the expressed duration is negative, the video is
22881 supposed to be generated forever.
22885 Set the number or the name of the test to perform. Supported tests are:
22899 @item max_frames, m
22900 Set the maximum number of frames generated for each test, default value is 30.
22904 Default value is "all", which will cycle through the list of all tests.
22909 mptestsrc=t=dc_luma
22912 will generate a "dc_luma" test pattern.
22914 @section frei0r_src
22916 Provide a frei0r source.
22918 To enable compilation of this filter you need to install the frei0r
22919 header and configure FFmpeg with @code{--enable-frei0r}.
22921 This source accepts the following parameters:
22926 The size of the video to generate. For the syntax of this option, check the
22927 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
22930 The framerate of the generated video. It may be a string of the form
22931 @var{num}/@var{den} or a frame rate abbreviation.
22934 The name to the frei0r source to load. For more information regarding frei0r and
22935 how to set the parameters, read the @ref{frei0r} section in the video filters
22938 @item filter_params
22939 A '|'-separated list of parameters to pass to the frei0r source.
22943 For example, to generate a frei0r partik0l source with size 200x200
22944 and frame rate 10 which is overlaid on the overlay filter main input:
22946 frei0r_src=size=200x200:framerate=10:filter_name=partik0l:filter_params=1234 [overlay]; [in][overlay] overlay
22951 Generate a life pattern.
22953 This source is based on a generalization of John Conway's life game.
22955 The sourced input represents a life grid, each pixel represents a cell
22956 which can be in one of two possible states, alive or dead. Every cell
22957 interacts with its eight neighbours, which are the cells that are
22958 horizontally, vertically, or diagonally adjacent.
22960 At each interaction the grid evolves according to the adopted rule,
22961 which specifies the number of neighbor alive cells which will make a
22962 cell stay alive or born. The @option{rule} option allows one to specify
22965 This source accepts the following options:
22969 Set the file from which to read the initial grid state. In the file,
22970 each non-whitespace character is considered an alive cell, and newline
22971 is used to delimit the end of each row.
22973 If this option is not specified, the initial grid is generated
22977 Set the video rate, that is the number of frames generated per second.
22980 @item random_fill_ratio, ratio
22981 Set the random fill ratio for the initial random grid. It is a
22982 floating point number value ranging from 0 to 1, defaults to 1/PHI.
22983 It is ignored when a file is specified.
22985 @item random_seed, seed
22986 Set the seed for filling the initial random grid, must be an integer
22987 included between 0 and UINT32_MAX. If not specified, or if explicitly
22988 set to -1, the filter will try to use a good random seed on a best
22994 A rule can be specified with a code of the kind "S@var{NS}/B@var{NB}",
22995 where @var{NS} and @var{NB} are sequences of numbers in the range 0-8,
22996 @var{NS} specifies the number of alive neighbor cells which make a
22997 live cell stay alive, and @var{NB} the number of alive neighbor cells
22998 which make a dead cell to become alive (i.e. to "born").
22999 "s" and "b" can be used in place of "S" and "B", respectively.
23001 Alternatively a rule can be specified by an 18-bits integer. The 9
23002 high order bits are used to encode the next cell state if it is alive
23003 for each number of neighbor alive cells, the low order bits specify
23004 the rule for "borning" new cells. Higher order bits encode for an
23005 higher number of neighbor cells.
23006 For example the number 6153 = @code{(12<<9)+9} specifies a stay alive
23007 rule of 12 and a born rule of 9, which corresponds to "S23/B03".
23009 Default value is "S23/B3", which is the original Conway's game of life
23010 rule, and will keep a cell alive if it has 2 or 3 neighbor alive
23011 cells, and will born a new cell if there are three alive cells around
23015 Set the size of the output video. For the syntax of this option, check the
23016 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23018 If @option{filename} is specified, the size is set by default to the
23019 same size of the input file. If @option{size} is set, it must contain
23020 the size specified in the input file, and the initial grid defined in
23021 that file is centered in the larger resulting area.
23023 If a filename is not specified, the size value defaults to "320x240"
23024 (used for a randomly generated initial grid).
23027 If set to 1, stitch the left and right grid edges together, and the
23028 top and bottom edges also. Defaults to 1.
23031 Set cell mold speed. If set, a dead cell will go from @option{death_color} to
23032 @option{mold_color} with a step of @option{mold}. @option{mold} can have a
23033 value from 0 to 255.
23036 Set the color of living (or new born) cells.
23039 Set the color of dead cells. If @option{mold} is set, this is the first color
23040 used to represent a dead cell.
23043 Set mold color, for definitely dead and moldy cells.
23045 For the syntax of these 3 color options, check the @ref{color syntax,,"Color" section in the
23046 ffmpeg-utils manual,ffmpeg-utils}.
23049 @subsection Examples
23053 Read a grid from @file{pattern}, and center it on a grid of size
23056 life=f=pattern:s=300x300
23060 Generate a random grid of size 200x200, with a fill ratio of 2/3:
23062 life=ratio=2/3:s=200x200
23066 Specify a custom rule for evolving a randomly generated grid:
23072 Full example with slow death effect (mold) using @command{ffplay}:
23074 ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16
23081 @anchor{haldclutsrc}
23084 @anchor{pal100bars}
23085 @anchor{rgbtestsrc}
23087 @anchor{smptehdbars}
23090 @anchor{yuvtestsrc}
23091 @section allrgb, allyuv, color, haldclutsrc, nullsrc, pal75bars, pal100bars, rgbtestsrc, smptebars, smptehdbars, testsrc, testsrc2, yuvtestsrc
23093 The @code{allrgb} source returns frames of size 4096x4096 of all rgb colors.
23095 The @code{allyuv} source returns frames of size 4096x4096 of all yuv colors.
23097 The @code{color} source provides an uniformly colored input.
23099 The @code{haldclutsrc} source provides an identity Hald CLUT. See also
23100 @ref{haldclut} filter.
23102 The @code{nullsrc} source returns unprocessed video frames. It is
23103 mainly useful to be employed in analysis / debugging tools, or as the
23104 source for filters which ignore the input data.
23106 The @code{pal75bars} source generates a color bars pattern, based on
23107 EBU PAL recommendations with 75% color levels.
23109 The @code{pal100bars} source generates a color bars pattern, based on
23110 EBU PAL recommendations with 100% color levels.
23112 The @code{rgbtestsrc} source generates an RGB test pattern useful for
23113 detecting RGB vs BGR issues. You should see a red, green and blue
23114 stripe from top to bottom.
23116 The @code{smptebars} source generates a color bars pattern, based on
23117 the SMPTE Engineering Guideline EG 1-1990.
23119 The @code{smptehdbars} source generates a color bars pattern, based on
23120 the SMPTE RP 219-2002.
23122 The @code{testsrc} source generates a test video pattern, showing a
23123 color pattern, a scrolling gradient and a timestamp. This is mainly
23124 intended for testing purposes.
23126 The @code{testsrc2} source is similar to testsrc, but supports more
23127 pixel formats instead of just @code{rgb24}. This allows using it as an
23128 input for other tests without requiring a format conversion.
23130 The @code{yuvtestsrc} source generates an YUV test pattern. You should
23131 see a y, cb and cr stripe from top to bottom.
23133 The sources accept the following parameters:
23138 Specify the level of the Hald CLUT, only available in the @code{haldclutsrc}
23139 source. A level of @code{N} generates a picture of @code{N*N*N} by @code{N*N*N}
23140 pixels to be used as identity matrix for 3D lookup tables. Each component is
23141 coded on a @code{1/(N*N)} scale.
23144 Specify the color of the source, only available in the @code{color}
23145 source. For the syntax of this option, check the
23146 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
23149 Specify the size of the sourced video. For the syntax of this option, check the
23150 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23151 The default value is @code{320x240}.
23153 This option is not available with the @code{allrgb}, @code{allyuv}, and
23154 @code{haldclutsrc} filters.
23157 Specify the frame rate of the sourced video, as the number of frames
23158 generated per second. It has to be a string in the format
23159 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
23160 number or a valid video frame rate abbreviation. The default value is
23164 Set the duration of the sourced video. See
23165 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
23166 for the accepted syntax.
23168 If not specified, or the expressed duration is negative, the video is
23169 supposed to be generated forever.
23171 Since the frame rate is used as time base, all frames including the last one
23172 will have their full duration. If the specified duration is not a multiple
23173 of the frame duration, it will be rounded up.
23176 Set the sample aspect ratio of the sourced video.
23179 Specify the alpha (opacity) of the background, only available in the
23180 @code{testsrc2} source. The value must be between 0 (fully transparent) and
23181 255 (fully opaque, the default).
23184 Set the number of decimals to show in the timestamp, only available in the
23185 @code{testsrc} source.
23187 The displayed timestamp value will correspond to the original
23188 timestamp value multiplied by the power of 10 of the specified
23189 value. Default value is 0.
23192 @subsection Examples
23196 Generate a video with a duration of 5.3 seconds, with size
23197 176x144 and a frame rate of 10 frames per second:
23199 testsrc=duration=5.3:size=qcif:rate=10
23203 The following graph description will generate a red source
23204 with an opacity of 0.2, with size "qcif" and a frame rate of 10
23207 color=c=red@@0.2:s=qcif:r=10
23211 If the input content is to be ignored, @code{nullsrc} can be used. The
23212 following command generates noise in the luminance plane by employing
23213 the @code{geq} filter:
23215 nullsrc=s=256x256, geq=random(1)*255:128:128
23219 @subsection Commands
23221 The @code{color} source supports the following commands:
23225 Set the color of the created image. Accepts the same syntax of the
23226 corresponding @option{color} option.
23231 Generate video using an OpenCL program.
23236 OpenCL program source file.
23239 Kernel name in program.
23242 Size of frames to generate. This must be set.
23245 Pixel format to use for the generated frames. This must be set.
23248 Number of frames generated every second. Default value is '25'.
23252 For details of how the program loading works, see the @ref{program_opencl}
23259 Generate a colour ramp by setting pixel values from the position of the pixel
23260 in the output image. (Note that this will work with all pixel formats, but
23261 the generated output will not be the same.)
23263 __kernel void ramp(__write_only image2d_t dst,
23264 unsigned int index)
23266 int2 loc = (int2)(get_global_id(0), get_global_id(1));
23269 val.xy = val.zw = convert_float2(loc) / convert_float2(get_image_dim(dst));
23271 write_imagef(dst, loc, val);
23276 Generate a Sierpinski carpet pattern, panning by a single pixel each frame.
23278 __kernel void sierpinski_carpet(__write_only image2d_t dst,
23279 unsigned int index)
23281 int2 loc = (int2)(get_global_id(0), get_global_id(1));
23283 float4 value = 0.0f;
23284 int x = loc.x + index;
23285 int y = loc.y + index;
23286 while (x > 0 || y > 0) {
23287 if (x % 3 == 1 && y % 3 == 1) {
23295 write_imagef(dst, loc, value);
23301 @section sierpinski
23303 Generate a Sierpinski carpet/triangle fractal, and randomly pan around.
23305 This source accepts the following options:
23309 Set frame size. For the syntax of this option, check the @ref{video size syntax,,"Video
23310 size" section in the ffmpeg-utils manual,ffmpeg-utils}. Default value is "640x480".
23313 Set frame rate, expressed as number of frames per second. Default
23317 Set seed which is used for random panning.
23320 Set max jump for single pan destination. Allowed range is from 1 to 10000.
23323 Set fractal type, can be default @code{carpet} or @code{triangle}.
23326 @c man end VIDEO SOURCES
23328 @chapter Video Sinks
23329 @c man begin VIDEO SINKS
23331 Below is a description of the currently available video sinks.
23333 @section buffersink
23335 Buffer video frames, and make them available to the end of the filter
23338 This sink is mainly intended for programmatic use, in particular
23339 through the interface defined in @file{libavfilter/buffersink.h}
23340 or the options system.
23342 It accepts a pointer to an AVBufferSinkContext structure, which
23343 defines the incoming buffers' formats, to be passed as the opaque
23344 parameter to @code{avfilter_init_filter} for initialization.
23348 Null video sink: do absolutely nothing with the input video. It is
23349 mainly useful as a template and for use in analysis / debugging
23352 @c man end VIDEO SINKS
23354 @chapter Multimedia Filters
23355 @c man begin MULTIMEDIA FILTERS
23357 Below is a description of the currently available multimedia filters.
23361 Convert input audio to a video output, displaying the audio bit scope.
23363 The filter accepts the following options:
23367 Set frame rate, expressed as number of frames per second. Default
23371 Specify the video size for the output. For the syntax of this option, check the
23372 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23373 Default value is @code{1024x256}.
23376 Specify list of colors separated by space or by '|' which will be used to
23377 draw channels. Unrecognized or missing colors will be replaced
23381 @section adrawgraph
23382 Draw a graph using input audio metadata.
23384 See @ref{drawgraph}
23386 @section agraphmonitor
23388 See @ref{graphmonitor}.
23390 @section ahistogram
23392 Convert input audio to a video output, displaying the volume histogram.
23394 The filter accepts the following options:
23398 Specify how histogram is calculated.
23400 It accepts the following values:
23403 Use single histogram for all channels.
23405 Use separate histogram for each channel.
23407 Default is @code{single}.
23410 Set frame rate, expressed as number of frames per second. Default
23414 Specify the video size for the output. For the syntax of this option, check the
23415 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23416 Default value is @code{hd720}.
23421 It accepts the following values:
23432 reverse logarithmic
23434 Default is @code{log}.
23437 Set amplitude scale.
23439 It accepts the following values:
23446 Default is @code{log}.
23449 Set how much frames to accumulate in histogram.
23450 Default is 1. Setting this to -1 accumulates all frames.
23453 Set histogram ratio of window height.
23456 Set sonogram sliding.
23458 It accepts the following values:
23461 replace old rows with new ones.
23463 scroll from top to bottom.
23465 Default is @code{replace}.
23468 @section aphasemeter
23470 Measures phase of input audio, which is exported as metadata @code{lavfi.aphasemeter.phase},
23471 representing mean phase of current audio frame. A video output can also be produced and is
23472 enabled by default. The audio is passed through as first output.
23474 Audio will be rematrixed to stereo if it has a different channel layout. Phase value is in
23475 range @code{[-1, 1]} where @code{-1} means left and right channels are completely out of phase
23476 and @code{1} means channels are in phase.
23478 The filter accepts the following options, all related to its video output:
23482 Set the output frame rate. Default value is @code{25}.
23485 Set the video size for the output. For the syntax of this option, check the
23486 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23487 Default value is @code{800x400}.
23492 Specify the red, green, blue contrast. Default values are @code{2},
23493 @code{7} and @code{1}.
23494 Allowed range is @code{[0, 255]}.
23497 Set color which will be used for drawing median phase. If color is
23498 @code{none} which is default, no median phase value will be drawn.
23501 Enable video output. Default is enabled.
23504 @subsection phasing detection
23506 The filter also detects out of phase and mono sequences in stereo streams.
23507 It logs the sequence start, end and duration when it lasts longer or as long as the minimum set.
23509 The filter accepts the following options for this detection:
23513 Enable mono and out of phase detection. Default is disabled.
23516 Set phase tolerance for mono detection, in amplitude ratio. Default is @code{0}.
23517 Allowed range is @code{[0, 1]}.
23520 Set angle threshold for out of phase detection, in degree. Default is @code{170}.
23521 Allowed range is @code{[90, 180]}.
23524 Set mono or out of phase duration until notification, expressed in seconds. Default is @code{2}.
23527 @subsection Examples
23531 Complete example with @command{ffmpeg} to detect 1 second of mono with 0.001 phase tolerance:
23533 ffmpeg -i stereo.wav -af aphasemeter=video=0:phasing=1:duration=1:tolerance=0.001 -f null -
23537 @section avectorscope
23539 Convert input audio to a video output, representing the audio vector
23542 The filter is used to measure the difference between channels of stereo
23543 audio stream. A monaural signal, consisting of identical left and right
23544 signal, results in straight vertical line. Any stereo separation is visible
23545 as a deviation from this line, creating a Lissajous figure.
23546 If the straight (or deviation from it) but horizontal line appears this
23547 indicates that the left and right channels are out of phase.
23549 The filter accepts the following options:
23553 Set the vectorscope mode.
23555 Available values are:
23558 Lissajous rotated by 45 degrees.
23561 Same as above but not rotated.
23564 Shape resembling half of circle.
23567 Default value is @samp{lissajous}.
23570 Set the video size for the output. For the syntax of this option, check the
23571 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23572 Default value is @code{400x400}.
23575 Set the output frame rate. Default value is @code{25}.
23581 Specify the red, green, blue and alpha contrast. Default values are @code{40},
23582 @code{160}, @code{80} and @code{255}.
23583 Allowed range is @code{[0, 255]}.
23589 Specify the red, green, blue and alpha fade. Default values are @code{15},
23590 @code{10}, @code{5} and @code{5}.
23591 Allowed range is @code{[0, 255]}.
23594 Set the zoom factor. Default value is @code{1}. Allowed range is @code{[0, 10]}.
23595 Values lower than @var{1} will auto adjust zoom factor to maximal possible value.
23598 Set the vectorscope drawing mode.
23600 Available values are:
23603 Draw dot for each sample.
23606 Draw line between previous and current sample.
23609 Default value is @samp{dot}.
23612 Specify amplitude scale of audio samples.
23614 Available values are:
23630 Swap left channel axis with right channel axis.
23640 Mirror only x axis.
23643 Mirror only y axis.
23651 @subsection Examples
23655 Complete example using @command{ffplay}:
23657 ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
23658 [a] avectorscope=zoom=1.3:rc=2:gc=200:bc=10:rf=1:gf=8:bf=7 [out0]'
23662 @section bench, abench
23664 Benchmark part of a filtergraph.
23666 The filter accepts the following options:
23670 Start or stop a timer.
23672 Available values are:
23675 Get the current time, set it as frame metadata (using the key
23676 @code{lavfi.bench.start_time}), and forward the frame to the next filter.
23679 Get the current time and fetch the @code{lavfi.bench.start_time} metadata from
23680 the input frame metadata to get the time difference. Time difference, average,
23681 maximum and minimum time (respectively @code{t}, @code{avg}, @code{max} and
23682 @code{min}) are then printed. The timestamps are expressed in seconds.
23686 @subsection Examples
23690 Benchmark @ref{selectivecolor} filter:
23692 bench=start,selectivecolor=reds=-.2 .12 -.49,bench=stop
23698 Concatenate audio and video streams, joining them together one after the
23701 The filter works on segments of synchronized video and audio streams. All
23702 segments must have the same number of streams of each type, and that will
23703 also be the number of streams at output.
23705 The filter accepts the following options:
23710 Set the number of segments. Default is 2.
23713 Set the number of output video streams, that is also the number of video
23714 streams in each segment. Default is 1.
23717 Set the number of output audio streams, that is also the number of audio
23718 streams in each segment. Default is 0.
23721 Activate unsafe mode: do not fail if segments have a different format.
23725 The filter has @var{v}+@var{a} outputs: first @var{v} video outputs, then
23726 @var{a} audio outputs.
23728 There are @var{n}x(@var{v}+@var{a}) inputs: first the inputs for the first
23729 segment, in the same order as the outputs, then the inputs for the second
23732 Related streams do not always have exactly the same duration, for various
23733 reasons including codec frame size or sloppy authoring. For that reason,
23734 related synchronized streams (e.g. a video and its audio track) should be
23735 concatenated at once. The concat filter will use the duration of the longest
23736 stream in each segment (except the last one), and if necessary pad shorter
23737 audio streams with silence.
23739 For this filter to work correctly, all segments must start at timestamp 0.
23741 All corresponding streams must have the same parameters in all segments; the
23742 filtering system will automatically select a common pixel format for video
23743 streams, and a common sample format, sample rate and channel layout for
23744 audio streams, but other settings, such as resolution, must be converted
23745 explicitly by the user.
23747 Different frame rates are acceptable but will result in variable frame rate
23748 at output; be sure to configure the output file to handle it.
23750 @subsection Examples
23754 Concatenate an opening, an episode and an ending, all in bilingual version
23755 (video in stream 0, audio in streams 1 and 2):
23757 ffmpeg -i opening.mkv -i episode.mkv -i ending.mkv -filter_complex \
23758 '[0:0] [0:1] [0:2] [1:0] [1:1] [1:2] [2:0] [2:1] [2:2]
23759 concat=n=3:v=1:a=2 [v] [a1] [a2]' \
23760 -map '[v]' -map '[a1]' -map '[a2]' output.mkv
23764 Concatenate two parts, handling audio and video separately, using the
23765 (a)movie sources, and adjusting the resolution:
23767 movie=part1.mp4, scale=512:288 [v1] ; amovie=part1.mp4 [a1] ;
23768 movie=part2.mp4, scale=512:288 [v2] ; amovie=part2.mp4 [a2] ;
23769 [v1] [v2] concat [outv] ; [a1] [a2] concat=v=0:a=1 [outa]
23771 Note that a desync will happen at the stitch if the audio and video streams
23772 do not have exactly the same duration in the first file.
23776 @subsection Commands
23778 This filter supports the following commands:
23781 Close the current segment and step to the next one
23787 EBU R128 scanner filter. This filter takes an audio stream and analyzes its loudness
23788 level. By default, it logs a message at a frequency of 10Hz with the
23789 Momentary loudness (identified by @code{M}), Short-term loudness (@code{S}),
23790 Integrated loudness (@code{I}) and Loudness Range (@code{LRA}).
23792 The filter can only analyze streams which have a sampling rate of 48000 Hz and whose
23793 sample format is double-precision floating point. The input stream will be converted to
23794 this specification, if needed. Users may need to insert aformat and/or aresample filters
23795 after this filter to obtain the original parameters.
23797 The filter also has a video output (see the @var{video} option) with a real
23798 time graph to observe the loudness evolution. The graphic contains the logged
23799 message mentioned above, so it is not printed anymore when this option is set,
23800 unless the verbose logging is set. The main graphing area contains the
23801 short-term loudness (3 seconds of analysis), and the gauge on the right is for
23802 the momentary loudness (400 milliseconds), but can optionally be configured
23803 to instead display short-term loudness (see @var{gauge}).
23805 The green area marks a +/- 1LU target range around the target loudness
23806 (-23LUFS by default, unless modified through @var{target}).
23808 More information about the Loudness Recommendation EBU R128 on
23809 @url{http://tech.ebu.ch/loudness}.
23811 The filter accepts the following options:
23816 Activate the video output. The audio stream is passed unchanged whether this
23817 option is set or no. The video stream will be the first output stream if
23818 activated. Default is @code{0}.
23821 Set the video size. This option is for video only. For the syntax of this
23823 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23824 Default and minimum resolution is @code{640x480}.
23827 Set the EBU scale meter. Default is @code{9}. Common values are @code{9} and
23828 @code{18}, respectively for EBU scale meter +9 and EBU scale meter +18. Any
23829 other integer value between this range is allowed.
23832 Set metadata injection. If set to @code{1}, the audio input will be segmented
23833 into 100ms output frames, each of them containing various loudness information
23834 in metadata. All the metadata keys are prefixed with @code{lavfi.r128.}.
23836 Default is @code{0}.
23839 Force the frame logging level.
23841 Available values are:
23844 information logging level
23846 verbose logging level
23849 By default, the logging level is set to @var{info}. If the @option{video} or
23850 the @option{metadata} options are set, it switches to @var{verbose}.
23855 Available modes can be cumulated (the option is a @code{flag} type). Possible
23859 Disable any peak mode (default).
23861 Enable sample-peak mode.
23863 Simple peak mode looking for the higher sample value. It logs a message
23864 for sample-peak (identified by @code{SPK}).
23866 Enable true-peak mode.
23868 If enabled, the peak lookup is done on an over-sampled version of the input
23869 stream for better peak accuracy. It logs a message for true-peak.
23870 (identified by @code{TPK}) and true-peak per frame (identified by @code{FTPK}).
23871 This mode requires a build with @code{libswresample}.
23875 Treat mono input files as "dual mono". If a mono file is intended for playback
23876 on a stereo system, its EBU R128 measurement will be perceptually incorrect.
23877 If set to @code{true}, this option will compensate for this effect.
23878 Multi-channel input files are not affected by this option.
23881 Set a specific pan law to be used for the measurement of dual mono files.
23882 This parameter is optional, and has a default value of -3.01dB.
23885 Set a specific target level (in LUFS) used as relative zero in the visualization.
23886 This parameter is optional and has a default value of -23LUFS as specified
23887 by EBU R128. However, material published online may prefer a level of -16LUFS
23888 (e.g. for use with podcasts or video platforms).
23891 Set the value displayed by the gauge. Valid values are @code{momentary} and s
23892 @code{shortterm}. By default the momentary value will be used, but in certain
23893 scenarios it may be more useful to observe the short term value instead (e.g.
23897 Sets the display scale for the loudness. Valid parameters are @code{absolute}
23898 (in LUFS) or @code{relative} (LU) relative to the target. This only affects the
23899 video output, not the summary or continuous log output.
23902 @subsection Examples
23906 Real-time graph using @command{ffplay}, with a EBU scale meter +18:
23908 ffplay -f lavfi -i "amovie=input.mp3,ebur128=video=1:meter=18 [out0][out1]"
23912 Run an analysis with @command{ffmpeg}:
23914 ffmpeg -nostats -i input.mp3 -filter_complex ebur128 -f null -
23918 @section interleave, ainterleave
23920 Temporally interleave frames from several inputs.
23922 @code{interleave} works with video inputs, @code{ainterleave} with audio.
23924 These filters read frames from several inputs and send the oldest
23925 queued frame to the output.
23927 Input streams must have well defined, monotonically increasing frame
23930 In order to submit one frame to output, these filters need to enqueue
23931 at least one frame for each input, so they cannot work in case one
23932 input is not yet terminated and will not receive incoming frames.
23934 For example consider the case when one input is a @code{select} filter
23935 which always drops input frames. The @code{interleave} filter will keep
23936 reading from that input, but it will never be able to send new frames
23937 to output until the input sends an end-of-stream signal.
23939 Also, depending on inputs synchronization, the filters will drop
23940 frames in case one input receives more frames than the other ones, and
23941 the queue is already filled.
23943 These filters accept the following options:
23947 Set the number of different inputs, it is 2 by default.
23950 How to determine the end-of-stream.
23954 The duration of the longest input. (default)
23957 The duration of the shortest input.
23960 The duration of the first input.
23965 @subsection Examples
23969 Interleave frames belonging to different streams using @command{ffmpeg}:
23971 ffmpeg -i bambi.avi -i pr0n.mkv -filter_complex "[0:v][1:v] interleave" out.avi
23975 Add flickering blur effect:
23977 select='if(gt(random(0), 0.2), 1, 2)':n=2 [tmp], boxblur=2:2, [tmp] interleave
23981 @section metadata, ametadata
23983 Manipulate frame metadata.
23985 This filter accepts the following options:
23989 Set mode of operation of the filter.
23991 Can be one of the following:
23995 If both @code{value} and @code{key} is set, select frames
23996 which have such metadata. If only @code{key} is set, select
23997 every frame that has such key in metadata.
24000 Add new metadata @code{key} and @code{value}. If key is already available
24004 Modify value of already present key.
24007 If @code{value} is set, delete only keys that have such value.
24008 Otherwise, delete key. If @code{key} is not set, delete all metadata values in
24012 Print key and its value if metadata was found. If @code{key} is not set print all
24013 metadata values available in frame.
24017 Set key used with all modes. Must be set for all modes except @code{print} and @code{delete}.
24020 Set metadata value which will be used. This option is mandatory for
24021 @code{modify} and @code{add} mode.
24024 Which function to use when comparing metadata value and @code{value}.
24026 Can be one of following:
24030 Values are interpreted as strings, returns true if metadata value is same as @code{value}.
24033 Values are interpreted as strings, returns true if metadata value starts with
24034 the @code{value} option string.
24037 Values are interpreted as floats, returns true if metadata value is less than @code{value}.
24040 Values are interpreted as floats, returns true if @code{value} is equal with metadata value.
24043 Values are interpreted as floats, returns true if metadata value is greater than @code{value}.
24046 Values are interpreted as floats, returns true if expression from option @code{expr}
24050 Values are interpreted as strings, returns true if metadata value ends with
24051 the @code{value} option string.
24055 Set expression which is used when @code{function} is set to @code{expr}.
24056 The expression is evaluated through the eval API and can contain the following
24061 Float representation of @code{value} from metadata key.
24064 Float representation of @code{value} as supplied by user in @code{value} option.
24068 If specified in @code{print} mode, output is written to the named file. Instead of
24069 plain filename any writable url can be specified. Filename ``-'' is a shorthand
24070 for standard output. If @code{file} option is not set, output is written to the log
24071 with AV_LOG_INFO loglevel.
24074 Reduces buffering in print mode when output is written to a URL set using @var{file}.
24078 @subsection Examples
24082 Print all metadata values for frames with key @code{lavfi.signalstats.YDIF} with values
24085 signalstats,metadata=print:key=lavfi.signalstats.YDIF:value=0:function=expr:expr='between(VALUE1,0,1)'
24088 Print silencedetect output to file @file{metadata.txt}.
24090 silencedetect,ametadata=mode=print:file=metadata.txt
24093 Direct all metadata to a pipe with file descriptor 4.
24095 metadata=mode=print:file='pipe\:4'
24099 @section perms, aperms
24101 Set read/write permissions for the output frames.
24103 These filters are mainly aimed at developers to test direct path in the
24104 following filter in the filtergraph.
24106 The filters accept the following options:
24110 Select the permissions mode.
24112 It accepts the following values:
24115 Do nothing. This is the default.
24117 Set all the output frames read-only.
24119 Set all the output frames directly writable.
24121 Make the frame read-only if writable, and writable if read-only.
24123 Set each output frame read-only or writable randomly.
24127 Set the seed for the @var{random} mode, must be an integer included between
24128 @code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to
24129 @code{-1}, the filter will try to use a good random seed on a best effort
24133 Note: in case of auto-inserted filter between the permission filter and the
24134 following one, the permission might not be received as expected in that
24135 following filter. Inserting a @ref{format} or @ref{aformat} filter before the
24136 perms/aperms filter can avoid this problem.
24138 @section realtime, arealtime
24140 Slow down filtering to match real time approximately.
24142 These filters will pause the filtering for a variable amount of time to
24143 match the output rate with the input timestamps.
24144 They are similar to the @option{re} option to @code{ffmpeg}.
24146 They accept the following options:
24150 Time limit for the pauses. Any pause longer than that will be considered
24151 a timestamp discontinuity and reset the timer. Default is 2 seconds.
24153 Speed factor for processing. The value must be a float larger than zero.
24154 Values larger than 1.0 will result in faster than realtime processing,
24155 smaller will slow processing down. The @var{limit} is automatically adapted
24156 accordingly. Default is 1.0.
24158 A processing speed faster than what is possible without these filters cannot
24163 @section select, aselect
24165 Select frames to pass in output.
24167 This filter accepts the following options:
24172 Set expression, which is evaluated for each input frame.
24174 If the expression is evaluated to zero, the frame is discarded.
24176 If the evaluation result is negative or NaN, the frame is sent to the
24177 first output; otherwise it is sent to the output with index
24178 @code{ceil(val)-1}, assuming that the input index starts from 0.
24180 For example a value of @code{1.2} corresponds to the output with index
24181 @code{ceil(1.2)-1 = 2-1 = 1}, that is the second output.
24184 Set the number of outputs. The output to which to send the selected
24185 frame is based on the result of the evaluation. Default value is 1.
24188 The expression can contain the following constants:
24192 The (sequential) number of the filtered frame, starting from 0.
24195 The (sequential) number of the selected frame, starting from 0.
24197 @item prev_selected_n
24198 The sequential number of the last selected frame. It's NAN if undefined.
24201 The timebase of the input timestamps.
24204 The PTS (Presentation TimeStamp) of the filtered video frame,
24205 expressed in @var{TB} units. It's NAN if undefined.
24208 The PTS of the filtered video frame,
24209 expressed in seconds. It's NAN if undefined.
24212 The PTS of the previously filtered video frame. It's NAN if undefined.
24214 @item prev_selected_pts
24215 The PTS of the last previously filtered video frame. It's NAN if undefined.
24217 @item prev_selected_t
24218 The PTS of the last previously selected video frame, expressed in seconds. It's NAN if undefined.
24221 The PTS of the first video frame in the video. It's NAN if undefined.
24224 The time of the first video frame in the video. It's NAN if undefined.
24226 @item pict_type @emph{(video only)}
24227 The type of the filtered frame. It can assume one of the following
24239 @item interlace_type @emph{(video only)}
24240 The frame interlace type. It can assume one of the following values:
24243 The frame is progressive (not interlaced).
24245 The frame is top-field-first.
24247 The frame is bottom-field-first.
24250 @item consumed_sample_n @emph{(audio only)}
24251 the number of selected samples before the current frame
24253 @item samples_n @emph{(audio only)}
24254 the number of samples in the current frame
24256 @item sample_rate @emph{(audio only)}
24257 the input sample rate
24260 This is 1 if the filtered frame is a key-frame, 0 otherwise.
24263 the position in the file of the filtered frame, -1 if the information
24264 is not available (e.g. for synthetic video)
24266 @item scene @emph{(video only)}
24267 value between 0 and 1 to indicate a new scene; a low value reflects a low
24268 probability for the current frame to introduce a new scene, while a higher
24269 value means the current frame is more likely to be one (see the example below)
24271 @item concatdec_select
24272 The concat demuxer can select only part of a concat input file by setting an
24273 inpoint and an outpoint, but the output packets may not be entirely contained
24274 in the selected interval. By using this variable, it is possible to skip frames
24275 generated by the concat demuxer which are not exactly contained in the selected
24278 This works by comparing the frame pts against the @var{lavf.concat.start_time}
24279 and the @var{lavf.concat.duration} packet metadata values which are also
24280 present in the decoded frames.
24282 The @var{concatdec_select} variable is -1 if the frame pts is at least
24283 start_time and either the duration metadata is missing or the frame pts is less
24284 than start_time + duration, 0 otherwise, and NaN if the start_time metadata is
24287 That basically means that an input frame is selected if its pts is within the
24288 interval set by the concat demuxer.
24292 The default value of the select expression is "1".
24294 @subsection Examples
24298 Select all frames in input:
24303 The example above is the same as:
24315 Select only I-frames:
24317 select='eq(pict_type\,I)'
24321 Select one frame every 100:
24323 select='not(mod(n\,100))'
24327 Select only frames contained in the 10-20 time interval:
24329 select=between(t\,10\,20)
24333 Select only I-frames contained in the 10-20 time interval:
24335 select=between(t\,10\,20)*eq(pict_type\,I)
24339 Select frames with a minimum distance of 10 seconds:
24341 select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)'
24345 Use aselect to select only audio frames with samples number > 100:
24347 aselect='gt(samples_n\,100)'
24351 Create a mosaic of the first scenes:
24353 ffmpeg -i video.avi -vf select='gt(scene\,0.4)',scale=160:120,tile -frames:v 1 preview.png
24356 Comparing @var{scene} against a value between 0.3 and 0.5 is generally a sane
24360 Send even and odd frames to separate outputs, and compose them:
24362 select=n=2:e='mod(n, 2)+1' [odd][even]; [odd] pad=h=2*ih [tmp]; [tmp][even] overlay=y=h
24366 Select useful frames from an ffconcat file which is using inpoints and
24367 outpoints but where the source files are not intra frame only.
24369 ffmpeg -copyts -vsync 0 -segment_time_metadata 1 -i input.ffconcat -vf select=concatdec_select -af aselect=concatdec_select output.avi
24373 @section sendcmd, asendcmd
24375 Send commands to filters in the filtergraph.
24377 These filters read commands to be sent to other filters in the
24380 @code{sendcmd} must be inserted between two video filters,
24381 @code{asendcmd} must be inserted between two audio filters, but apart
24382 from that they act the same way.
24384 The specification of commands can be provided in the filter arguments
24385 with the @var{commands} option, or in a file specified by the
24386 @var{filename} option.
24388 These filters accept the following options:
24391 Set the commands to be read and sent to the other filters.
24393 Set the filename of the commands to be read and sent to the other
24397 @subsection Commands syntax
24399 A commands description consists of a sequence of interval
24400 specifications, comprising a list of commands to be executed when a
24401 particular event related to that interval occurs. The occurring event
24402 is typically the current frame time entering or leaving a given time
24405 An interval is specified by the following syntax:
24407 @var{START}[-@var{END}] @var{COMMANDS};
24410 The time interval is specified by the @var{START} and @var{END} times.
24411 @var{END} is optional and defaults to the maximum time.
24413 The current frame time is considered within the specified interval if
24414 it is included in the interval [@var{START}, @var{END}), that is when
24415 the time is greater or equal to @var{START} and is lesser than
24418 @var{COMMANDS} consists of a sequence of one or more command
24419 specifications, separated by ",", relating to that interval. The
24420 syntax of a command specification is given by:
24422 [@var{FLAGS}] @var{TARGET} @var{COMMAND} @var{ARG}
24425 @var{FLAGS} is optional and specifies the type of events relating to
24426 the time interval which enable sending the specified command, and must
24427 be a non-null sequence of identifier flags separated by "+" or "|" and
24428 enclosed between "[" and "]".
24430 The following flags are recognized:
24433 The command is sent when the current frame timestamp enters the
24434 specified interval. In other words, the command is sent when the
24435 previous frame timestamp was not in the given interval, and the
24439 The command is sent when the current frame timestamp leaves the
24440 specified interval. In other words, the command is sent when the
24441 previous frame timestamp was in the given interval, and the
24445 The command @var{ARG} is interpreted as expression and result of
24446 expression is passed as @var{ARG}.
24448 The expression is evaluated through the eval API and can contain the following
24453 Original position in the file of the frame, or undefined if undefined
24454 for the current frame.
24457 The presentation timestamp in input.
24460 The count of the input frame for video or audio, starting from 0.
24463 The time in seconds of the current frame.
24466 The start time in seconds of the current command interval.
24469 The end time in seconds of the current command interval.
24472 The interpolated time of the current command interval, TI = (T - TS) / (TE - TS).
24477 If @var{FLAGS} is not specified, a default value of @code{[enter]} is
24480 @var{TARGET} specifies the target of the command, usually the name of
24481 the filter class or a specific filter instance name.
24483 @var{COMMAND} specifies the name of the command for the target filter.
24485 @var{ARG} is optional and specifies the optional list of argument for
24486 the given @var{COMMAND}.
24488 Between one interval specification and another, whitespaces, or
24489 sequences of characters starting with @code{#} until the end of line,
24490 are ignored and can be used to annotate comments.
24492 A simplified BNF description of the commands specification syntax
24495 @var{COMMAND_FLAG} ::= "enter" | "leave"
24496 @var{COMMAND_FLAGS} ::= @var{COMMAND_FLAG} [(+|"|")@var{COMMAND_FLAG}]
24497 @var{COMMAND} ::= ["[" @var{COMMAND_FLAGS} "]"] @var{TARGET} @var{COMMAND} [@var{ARG}]
24498 @var{COMMANDS} ::= @var{COMMAND} [,@var{COMMANDS}]
24499 @var{INTERVAL} ::= @var{START}[-@var{END}] @var{COMMANDS}
24500 @var{INTERVALS} ::= @var{INTERVAL}[;@var{INTERVALS}]
24503 @subsection Examples
24507 Specify audio tempo change at second 4:
24509 asendcmd=c='4.0 atempo tempo 1.5',atempo
24513 Target a specific filter instance:
24515 asendcmd=c='4.0 atempo@@my tempo 1.5',atempo@@my
24519 Specify a list of drawtext and hue commands in a file.
24521 # show text in the interval 5-10
24522 5.0-10.0 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=hello world',
24523 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=';
24525 # desaturate the image in the interval 15-20
24526 15.0-20.0 [enter] hue s 0,
24527 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=nocolor',
24529 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=color';
24531 # apply an exponential saturation fade-out effect, starting from time 25
24532 25 [enter] hue s exp(25-t)
24535 A filtergraph allowing to read and process the above command list
24536 stored in a file @file{test.cmd}, can be specified with:
24538 sendcmd=f=test.cmd,drawtext=fontfile=FreeSerif.ttf:text='',hue
24543 @section setpts, asetpts
24545 Change the PTS (presentation timestamp) of the input frames.
24547 @code{setpts} works on video frames, @code{asetpts} on audio frames.
24549 This filter accepts the following options:
24554 The expression which is evaluated for each frame to construct its timestamp.
24558 The expression is evaluated through the eval API and can contain the following
24562 @item FRAME_RATE, FR
24563 frame rate, only defined for constant frame-rate video
24566 The presentation timestamp in input
24569 The count of the input frame for video or the number of consumed samples,
24570 not including the current frame for audio, starting from 0.
24572 @item NB_CONSUMED_SAMPLES
24573 The number of consumed samples, not including the current frame (only
24576 @item NB_SAMPLES, S
24577 The number of samples in the current frame (only audio)
24579 @item SAMPLE_RATE, SR
24580 The audio sample rate.
24583 The PTS of the first frame.
24586 the time in seconds of the first frame
24589 State whether the current frame is interlaced.
24592 the time in seconds of the current frame
24595 original position in the file of the frame, or undefined if undefined
24596 for the current frame
24599 The previous input PTS.
24602 previous input time in seconds
24605 The previous output PTS.
24608 previous output time in seconds
24611 The wallclock (RTC) time in microseconds. This is deprecated, use time(0)
24615 The wallclock (RTC) time at the start of the movie in microseconds.
24618 The timebase of the input timestamps.
24622 @subsection Examples
24626 Start counting PTS from zero
24628 setpts=PTS-STARTPTS
24632 Apply fast motion effect:
24638 Apply slow motion effect:
24644 Set fixed rate of 25 frames per second:
24650 Set fixed rate 25 fps with some jitter:
24652 setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
24656 Apply an offset of 10 seconds to the input PTS:
24662 Generate timestamps from a "live source" and rebase onto the current timebase:
24664 setpts='(RTCTIME - RTCSTART) / (TB * 1000000)'
24668 Generate timestamps by counting samples:
24677 Force color range for the output video frame.
24679 The @code{setrange} filter marks the color range property for the
24680 output frames. It does not change the input frame, but only sets the
24681 corresponding property, which affects how the frame is treated by
24684 The filter accepts the following options:
24689 Available values are:
24693 Keep the same color range property.
24695 @item unspecified, unknown
24696 Set the color range as unspecified.
24698 @item limited, tv, mpeg
24699 Set the color range as limited.
24701 @item full, pc, jpeg
24702 Set the color range as full.
24706 @section settb, asettb
24708 Set the timebase to use for the output frames timestamps.
24709 It is mainly useful for testing timebase configuration.
24711 It accepts the following parameters:
24716 The expression which is evaluated into the output timebase.
24720 The value for @option{tb} is an arithmetic expression representing a
24721 rational. The expression can contain the constants "AVTB" (the default
24722 timebase), "intb" (the input timebase) and "sr" (the sample rate,
24723 audio only). Default value is "intb".
24725 @subsection Examples
24729 Set the timebase to 1/25:
24735 Set the timebase to 1/10:
24741 Set the timebase to 1001/1000:
24747 Set the timebase to 2*intb:
24753 Set the default timebase value:
24760 Convert input audio to a video output representing frequency spectrum
24761 logarithmically using Brown-Puckette constant Q transform algorithm with
24762 direct frequency domain coefficient calculation (but the transform itself
24763 is not really constant Q, instead the Q factor is actually variable/clamped),
24764 with musical tone scale, from E0 to D#10.
24766 The filter accepts the following options:
24770 Specify the video size for the output. It must be even. For the syntax of this option,
24771 check the @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
24772 Default value is @code{1920x1080}.
24775 Set the output frame rate. Default value is @code{25}.
24778 Set the bargraph height. It must be even. Default value is @code{-1} which
24779 computes the bargraph height automatically.
24782 Set the axis height. It must be even. Default value is @code{-1} which computes
24783 the axis height automatically.
24786 Set the sonogram height. It must be even. Default value is @code{-1} which
24787 computes the sonogram height automatically.
24790 Set the fullhd resolution. This option is deprecated, use @var{size}, @var{s}
24791 instead. Default value is @code{1}.
24793 @item sono_v, volume
24794 Specify the sonogram volume expression. It can contain variables:
24797 the @var{bar_v} evaluated expression
24798 @item frequency, freq, f
24799 the frequency where it is evaluated
24800 @item timeclamp, tc
24801 the value of @var{timeclamp} option
24805 @item a_weighting(f)
24806 A-weighting of equal loudness
24807 @item b_weighting(f)
24808 B-weighting of equal loudness
24809 @item c_weighting(f)
24810 C-weighting of equal loudness.
24812 Default value is @code{16}.
24814 @item bar_v, volume2
24815 Specify the bargraph volume expression. It can contain variables:
24818 the @var{sono_v} evaluated expression
24819 @item frequency, freq, f
24820 the frequency where it is evaluated
24821 @item timeclamp, tc
24822 the value of @var{timeclamp} option
24826 @item a_weighting(f)
24827 A-weighting of equal loudness
24828 @item b_weighting(f)
24829 B-weighting of equal loudness
24830 @item c_weighting(f)
24831 C-weighting of equal loudness.
24833 Default value is @code{sono_v}.
24835 @item sono_g, gamma
24836 Specify the sonogram gamma. Lower gamma makes the spectrum more contrast,
24837 higher gamma makes the spectrum having more range. Default value is @code{3}.
24838 Acceptable range is @code{[1, 7]}.
24840 @item bar_g, gamma2
24841 Specify the bargraph gamma. Default value is @code{1}. Acceptable range is
24845 Specify the bargraph transparency level. Lower value makes the bargraph sharper.
24846 Default value is @code{1}. Acceptable range is @code{[0, 1]}.
24848 @item timeclamp, tc
24849 Specify the transform timeclamp. At low frequency, there is trade-off between
24850 accuracy in time domain and frequency domain. If timeclamp is lower,
24851 event in time domain is represented more accurately (such as fast bass drum),
24852 otherwise event in frequency domain is represented more accurately
24853 (such as bass guitar). Acceptable range is @code{[0.002, 1]}. Default value is @code{0.17}.
24856 Set attack time in seconds. The default is @code{0} (disabled). Otherwise, it
24857 limits future samples by applying asymmetric windowing in time domain, useful
24858 when low latency is required. Accepted range is @code{[0, 1]}.
24861 Specify the transform base frequency. Default value is @code{20.01523126408007475},
24862 which is frequency 50 cents below E0. Acceptable range is @code{[10, 100000]}.
24865 Specify the transform end frequency. Default value is @code{20495.59681441799654},
24866 which is frequency 50 cents above D#10. Acceptable range is @code{[10, 100000]}.
24869 This option is deprecated and ignored.
24872 Specify the transform length in time domain. Use this option to control accuracy
24873 trade-off between time domain and frequency domain at every frequency sample.
24874 It can contain variables:
24876 @item frequency, freq, f
24877 the frequency where it is evaluated
24878 @item timeclamp, tc
24879 the value of @var{timeclamp} option.
24881 Default value is @code{384*tc/(384+tc*f)}.
24884 Specify the transform count for every video frame. Default value is @code{6}.
24885 Acceptable range is @code{[1, 30]}.
24888 Specify the transform count for every single pixel. Default value is @code{0},
24889 which makes it computed automatically. Acceptable range is @code{[0, 10]}.
24892 Specify font file for use with freetype to draw the axis. If not specified,
24893 use embedded font. Note that drawing with font file or embedded font is not
24894 implemented with custom @var{basefreq} and @var{endfreq}, use @var{axisfile}
24898 Specify fontconfig pattern. This has lower priority than @var{fontfile}. The
24899 @code{:} in the pattern may be replaced by @code{|} to avoid unnecessary
24903 Specify font color expression. This is arithmetic expression that should return
24904 integer value 0xRRGGBB. It can contain variables:
24906 @item frequency, freq, f
24907 the frequency where it is evaluated
24908 @item timeclamp, tc
24909 the value of @var{timeclamp} option
24914 midi number of frequency f, some midi numbers: E0(16), C1(24), C2(36), A4(69)
24915 @item r(x), g(x), b(x)
24916 red, green, and blue value of intensity x.
24918 Default value is @code{st(0, (midi(f)-59.5)/12);
24919 st(1, if(between(ld(0),0,1), 0.5-0.5*cos(2*PI*ld(0)), 0));
24920 r(1-ld(1)) + b(ld(1))}.
24923 Specify image file to draw the axis. This option override @var{fontfile} and
24924 @var{fontcolor} option.
24927 Enable/disable drawing text to the axis. If it is set to @code{0}, drawing to
24928 the axis is disabled, ignoring @var{fontfile} and @var{axisfile} option.
24929 Default value is @code{1}.
24932 Set colorspace. The accepted values are:
24935 Unspecified (default)
24944 BT.470BG or BT.601-6 625
24947 SMPTE-170M or BT.601-6 525
24953 BT.2020 with non-constant luminance
24958 Set spectrogram color scheme. This is list of floating point values with format
24959 @code{left_r|left_g|left_b|right_r|right_g|right_b}.
24960 The default is @code{1|0.5|0|0|0.5|1}.
24964 @subsection Examples
24968 Playing audio while showing the spectrum:
24970 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt [out0]'
24974 Same as above, but with frame rate 30 fps:
24976 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fps=30:count=5 [out0]'
24980 Playing at 1280x720:
24982 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=s=1280x720:count=4 [out0]'
24986 Disable sonogram display:
24992 A1 and its harmonics: A1, A2, (near)E3, A3:
24994 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),
24995 asplit[a][out1]; [a] showcqt [out0]'
24999 Same as above, but with more accuracy in frequency domain:
25001 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),
25002 asplit[a][out1]; [a] showcqt=timeclamp=0.5 [out0]'
25008 bar_v=10:sono_v=bar_v*a_weighting(f)
25012 Custom gamma, now spectrum is linear to the amplitude.
25018 Custom tlength equation:
25020 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)))'
25024 Custom fontcolor and fontfile, C-note is colored green, others are colored blue:
25026 fontcolor='if(mod(floor(midi(f)+0.5),12), 0x0000FF, g(1))':fontfile=myfont.ttf
25030 Custom font using fontconfig:
25032 font='Courier New,Monospace,mono|bold'
25036 Custom frequency range with custom axis using image file:
25038 axisfile=myaxis.png:basefreq=40:endfreq=10000
25044 Convert input audio to video output representing the audio power spectrum.
25045 Audio amplitude is on Y-axis while frequency is on X-axis.
25047 The filter accepts the following options:
25051 Specify size of video. For the syntax of this option, check the
25052 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
25053 Default is @code{1024x512}.
25057 This set how each frequency bin will be represented.
25059 It accepts the following values:
25065 Default is @code{bar}.
25068 Set amplitude scale.
25070 It accepts the following values:
25084 Default is @code{log}.
25087 Set frequency scale.
25089 It accepts the following values:
25098 Reverse logarithmic scale.
25100 Default is @code{lin}.
25103 Set window size. Allowed range is from 16 to 65536.
25105 Default is @code{2048}
25108 Set windowing function.
25110 It accepts the following values:
25133 Default is @code{hanning}.
25136 Set window overlap. In range @code{[0, 1]}. Default is @code{1},
25137 which means optimal overlap for selected window function will be picked.
25140 Set time averaging. Setting this to 0 will display current maximal peaks.
25141 Default is @code{1}, which means time averaging is disabled.
25144 Specify list of colors separated by space or by '|' which will be used to
25145 draw channel frequencies. Unrecognized or missing colors will be replaced
25149 Set channel display mode.
25151 It accepts the following values:
25156 Default is @code{combined}.
25159 Set minimum amplitude used in @code{log} amplitude scaler.
25163 @section showspatial
25165 Convert stereo input audio to a video output, representing the spatial relationship
25166 between two channels.
25168 The filter accepts the following options:
25172 Specify the video size for the output. For the syntax of this option, check the
25173 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
25174 Default value is @code{512x512}.
25177 Set window size. Allowed range is from @var{1024} to @var{65536}. Default size is @var{4096}.
25180 Set window function.
25182 It accepts the following values:
25207 Default value is @code{hann}.
25210 Set ratio of overlap window. Default value is @code{0.5}.
25211 When value is @code{1} overlap is set to recommended size for specific
25212 window function currently used.
25215 @anchor{showspectrum}
25216 @section showspectrum
25218 Convert input audio to a video output, representing the audio frequency
25221 The filter accepts the following options:
25225 Specify the video size for the output. For the syntax of this option, check the
25226 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
25227 Default value is @code{640x512}.
25230 Specify how the spectrum should slide along the window.
25232 It accepts the following values:
25235 the samples start again on the left when they reach the right
25237 the samples scroll from right to left
25239 frames are only produced when the samples reach the right
25241 the samples scroll from left to right
25244 Default value is @code{replace}.
25247 Specify display mode.
25249 It accepts the following values:
25252 all channels are displayed in the same row
25254 all channels are displayed in separate rows
25257 Default value is @samp{combined}.
25260 Specify display color mode.
25262 It accepts the following values:
25265 each channel is displayed in a separate color
25267 each channel is displayed using the same color scheme
25269 each channel is displayed using the rainbow color scheme
25271 each channel is displayed using the moreland color scheme
25273 each channel is displayed using the nebulae color scheme
25275 each channel is displayed using the fire color scheme
25277 each channel is displayed using the fiery color scheme
25279 each channel is displayed using the fruit color scheme
25281 each channel is displayed using the cool color scheme
25283 each channel is displayed using the magma color scheme
25285 each channel is displayed using the green color scheme
25287 each channel is displayed using the viridis color scheme
25289 each channel is displayed using the plasma color scheme
25291 each channel is displayed using the cividis color scheme
25293 each channel is displayed using the terrain color scheme
25296 Default value is @samp{channel}.
25299 Specify scale used for calculating intensity color values.
25301 It accepts the following values:
25306 square root, default
25317 Default value is @samp{sqrt}.
25320 Specify frequency scale.
25322 It accepts the following values:
25330 Default value is @samp{lin}.
25333 Set saturation modifier for displayed colors. Negative values provide
25334 alternative color scheme. @code{0} is no saturation at all.
25335 Saturation must be in [-10.0, 10.0] range.
25336 Default value is @code{1}.
25339 Set window function.
25341 It accepts the following values:
25366 Default value is @code{hann}.
25369 Set orientation of time vs frequency axis. Can be @code{vertical} or
25370 @code{horizontal}. Default is @code{vertical}.
25373 Set ratio of overlap window. Default value is @code{0}.
25374 When value is @code{1} overlap is set to recommended size for specific
25375 window function currently used.
25378 Set scale gain for calculating intensity color values.
25379 Default value is @code{1}.
25382 Set which data to display. Can be @code{magnitude}, default or @code{phase}.
25385 Set color rotation, must be in [-1.0, 1.0] range.
25386 Default value is @code{0}.
25389 Set start frequency from which to display spectrogram. Default is @code{0}.
25392 Set stop frequency to which to display spectrogram. Default is @code{0}.
25395 Set upper frame rate limit. Default is @code{auto}, unlimited.
25398 Draw time and frequency axes and legends. Default is disabled.
25401 The usage is very similar to the showwaves filter; see the examples in that
25404 @subsection Examples
25408 Large window with logarithmic color scaling:
25410 showspectrum=s=1280x480:scale=log
25414 Complete example for a colored and sliding spectrum per channel using @command{ffplay}:
25416 ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
25417 [a] showspectrum=mode=separate:color=intensity:slide=1:scale=cbrt [out0]'
25421 @section showspectrumpic
25423 Convert input audio to a single video frame, representing the audio frequency
25426 The filter accepts the following options:
25430 Specify the video size for the output. For the syntax of this option, check the
25431 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
25432 Default value is @code{4096x2048}.
25435 Specify display mode.
25437 It accepts the following values:
25440 all channels are displayed in the same row
25442 all channels are displayed in separate rows
25444 Default value is @samp{combined}.
25447 Specify display color mode.
25449 It accepts the following values:
25452 each channel is displayed in a separate color
25454 each channel is displayed using the same color scheme
25456 each channel is displayed using the rainbow color scheme
25458 each channel is displayed using the moreland color scheme
25460 each channel is displayed using the nebulae color scheme
25462 each channel is displayed using the fire color scheme
25464 each channel is displayed using the fiery color scheme
25466 each channel is displayed using the fruit color scheme
25468 each channel is displayed using the cool color scheme
25470 each channel is displayed using the magma color scheme
25472 each channel is displayed using the green color scheme
25474 each channel is displayed using the viridis color scheme
25476 each channel is displayed using the plasma color scheme
25478 each channel is displayed using the cividis color scheme
25480 each channel is displayed using the terrain color scheme
25482 Default value is @samp{intensity}.
25485 Specify scale used for calculating intensity color values.
25487 It accepts the following values:
25492 square root, default
25502 Default value is @samp{log}.
25505 Specify frequency scale.
25507 It accepts the following values:
25515 Default value is @samp{lin}.
25518 Set saturation modifier for displayed colors. Negative values provide
25519 alternative color scheme. @code{0} is no saturation at all.
25520 Saturation must be in [-10.0, 10.0] range.
25521 Default value is @code{1}.
25524 Set window function.
25526 It accepts the following values:
25550 Default value is @code{hann}.
25553 Set orientation of time vs frequency axis. Can be @code{vertical} or
25554 @code{horizontal}. Default is @code{vertical}.
25557 Set scale gain for calculating intensity color values.
25558 Default value is @code{1}.
25561 Draw time and frequency axes and legends. Default is enabled.
25564 Set color rotation, must be in [-1.0, 1.0] range.
25565 Default value is @code{0}.
25568 Set start frequency from which to display spectrogram. Default is @code{0}.
25571 Set stop frequency to which to display spectrogram. Default is @code{0}.
25574 @subsection Examples
25578 Extract an audio spectrogram of a whole audio track
25579 in a 1024x1024 picture using @command{ffmpeg}:
25581 ffmpeg -i audio.flac -lavfi showspectrumpic=s=1024x1024 spectrogram.png
25585 @section showvolume
25587 Convert input audio volume to a video output.
25589 The filter accepts the following options:
25596 Set border width, allowed range is [0, 5]. Default is 1.
25599 Set channel width, allowed range is [80, 8192]. Default is 400.
25602 Set channel height, allowed range is [1, 900]. Default is 20.
25605 Set fade, allowed range is [0, 1]. Default is 0.95.
25608 Set volume color expression.
25610 The expression can use the following variables:
25614 Current max volume of channel in dB.
25620 Current channel number, starting from 0.
25624 If set, displays channel names. Default is enabled.
25627 If set, displays volume values. Default is enabled.
25630 Set orientation, can be horizontal: @code{h} or vertical: @code{v},
25631 default is @code{h}.
25634 Set step size, allowed range is [0, 5]. Default is 0, which means
25638 Set background opacity, allowed range is [0, 1]. Default is 0.
25641 Set metering mode, can be peak: @code{p} or rms: @code{r},
25642 default is @code{p}.
25645 Set display scale, can be linear: @code{lin} or log: @code{log},
25646 default is @code{lin}.
25650 If set to > 0., display a line for the max level
25651 in the previous seconds.
25652 default is disabled: @code{0.}
25655 The color of the max line. Use when @code{dm} option is set to > 0.
25656 default is: @code{orange}
25661 Convert input audio to a video output, representing the samples waves.
25663 The filter accepts the following options:
25667 Specify the video size for the output. For the syntax of this option, check the
25668 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
25669 Default value is @code{600x240}.
25674 Available values are:
25677 Draw a point for each sample.
25680 Draw a vertical line for each sample.
25683 Draw a point for each sample and a line between them.
25686 Draw a centered vertical line for each sample.
25689 Default value is @code{point}.
25692 Set the number of samples which are printed on the same column. A
25693 larger value will decrease the frame rate. Must be a positive
25694 integer. This option can be set only if the value for @var{rate}
25695 is not explicitly specified.
25698 Set the (approximate) output frame rate. This is done by setting the
25699 option @var{n}. Default value is "25".
25701 @item split_channels
25702 Set if channels should be drawn separately or overlap. Default value is 0.
25705 Set colors separated by '|' which are going to be used for drawing of each channel.
25708 Set amplitude scale.
25710 Available values are:
25728 Set the draw mode. This is mostly useful to set for high @var{n}.
25730 Available values are:
25733 Scale pixel values for each drawn sample.
25736 Draw every sample directly.
25739 Default value is @code{scale}.
25742 @subsection Examples
25746 Output the input file audio and the corresponding video representation
25749 amovie=a.mp3,asplit[out0],showwaves[out1]
25753 Create a synthetic signal and show it with showwaves, forcing a
25754 frame rate of 30 frames per second:
25756 aevalsrc=sin(1*2*PI*t)*sin(880*2*PI*t):cos(2*PI*200*t),asplit[out0],showwaves=r=30[out1]
25760 @section showwavespic
25762 Convert input audio to a single video frame, representing the samples waves.
25764 The filter accepts the following options:
25768 Specify the video size for the output. For the syntax of this option, check the
25769 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
25770 Default value is @code{600x240}.
25772 @item split_channels
25773 Set if channels should be drawn separately or overlap. Default value is 0.
25776 Set colors separated by '|' which are going to be used for drawing of each channel.
25779 Set amplitude scale.
25781 Available values are:
25801 Available values are:
25804 Scale pixel values for each drawn sample.
25807 Draw every sample directly.
25810 Default value is @code{scale}.
25813 Set the filter mode.
25815 Available values are:
25818 Use average samples values for each drawn sample.
25821 Use peak samples values for each drawn sample.
25824 Default value is @code{average}.
25827 @subsection Examples
25831 Extract a channel split representation of the wave form of a whole audio track
25832 in a 1024x800 picture using @command{ffmpeg}:
25834 ffmpeg -i audio.flac -lavfi showwavespic=split_channels=1:s=1024x800 waveform.png
25838 @section sidedata, asidedata
25840 Delete frame side data, or select frames based on it.
25842 This filter accepts the following options:
25846 Set mode of operation of the filter.
25848 Can be one of the following:
25852 Select every frame with side data of @code{type}.
25855 Delete side data of @code{type}. If @code{type} is not set, delete all side
25861 Set side data type used with all modes. Must be set for @code{select} mode. For
25862 the list of frame side data types, refer to the @code{AVFrameSideDataType} enum
25863 in @file{libavutil/frame.h}. For example, to choose
25864 @code{AV_FRAME_DATA_PANSCAN} side data, you must specify @code{PANSCAN}.
25868 @section spectrumsynth
25870 Synthesize audio from 2 input video spectrums, first input stream represents
25871 magnitude across time and second represents phase across time.
25872 The filter will transform from frequency domain as displayed in videos back
25873 to time domain as presented in audio output.
25875 This filter is primarily created for reversing processed @ref{showspectrum}
25876 filter outputs, but can synthesize sound from other spectrograms too.
25877 But in such case results are going to be poor if the phase data is not
25878 available, because in such cases phase data need to be recreated, usually
25879 it's just recreated from random noise.
25880 For best results use gray only output (@code{channel} color mode in
25881 @ref{showspectrum} filter) and @code{log} scale for magnitude video and
25882 @code{lin} scale for phase video. To produce phase, for 2nd video, use
25883 @code{data} option. Inputs videos should generally use @code{fullframe}
25884 slide mode as that saves resources needed for decoding video.
25886 The filter accepts the following options:
25890 Specify sample rate of output audio, the sample rate of audio from which
25891 spectrum was generated may differ.
25894 Set number of channels represented in input video spectrums.
25897 Set scale which was used when generating magnitude input spectrum.
25898 Can be @code{lin} or @code{log}. Default is @code{log}.
25901 Set slide which was used when generating inputs spectrums.
25902 Can be @code{replace}, @code{scroll}, @code{fullframe} or @code{rscroll}.
25903 Default is @code{fullframe}.
25906 Set window function used for resynthesis.
25909 Set window overlap. In range @code{[0, 1]}. Default is @code{1},
25910 which means optimal overlap for selected window function will be picked.
25913 Set orientation of input videos. Can be @code{vertical} or @code{horizontal}.
25914 Default is @code{vertical}.
25917 @subsection Examples
25921 First create magnitude and phase videos from audio, assuming audio is stereo with 44100 sample rate,
25922 then resynthesize videos back to audio with spectrumsynth:
25924 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
25925 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
25926 ffmpeg -i magnitude.nut -i phase.nut -lavfi spectrumsynth=channels=2:sample_rate=44100:win_func=hann:overlap=0.875:slide=fullframe output.flac
25930 @section split, asplit
25932 Split input into several identical outputs.
25934 @code{asplit} works with audio input, @code{split} with video.
25936 The filter accepts a single parameter which specifies the number of outputs. If
25937 unspecified, it defaults to 2.
25939 @subsection Examples
25943 Create two separate outputs from the same input:
25945 [in] split [out0][out1]
25949 To create 3 or more outputs, you need to specify the number of
25952 [in] asplit=3 [out0][out1][out2]
25956 Create two separate outputs from the same input, one cropped and
25959 [in] split [splitout1][splitout2];
25960 [splitout1] crop=100:100:0:0 [cropout];
25961 [splitout2] pad=200:200:100:100 [padout];
25965 Create 5 copies of the input audio with @command{ffmpeg}:
25967 ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT
25973 Receive commands sent through a libzmq client, and forward them to
25974 filters in the filtergraph.
25976 @code{zmq} and @code{azmq} work as a pass-through filters. @code{zmq}
25977 must be inserted between two video filters, @code{azmq} between two
25978 audio filters. Both are capable to send messages to any filter type.
25980 To enable these filters you need to install the libzmq library and
25981 headers and configure FFmpeg with @code{--enable-libzmq}.
25983 For more information about libzmq see:
25984 @url{http://www.zeromq.org/}
25986 The @code{zmq} and @code{azmq} filters work as a libzmq server, which
25987 receives messages sent through a network interface defined by the
25988 @option{bind_address} (or the abbreviation "@option{b}") option.
25989 Default value of this option is @file{tcp://localhost:5555}. You may
25990 want to alter this value to your needs, but do not forget to escape any
25991 ':' signs (see @ref{filtergraph escaping}).
25993 The received message must be in the form:
25995 @var{TARGET} @var{COMMAND} [@var{ARG}]
25998 @var{TARGET} specifies the target of the command, usually the name of
25999 the filter class or a specific filter instance name. The default
26000 filter instance name uses the pattern @samp{Parsed_<filter_name>_<index>},
26001 but you can override this by using the @samp{filter_name@@id} syntax
26002 (see @ref{Filtergraph syntax}).
26004 @var{COMMAND} specifies the name of the command for the target filter.
26006 @var{ARG} is optional and specifies the optional argument list for the
26007 given @var{COMMAND}.
26009 Upon reception, the message is processed and the corresponding command
26010 is injected into the filtergraph. Depending on the result, the filter
26011 will send a reply to the client, adopting the format:
26013 @var{ERROR_CODE} @var{ERROR_REASON}
26017 @var{MESSAGE} is optional.
26019 @subsection Examples
26021 Look at @file{tools/zmqsend} for an example of a zmq client which can
26022 be used to send commands processed by these filters.
26024 Consider the following filtergraph generated by @command{ffplay}.
26025 In this example the last overlay filter has an instance name. All other
26026 filters will have default instance names.
26029 ffplay -dumpgraph 1 -f lavfi "
26030 color=s=100x100:c=red [l];
26031 color=s=100x100:c=blue [r];
26032 nullsrc=s=200x100, zmq [bg];
26033 [bg][l] overlay [bg+l];
26034 [bg+l][r] overlay@@my=x=100 "
26037 To change the color of the left side of the video, the following
26038 command can be used:
26040 echo Parsed_color_0 c yellow | tools/zmqsend
26043 To change the right side:
26045 echo Parsed_color_1 c pink | tools/zmqsend
26048 To change the position of the right side:
26050 echo overlay@@my x 150 | tools/zmqsend
26054 @c man end MULTIMEDIA FILTERS
26056 @chapter Multimedia Sources
26057 @c man begin MULTIMEDIA SOURCES
26059 Below is a description of the currently available multimedia sources.
26063 This is the same as @ref{movie} source, except it selects an audio
26069 Read audio and/or video stream(s) from a movie container.
26071 It accepts the following parameters:
26075 The name of the resource to read (not necessarily a file; it can also be a
26076 device or a stream accessed through some protocol).
26078 @item format_name, f
26079 Specifies the format assumed for the movie to read, and can be either
26080 the name of a container or an input device. If not specified, the
26081 format is guessed from @var{movie_name} or by probing.
26083 @item seek_point, sp
26084 Specifies the seek point in seconds. The frames will be output
26085 starting from this seek point. The parameter is evaluated with
26086 @code{av_strtod}, so the numerical value may be suffixed by an IS
26087 postfix. The default value is "0".
26090 Specifies the streams to read. Several streams can be specified,
26091 separated by "+". The source will then have as many outputs, in the
26092 same order. The syntax is explained in the @ref{Stream specifiers,,"Stream specifiers"
26093 section in the ffmpeg manual,ffmpeg}. Two special names, "dv" and "da" specify
26094 respectively the default (best suited) video and audio stream. Default
26095 is "dv", or "da" if the filter is called as "amovie".
26097 @item stream_index, si
26098 Specifies the index of the video stream to read. If the value is -1,
26099 the most suitable video stream will be automatically selected. The default
26100 value is "-1". Deprecated. If the filter is called "amovie", it will select
26101 audio instead of video.
26104 Specifies how many times to read the stream in sequence.
26105 If the value is 0, the stream will be looped infinitely.
26106 Default value is "1".
26108 Note that when the movie is looped the source timestamps are not
26109 changed, so it will generate non monotonically increasing timestamps.
26111 @item discontinuity
26112 Specifies the time difference between frames above which the point is
26113 considered a timestamp discontinuity which is removed by adjusting the later
26117 It allows overlaying a second video on top of the main input of
26118 a filtergraph, as shown in this graph:
26120 input -----------> deltapts0 --> overlay --> output
26123 movie --> scale--> deltapts1 -------+
26125 @subsection Examples
26129 Skip 3.2 seconds from the start of the AVI file in.avi, and overlay it
26130 on top of the input labelled "in":
26132 movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [over];
26133 [in] setpts=PTS-STARTPTS [main];
26134 [main][over] overlay=16:16 [out]
26138 Read from a video4linux2 device, and overlay it on top of the input
26141 movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [over];
26142 [in] setpts=PTS-STARTPTS [main];
26143 [main][over] overlay=16:16 [out]
26147 Read the first video stream and the audio stream with id 0x81 from
26148 dvd.vob; the video is connected to the pad named "video" and the audio is
26149 connected to the pad named "audio":
26151 movie=dvd.vob:s=v:0+#0x81 [video] [audio]
26155 @subsection Commands
26157 Both movie and amovie support the following commands:
26160 Perform seek using "av_seek_frame".
26161 The syntax is: seek @var{stream_index}|@var{timestamp}|@var{flags}
26164 @var{stream_index}: If stream_index is -1, a default
26165 stream is selected, and @var{timestamp} is automatically converted
26166 from AV_TIME_BASE units to the stream specific time_base.
26168 @var{timestamp}: Timestamp in AVStream.time_base units
26169 or, if no stream is specified, in AV_TIME_BASE units.
26171 @var{flags}: Flags which select direction and seeking mode.
26175 Get movie duration in AV_TIME_BASE units.
26179 @c man end MULTIMEDIA SOURCES