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. Availabe values are:
541 Default is @var{4th}.
546 Reduce audio bit resolution.
548 This filter is bit crusher with enhanced functionality. A bit crusher
549 is used to audibly reduce number of bits an audio signal is sampled
550 with. This doesn't change the bit depth at all, it just produces the
551 effect. Material reduced in bit depth sounds more harsh and "digital".
552 This filter is able to even round to continuous values instead of discrete
554 Additionally it has a D/C offset which results in different crushing of
555 the lower and the upper half of the signal.
556 An Anti-Aliasing setting is able to produce "softer" crushing sounds.
558 Another feature of this filter is the logarithmic mode.
559 This setting switches from linear distances between bits to logarithmic ones.
560 The result is a much more "natural" sounding crusher which doesn't gate low
561 signals for example. The human ear has a logarithmic perception,
562 so this kind of crushing is much more pleasant.
563 Logarithmic crushing is also able to get anti-aliased.
565 The filter accepts the following options:
581 Can be linear: @code{lin} or logarithmic: @code{log}.
590 Set sample reduction.
593 Enable LFO. By default disabled.
604 Delay audio filtering until a given wallclock timestamp. See the @ref{cue}
608 Remove impulsive noise from input audio.
610 Samples detected as impulsive noise are replaced by interpolated samples using
611 autoregressive modelling.
615 Set window size, in milliseconds. Allowed range is from @code{10} to
616 @code{100}. Default value is @code{55} milliseconds.
617 This sets size of window which will be processed at once.
620 Set window overlap, in percentage of window size. Allowed range is from
621 @code{50} to @code{95}. Default value is @code{75} percent.
622 Setting this to a very high value increases impulsive noise removal but makes
623 whole process much slower.
626 Set autoregression order, in percentage of window size. Allowed range is from
627 @code{0} to @code{25}. Default value is @code{2} percent. This option also
628 controls quality of interpolated samples using neighbour good samples.
631 Set threshold value. Allowed range is from @code{1} to @code{100}.
632 Default value is @code{2}.
633 This controls the strength of impulsive noise which is going to be removed.
634 The lower value, the more samples will be detected as impulsive noise.
637 Set burst fusion, in percentage of window size. Allowed range is @code{0} to
638 @code{10}. Default value is @code{2}.
639 If any two samples detected as noise are spaced less than this value then any
640 sample between those two samples will be also detected as noise.
645 It accepts the following values:
648 Select overlap-add method. Even not interpolated samples are slightly
649 changed with this method.
652 Select overlap-save method. Not interpolated samples remain unchanged.
655 Default value is @code{a}.
659 Remove clipped samples from input audio.
661 Samples detected as clipped are replaced by interpolated samples using
662 autoregressive modelling.
666 Set window size, in milliseconds. Allowed range is from @code{10} to @code{100}.
667 Default value is @code{55} milliseconds.
668 This sets size of window which will be processed at once.
671 Set window overlap, in percentage of window size. Allowed range is from @code{50}
672 to @code{95}. Default value is @code{75} percent.
675 Set autoregression order, in percentage of window size. Allowed range is from
676 @code{0} to @code{25}. Default value is @code{8} percent. This option also controls
677 quality of interpolated samples using neighbour good samples.
680 Set threshold value. Allowed range is from @code{1} to @code{100}.
681 Default value is @code{10}. Higher values make clip detection less aggressive.
684 Set size of histogram used to detect clips. Allowed range is from @code{100} to @code{9999}.
685 Default value is @code{1000}. Higher values make clip detection less aggressive.
690 It accepts the following values:
693 Select overlap-add method. Even not interpolated samples are slightly changed
697 Select overlap-save method. Not interpolated samples remain unchanged.
700 Default value is @code{a}.
705 Delay one or more audio channels.
707 Samples in delayed channel are filled with silence.
709 The filter accepts the following option:
713 Set list of delays in milliseconds for each channel separated by '|'.
714 Unused delays will be silently ignored. If number of given delays is
715 smaller than number of channels all remaining channels will not be delayed.
716 If you want to delay exact number of samples, append 'S' to number.
717 If you want instead to delay in seconds, append 's' to number.
720 Use last set delay for all remaining channels. By default is disabled.
721 This option if enabled changes how option @code{delays} is interpreted.
728 Delay first channel by 1.5 seconds, the third channel by 0.5 seconds and leave
729 the second channel (and any other channels that may be present) unchanged.
735 Delay second channel by 500 samples, the third channel by 700 samples and leave
736 the first channel (and any other channels that may be present) unchanged.
742 Delay all channels by same number of samples:
744 adelay=delays=64S:all=1
749 Remedy denormals in audio by adding extremely low-level noise.
751 A description of the accepted parameters follows.
755 Set level of added noise in dB. Default is @code{-351}.
756 Allowed range is from -451 to -90.
759 Set type of added noise.
772 Default is @code{dc}.
775 @section aderivative, aintegral
777 Compute derivative/integral of audio stream.
779 Applying both filters one after another produces original audio.
783 Apply echoing to the input audio.
785 Echoes are reflected sound and can occur naturally amongst mountains
786 (and sometimes large buildings) when talking or shouting; digital echo
787 effects emulate this behaviour and are often used to help fill out the
788 sound of a single instrument or vocal. The time difference between the
789 original signal and the reflection is the @code{delay}, and the
790 loudness of the reflected signal is the @code{decay}.
791 Multiple echoes can have different delays and decays.
793 A description of the accepted parameters follows.
797 Set input gain of reflected signal. Default is @code{0.6}.
800 Set output gain of reflected signal. Default is @code{0.3}.
803 Set list of time intervals in milliseconds between original signal and reflections
804 separated by '|'. Allowed range for each @code{delay} is @code{(0 - 90000.0]}.
805 Default is @code{1000}.
808 Set list of loudness of reflected signals separated by '|'.
809 Allowed range for each @code{decay} is @code{(0 - 1.0]}.
810 Default is @code{0.5}.
817 Make it sound as if there are twice as many instruments as are actually playing:
819 aecho=0.8:0.88:60:0.4
823 If delay is very short, then it sounds like a (metallic) robot playing music:
829 A longer delay will sound like an open air concert in the mountains:
831 aecho=0.8:0.9:1000:0.3
835 Same as above but with one more mountain:
837 aecho=0.8:0.9:1000|1800:0.3|0.25
842 Audio emphasis filter creates or restores material directly taken from LPs or
843 emphased CDs with different filter curves. E.g. to store music on vinyl the
844 signal has to be altered by a filter first to even out the disadvantages of
845 this recording medium.
846 Once the material is played back the inverse filter has to be applied to
847 restore the distortion of the frequency response.
849 The filter accepts the following options:
859 Set filter mode. For restoring material use @code{reproduction} mode, otherwise
860 use @code{production} mode. Default is @code{reproduction} mode.
863 Set filter type. Selects medium. Can be one of the following:
875 select Compact Disc (CD).
881 select 50µs (FM-KF).
883 select 75µs (FM-KF).
889 Modify an audio signal according to the specified expressions.
891 This filter accepts one or more expressions (one for each channel),
892 which are evaluated and used to modify a corresponding audio signal.
894 It accepts the following parameters:
898 Set the '|'-separated expressions list for each separate channel. If
899 the number of input channels is greater than the number of
900 expressions, the last specified expression is used for the remaining
903 @item channel_layout, c
904 Set output channel layout. If not specified, the channel layout is
905 specified by the number of expressions. If set to @samp{same}, it will
906 use by default the same input channel layout.
909 Each expression in @var{exprs} can contain the following constants and functions:
913 channel number of the current expression
916 number of the evaluated sample, starting from 0
922 time of the evaluated sample expressed in seconds
925 @item nb_out_channels
926 input and output number of channels
929 the value of input channel with number @var{CH}
932 Note: this filter is slow. For faster processing you should use a
941 aeval=val(ch)/2:c=same
945 Invert phase of the second channel:
954 Apply fade-in/out effect to input audio.
956 A description of the accepted parameters follows.
960 Specify the effect type, can be either @code{in} for fade-in, or
961 @code{out} for a fade-out effect. Default is @code{in}.
963 @item start_sample, ss
964 Specify the number of the start sample for starting to apply the fade
965 effect. Default is 0.
968 Specify the number of samples for which the fade effect has to last. At
969 the end of the fade-in effect the output audio will have the same
970 volume as the input audio, at the end of the fade-out transition
971 the output audio will be silence. Default is 44100.
974 Specify the start time of the fade effect. Default is 0.
975 The value must be specified as a time duration; see
976 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
977 for the accepted syntax.
978 If set this option is used instead of @var{start_sample}.
981 Specify the duration of the fade effect. See
982 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
983 for the accepted syntax.
984 At the end of the fade-in effect the output audio will have the same
985 volume as the input audio, at the end of the fade-out transition
986 the output audio will be silence.
987 By default the duration is determined by @var{nb_samples}.
988 If set this option is used instead of @var{nb_samples}.
991 Set curve for fade transition.
993 It accepts the following values:
996 select triangular, linear slope (default)
998 select quarter of sine wave
1000 select half of sine wave
1002 select exponential sine wave
1006 select inverted parabola
1020 select inverted quarter of sine wave
1022 select inverted half of sine wave
1024 select double-exponential seat
1026 select double-exponential sigmoid
1028 select logistic sigmoid
1030 select sine cardinal function
1032 select inverted sine cardinal function
1038 @subsection Examples
1042 Fade in first 15 seconds of audio:
1044 afade=t=in:ss=0:d=15
1048 Fade out last 25 seconds of a 900 seconds audio:
1050 afade=t=out:st=875:d=25
1055 Denoise audio samples with FFT.
1057 A description of the accepted parameters follows.
1061 Set the noise reduction in dB, allowed range is 0.01 to 97.
1062 Default value is 12 dB.
1065 Set the noise floor in dB, allowed range is -80 to -20.
1066 Default value is -50 dB.
1071 It accepts the following values:
1080 Select shellac noise.
1083 Select custom noise, defined in @code{bn} option.
1085 Default value is white noise.
1089 Set custom band noise for every one of 15 bands.
1090 Bands are separated by ' ' or '|'.
1093 Set the residual floor in dB, allowed range is -80 to -20.
1094 Default value is -38 dB.
1097 Enable noise tracking. By default is disabled.
1098 With this enabled, noise floor is automatically adjusted.
1101 Enable residual tracking. By default is disabled.
1104 Set the output mode.
1106 It accepts the following values:
1109 Pass input unchanged.
1112 Pass noise filtered out.
1117 Default value is @var{o}.
1121 @subsection Commands
1123 This filter supports the following commands:
1125 @item sample_noise, sn
1126 Start or stop measuring noise profile.
1127 Syntax for the command is : "start" or "stop" string.
1128 After measuring noise profile is stopped it will be
1129 automatically applied in filtering.
1131 @item noise_reduction, nr
1132 Change noise reduction. Argument is single float number.
1133 Syntax for the command is : "@var{noise_reduction}"
1135 @item noise_floor, nf
1136 Change noise floor. Argument is single float number.
1137 Syntax for the command is : "@var{noise_floor}"
1139 @item output_mode, om
1140 Change output mode operation.
1141 Syntax for the command is : "i", "o" or "n" string.
1145 Apply arbitrary expressions to samples in frequency domain.
1149 Set frequency domain real expression for each separate channel separated
1150 by '|'. Default is "re".
1151 If the number of input channels is greater than the number of
1152 expressions, the last specified expression is used for the remaining
1156 Set frequency domain imaginary expression for each separate channel
1157 separated by '|'. Default is "im".
1159 Each expression in @var{real} and @var{imag} can contain the following
1160 constants and functions:
1167 current frequency bin number
1170 number of available bins
1173 channel number of the current expression
1182 current real part of frequency bin of current channel
1185 current imaginary part of frequency bin of current channel
1188 Return the value of real part of frequency bin at location (@var{bin},@var{channel})
1191 Return the value of imaginary part of frequency bin at location (@var{bin},@var{channel})
1195 Set window size. Allowed range is from 16 to 131072.
1196 Default is @code{4096}
1199 Set window function. Default is @code{hann}.
1202 Set window overlap. If set to 1, the recommended overlap for selected
1203 window function will be picked. Default is @code{0.75}.
1206 @subsection Examples
1210 Leave almost only low frequencies in audio:
1212 afftfilt="'real=re * (1-clip((b/nb)*b,0,1))':imag='im * (1-clip((b/nb)*b,0,1))'"
1216 Apply robotize effect:
1218 afftfilt="real='hypot(re,im)*sin(0)':imag='hypot(re,im)*cos(0)':win_size=512:overlap=0.75"
1222 Apply whisper effect:
1224 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"
1231 Apply an arbitrary Finite Impulse Response filter.
1233 This filter is designed for applying long FIR filters,
1234 up to 60 seconds long.
1236 It can be used as component for digital crossover filters,
1237 room equalization, cross talk cancellation, wavefield synthesis,
1238 auralization, ambiophonics, ambisonics and spatialization.
1240 This filter uses the streams higher than first one as FIR coefficients.
1241 If the non-first stream holds a single channel, it will be used
1242 for all input channels in the first stream, otherwise
1243 the number of channels in the non-first stream must be same as
1244 the number of channels in the first stream.
1246 It accepts the following parameters:
1250 Set dry gain. This sets input gain.
1253 Set wet gain. This sets final output gain.
1256 Set Impulse Response filter length. Default is 1, which means whole IR is processed.
1259 Enable applying gain measured from power of IR.
1261 Set which approach to use for auto gain measurement.
1265 Do not apply any gain.
1268 select peak gain, very conservative approach. This is default value.
1271 select DC gain, limited application.
1274 select gain to noise approach, this is most popular one.
1278 Set gain to be applied to IR coefficients before filtering.
1279 Allowed range is 0 to 1. This gain is applied after any gain applied with @var{gtype} option.
1282 Set format of IR stream. Can be @code{mono} or @code{input}.
1283 Default is @code{input}.
1286 Set max allowed Impulse Response filter duration in seconds. Default is 30 seconds.
1287 Allowed range is 0.1 to 60 seconds.
1290 Show IR frequency response, magnitude(magenta), phase(green) and group delay(yellow) in additional video stream.
1291 By default it is disabled.
1294 Set for which IR channel to display frequency response. By default is first channel
1295 displayed. This option is used only when @var{response} is enabled.
1298 Set video stream size. This option is used only when @var{response} is enabled.
1301 Set video stream frame rate. This option is used only when @var{response} is enabled.
1304 Set minimal partition size used for convolution. Default is @var{8192}.
1305 Allowed range is from @var{1} to @var{32768}.
1306 Lower values decreases latency at cost of higher CPU usage.
1309 Set maximal partition size used for convolution. Default is @var{8192}.
1310 Allowed range is from @var{8} to @var{32768}.
1311 Lower values may increase CPU usage.
1314 Set number of input impulse responses streams which will be switchable at runtime.
1315 Allowed range is from @var{1} to @var{32}. Default is @var{1}.
1318 Set IR stream which will be used for convolution, starting from @var{0}, should always be
1319 lower than supplied value by @code{nbirs} option. Default is @var{0}.
1320 This option can be changed at runtime via @ref{commands}.
1323 @subsection Examples
1327 Apply reverb to stream using mono IR file as second input, complete command using ffmpeg:
1329 ffmpeg -i input.wav -i middle_tunnel_1way_mono.wav -lavfi afir output.wav
1336 Set output format constraints for the input audio. The framework will
1337 negotiate the most appropriate format to minimize conversions.
1339 It accepts the following parameters:
1342 @item sample_fmts, f
1343 A '|'-separated list of requested sample formats.
1345 @item sample_rates, r
1346 A '|'-separated list of requested sample rates.
1348 @item channel_layouts, cl
1349 A '|'-separated list of requested channel layouts.
1351 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
1352 for the required syntax.
1355 If a parameter is omitted, all values are allowed.
1357 Force the output to either unsigned 8-bit or signed 16-bit stereo
1359 aformat=sample_fmts=u8|s16:channel_layouts=stereo
1363 Apply frequency shift to input audio samples.
1365 The filter accepts the following options:
1369 Specify frequency shift. Allowed range is -INT_MAX to INT_MAX.
1370 Default value is 0.0.
1373 @subsection Commands
1375 This filter supports the above option as @ref{commands}.
1379 A gate is mainly used to reduce lower parts of a signal. This kind of signal
1380 processing reduces disturbing noise between useful signals.
1382 Gating is done by detecting the volume below a chosen level @var{threshold}
1383 and dividing it by the factor set with @var{ratio}. The bottom of the noise
1384 floor is set via @var{range}. Because an exact manipulation of the signal
1385 would cause distortion of the waveform the reduction can be levelled over
1386 time. This is done by setting @var{attack} and @var{release}.
1388 @var{attack} determines how long the signal has to fall below the threshold
1389 before any reduction will occur and @var{release} sets the time the signal
1390 has to rise above the threshold to reduce the reduction again.
1391 Shorter signals than the chosen attack time will be left untouched.
1395 Set input level before filtering.
1396 Default is 1. Allowed range is from 0.015625 to 64.
1399 Set the mode of operation. Can be @code{upward} or @code{downward}.
1400 Default is @code{downward}. If set to @code{upward} mode, higher parts of signal
1401 will be amplified, expanding dynamic range in upward direction.
1402 Otherwise, in case of @code{downward} lower parts of signal will be reduced.
1405 Set the level of gain reduction when the signal is below the threshold.
1406 Default is 0.06125. Allowed range is from 0 to 1.
1407 Setting this to 0 disables reduction and then filter behaves like expander.
1410 If a signal rises above this level the gain reduction is released.
1411 Default is 0.125. Allowed range is from 0 to 1.
1414 Set a ratio by which the signal is reduced.
1415 Default is 2. Allowed range is from 1 to 9000.
1418 Amount of milliseconds the signal has to rise above the threshold before gain
1420 Default is 20 milliseconds. Allowed range is from 0.01 to 9000.
1423 Amount of milliseconds the signal has to fall below the threshold before the
1424 reduction is increased again. Default is 250 milliseconds.
1425 Allowed range is from 0.01 to 9000.
1428 Set amount of amplification of signal after processing.
1429 Default is 1. Allowed range is from 1 to 64.
1432 Curve the sharp knee around the threshold to enter gain reduction more softly.
1433 Default is 2.828427125. Allowed range is from 1 to 8.
1436 Choose if exact signal should be taken for detection or an RMS like one.
1437 Default is @code{rms}. Can be @code{peak} or @code{rms}.
1440 Choose if the average level between all channels or the louder channel affects
1442 Default is @code{average}. Can be @code{average} or @code{maximum}.
1447 Apply an arbitrary Infinite Impulse Response filter.
1449 It accepts the following parameters:
1453 Set B/numerator/zeros/reflection coefficients.
1456 Set A/denominator/poles/ladder coefficients.
1468 Set coefficients format.
1472 lattice-ladder function
1474 analog transfer function
1476 digital transfer function
1478 Z-plane zeros/poles, cartesian (default)
1480 Z-plane zeros/poles, polar radians
1482 Z-plane zeros/poles, polar degrees
1488 Set type of processing.
1500 Set filtering precision.
1504 double-precision floating-point (default)
1506 single-precision floating-point
1514 Normalize filter coefficients, by default is enabled.
1515 Enabling it will normalize magnitude response at DC to 0dB.
1518 How much to use filtered signal in output. Default is 1.
1519 Range is between 0 and 1.
1522 Show IR frequency response, magnitude(magenta), phase(green) and group delay(yellow) in additional video stream.
1523 By default it is disabled.
1526 Set for which IR channel to display frequency response. By default is first channel
1527 displayed. This option is used only when @var{response} is enabled.
1530 Set video stream size. This option is used only when @var{response} is enabled.
1533 Coefficients in @code{tf} and @code{sf} format are separated by spaces and are in ascending
1536 Coefficients in @code{zp} format are separated by spaces and order of coefficients
1537 doesn't matter. Coefficients in @code{zp} format are complex numbers with @var{i}
1540 Different coefficients and gains can be provided for every channel, in such case
1541 use '|' to separate coefficients or gains. Last provided coefficients will be
1542 used for all remaining channels.
1544 @subsection Examples
1548 Apply 2 pole elliptic notch at around 5000Hz for 48000 Hz sample rate:
1550 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
1554 Same as above but in @code{zp} format:
1556 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
1560 Apply 3-rd order analog normalized Butterworth low-pass filter, using analog transfer function format:
1562 aiir=z=1.3057 0 0 0:p=1.3057 2.3892 2.1860 1:f=sf:r=d
1568 The limiter prevents an input signal from rising over a desired threshold.
1569 This limiter uses lookahead technology to prevent your signal from distorting.
1570 It means that there is a small delay after the signal is processed. Keep in mind
1571 that the delay it produces is the attack time you set.
1573 The filter accepts the following options:
1577 Set input gain. Default is 1.
1580 Set output gain. Default is 1.
1583 Don't let signals above this level pass the limiter. Default is 1.
1586 The limiter will reach its attenuation level in this amount of time in
1587 milliseconds. Default is 5 milliseconds.
1590 Come back from limiting to attenuation 1.0 in this amount of milliseconds.
1591 Default is 50 milliseconds.
1594 When gain reduction is always needed ASC takes care of releasing to an
1595 average reduction level rather than reaching a reduction of 0 in the release
1599 Select how much the release time is affected by ASC, 0 means nearly no changes
1600 in release time while 1 produces higher release times.
1603 Auto level output signal. Default is enabled.
1604 This normalizes audio back to 0dB if enabled.
1607 Depending on picked setting it is recommended to upsample input 2x or 4x times
1608 with @ref{aresample} before applying this filter.
1612 Apply a two-pole all-pass filter with central frequency (in Hz)
1613 @var{frequency}, and filter-width @var{width}.
1614 An all-pass filter changes the audio's frequency to phase relationship
1615 without changing its frequency to amplitude relationship.
1617 The filter accepts the following options:
1621 Set frequency in Hz.
1624 Set method to specify band-width of filter.
1639 Specify the band-width of a filter in width_type units.
1642 How much to use filtered signal in output. Default is 1.
1643 Range is between 0 and 1.
1646 Specify which channels to filter, by default all available are filtered.
1649 Normalize biquad coefficients, by default is disabled.
1650 Enabling it will normalize magnitude response at DC to 0dB.
1653 Set the filter order, can be 1 or 2. Default is 2.
1656 Set transform type of IIR filter.
1665 @subsection Commands
1667 This filter supports the following commands:
1670 Change allpass frequency.
1671 Syntax for the command is : "@var{frequency}"
1674 Change allpass width_type.
1675 Syntax for the command is : "@var{width_type}"
1678 Change allpass width.
1679 Syntax for the command is : "@var{width}"
1683 Syntax for the command is : "@var{mix}"
1690 The filter accepts the following options:
1694 Set the number of loops. Setting this value to -1 will result in infinite loops.
1698 Set maximal number of samples. Default is 0.
1701 Set first sample of loop. Default is 0.
1707 Merge two or more audio streams into a single multi-channel stream.
1709 The filter accepts the following options:
1714 Set the number of inputs. Default is 2.
1718 If the channel layouts of the inputs are disjoint, and therefore compatible,
1719 the channel layout of the output will be set accordingly and the channels
1720 will be reordered as necessary. If the channel layouts of the inputs are not
1721 disjoint, the output will have all the channels of the first input then all
1722 the channels of the second input, in that order, and the channel layout of
1723 the output will be the default value corresponding to the total number of
1726 For example, if the first input is in 2.1 (FL+FR+LF) and the second input
1727 is FC+BL+BR, then the output will be in 5.1, with the channels in the
1728 following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the
1729 first input, b1 is the first channel of the second input).
1731 On the other hand, if both input are in stereo, the output channels will be
1732 in the default order: a1, a2, b1, b2, and the channel layout will be
1733 arbitrarily set to 4.0, which may or may not be the expected value.
1735 All inputs must have the same sample rate, and format.
1737 If inputs do not have the same duration, the output will stop with the
1740 @subsection Examples
1744 Merge two mono files into a stereo stream:
1746 amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge
1750 Multiple merges assuming 1 video stream and 6 audio streams in @file{input.mkv}:
1752 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
1758 Mixes multiple audio inputs into a single output.
1760 Note that this filter only supports float samples (the @var{amerge}
1761 and @var{pan} audio filters support many formats). If the @var{amix}
1762 input has integer samples then @ref{aresample} will be automatically
1763 inserted to perform the conversion to float samples.
1767 ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT
1769 will mix 3 input audio streams to a single output with the same duration as the
1770 first input and a dropout transition time of 3 seconds.
1772 It accepts the following parameters:
1776 The number of inputs. If unspecified, it defaults to 2.
1779 How to determine the end-of-stream.
1783 The duration of the longest input. (default)
1786 The duration of the shortest input.
1789 The duration of the first input.
1793 @item dropout_transition
1794 The transition time, in seconds, for volume renormalization when an input
1795 stream ends. The default value is 2 seconds.
1798 Specify weight of each input audio stream as sequence.
1799 Each weight is separated by space. By default all inputs have same weight.
1802 @subsection Commands
1804 This filter supports the following commands:
1807 Syntax is same as option with same name.
1812 Multiply first audio stream with second audio stream and store result
1813 in output audio stream. Multiplication is done by multiplying each
1814 sample from first stream with sample at same position from second stream.
1816 With this element-wise multiplication one can create amplitude fades and
1817 amplitude modulations.
1819 @section anequalizer
1821 High-order parametric multiband equalizer for each channel.
1823 It accepts the following parameters:
1827 This option string is in format:
1828 "c@var{chn} f=@var{cf} w=@var{w} g=@var{g} t=@var{f} | ..."
1829 Each equalizer band is separated by '|'.
1833 Set channel number to which equalization will be applied.
1834 If input doesn't have that channel the entry is ignored.
1837 Set central frequency for band.
1838 If input doesn't have that frequency the entry is ignored.
1841 Set band width in hertz.
1844 Set band gain in dB.
1847 Set filter type for band, optional, can be:
1851 Butterworth, this is default.
1862 With this option activated frequency response of anequalizer is displayed
1866 Set video stream size. Only useful if curves option is activated.
1869 Set max gain that will be displayed. Only useful if curves option is activated.
1870 Setting this to a reasonable value makes it possible to display gain which is derived from
1871 neighbour bands which are too close to each other and thus produce higher gain
1872 when both are activated.
1875 Set frequency scale used to draw frequency response in video output.
1876 Can be linear or logarithmic. Default is logarithmic.
1879 Set color for each channel curve which is going to be displayed in video stream.
1880 This is list of color names separated by space or by '|'.
1881 Unrecognised or missing colors will be replaced by white color.
1884 @subsection Examples
1888 Lower gain by 10 of central frequency 200Hz and width 100 Hz
1889 for first 2 channels using Chebyshev type 1 filter:
1891 anequalizer=c0 f=200 w=100 g=-10 t=1|c1 f=200 w=100 g=-10 t=1
1895 @subsection Commands
1897 This filter supports the following commands:
1900 Alter existing filter parameters.
1901 Syntax for the commands is : "@var{fN}|f=@var{freq}|w=@var{width}|g=@var{gain}"
1903 @var{fN} is existing filter number, starting from 0, if no such filter is available
1905 @var{freq} set new frequency parameter.
1906 @var{width} set new width parameter in herz.
1907 @var{gain} set new gain parameter in dB.
1909 Full filter invocation with asendcmd may look like this:
1910 asendcmd=c='4.0 anequalizer change 0|f=200|w=50|g=1',anequalizer=...
1915 Reduce broadband noise in audio samples using Non-Local Means algorithm.
1917 Each sample is adjusted by looking for other samples with similar contexts. This
1918 context similarity is defined by comparing their surrounding patches of size
1919 @option{p}. Patches are searched in an area of @option{r} around the sample.
1921 The filter accepts the following options:
1925 Set denoising strength. Allowed range is from 0.00001 to 10. Default value is 0.00001.
1928 Set patch radius duration. Allowed range is from 1 to 100 milliseconds.
1929 Default value is 2 milliseconds.
1932 Set research radius duration. Allowed range is from 2 to 300 milliseconds.
1933 Default value is 6 milliseconds.
1936 Set the output mode.
1938 It accepts the following values:
1941 Pass input unchanged.
1944 Pass noise filtered out.
1949 Default value is @var{o}.
1953 Set smooth factor. Default value is @var{11}. Allowed range is from @var{1} to @var{15}.
1956 @subsection Commands
1958 This filter supports the all above options as @ref{commands}.
1961 Apply Normalized Least-Mean-Squares algorithm to the first audio stream using the second audio stream.
1963 This adaptive filter is used to mimic a desired filter by finding the filter coefficients that
1964 relate to producing the least mean square of the error signal (difference between the desired,
1965 2nd input audio stream and the actual signal, the 1st input audio stream).
1967 A description of the accepted options follows.
1980 Set the filter leakage.
1983 It accepts the following values:
1992 Pass filtered samples.
1995 Pass difference between desired and filtered samples.
1997 Default value is @var{o}.
2001 @subsection Examples
2005 One of many usages of this filter is noise reduction, input audio is filtered
2006 with same samples that are delayed by fixed amount, one such example for stereo audio is:
2008 asplit[a][b],[a]adelay=32S|32S[a],[b][a]anlms=order=128:leakage=0.0005:mu=.5:out_mode=o
2012 @subsection Commands
2014 This filter supports the same commands as options, excluding option @code{order}.
2018 Pass the audio source unchanged to the output.
2022 Pad the end of an audio stream with silence.
2024 This can be used together with @command{ffmpeg} @option{-shortest} to
2025 extend audio streams to the same length as the video stream.
2027 A description of the accepted options follows.
2031 Set silence packet size. Default value is 4096.
2034 Set the number of samples of silence to add to the end. After the
2035 value is reached, the stream is terminated. This option is mutually
2036 exclusive with @option{whole_len}.
2039 Set the minimum total number of samples in the output audio stream. If
2040 the value is longer than the input audio length, silence is added to
2041 the end, until the value is reached. This option is mutually exclusive
2042 with @option{pad_len}.
2045 Specify the duration of samples of silence to add. See
2046 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
2047 for the accepted syntax. Used only if set to non-zero value.
2050 Specify the minimum total duration in the output audio stream. See
2051 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
2052 for the accepted syntax. Used only if set to non-zero value. If the value is longer than
2053 the input audio length, silence is added to the end, until the value is reached.
2054 This option is mutually exclusive with @option{pad_dur}
2057 If neither the @option{pad_len} nor the @option{whole_len} nor @option{pad_dur}
2058 nor @option{whole_dur} option is set, the filter will add silence to the end of
2059 the input stream indefinitely.
2061 @subsection Examples
2065 Add 1024 samples of silence to the end of the input:
2071 Make sure the audio output will contain at least 10000 samples, pad
2072 the input with silence if required:
2074 apad=whole_len=10000
2078 Use @command{ffmpeg} to pad the audio input with silence, so that the
2079 video stream will always result the shortest and will be converted
2080 until the end in the output file when using the @option{shortest}
2083 ffmpeg -i VIDEO -i AUDIO -filter_complex "[1:0]apad" -shortest OUTPUT
2088 Add a phasing effect to the input audio.
2090 A phaser filter creates series of peaks and troughs in the frequency spectrum.
2091 The position of the peaks and troughs are modulated so that they vary over time, creating a sweeping effect.
2093 A description of the accepted parameters follows.
2097 Set input gain. Default is 0.4.
2100 Set output gain. Default is 0.74
2103 Set delay in milliseconds. Default is 3.0.
2106 Set decay. Default is 0.4.
2109 Set modulation speed in Hz. Default is 0.5.
2112 Set modulation type. Default is triangular.
2114 It accepts the following values:
2121 @section aphaseshift
2122 Apply phase shift to input audio samples.
2124 The filter accepts the following options:
2128 Specify phase shift. Allowed range is from -1.0 to 1.0.
2129 Default value is 0.0.
2132 @subsection Commands
2134 This filter supports the above option as @ref{commands}.
2138 Audio pulsator is something between an autopanner and a tremolo.
2139 But it can produce funny stereo effects as well. Pulsator changes the volume
2140 of the left and right channel based on a LFO (low frequency oscillator) with
2141 different waveforms and shifted phases.
2142 This filter have the ability to define an offset between left and right
2143 channel. An offset of 0 means that both LFO shapes match each other.
2144 The left and right channel are altered equally - a conventional tremolo.
2145 An offset of 50% means that the shape of the right channel is exactly shifted
2146 in phase (or moved backwards about half of the frequency) - pulsator acts as
2147 an autopanner. At 1 both curves match again. Every setting in between moves the
2148 phase shift gapless between all stages and produces some "bypassing" sounds with
2149 sine and triangle waveforms. The more you set the offset near 1 (starting from
2150 the 0.5) the faster the signal passes from the left to the right speaker.
2152 The filter accepts the following options:
2156 Set input gain. By default it is 1. Range is [0.015625 - 64].
2159 Set output gain. By default it is 1. Range is [0.015625 - 64].
2162 Set waveform shape the LFO will use. Can be one of: sine, triangle, square,
2163 sawup or sawdown. Default is sine.
2166 Set modulation. Define how much of original signal is affected by the LFO.
2169 Set left channel offset. Default is 0. Allowed range is [0 - 1].
2172 Set right channel offset. Default is 0.5. Allowed range is [0 - 1].
2175 Set pulse width. Default is 1. Allowed range is [0 - 2].
2178 Set possible timing mode. Can be one of: bpm, ms or hz. Default is hz.
2181 Set bpm. Default is 120. Allowed range is [30 - 300]. Only used if timing
2185 Set ms. Default is 500. Allowed range is [10 - 2000]. Only used if timing
2189 Set frequency in Hz. Default is 2. Allowed range is [0.01 - 100]. Only used
2190 if timing is set to hz.
2196 Resample the input audio to the specified parameters, using the
2197 libswresample library. If none are specified then the filter will
2198 automatically convert between its input and output.
2200 This filter is also able to stretch/squeeze the audio data to make it match
2201 the timestamps or to inject silence / cut out audio to make it match the
2202 timestamps, do a combination of both or do neither.
2204 The filter accepts the syntax
2205 [@var{sample_rate}:]@var{resampler_options}, where @var{sample_rate}
2206 expresses a sample rate and @var{resampler_options} is a list of
2207 @var{key}=@var{value} pairs, separated by ":". See the
2208 @ref{Resampler Options,,"Resampler Options" section in the
2209 ffmpeg-resampler(1) manual,ffmpeg-resampler}
2210 for the complete list of supported options.
2212 @subsection Examples
2216 Resample the input audio to 44100Hz:
2222 Stretch/squeeze samples to the given timestamps, with a maximum of 1000
2223 samples per second compensation:
2225 aresample=async=1000
2231 Reverse an audio clip.
2233 Warning: This filter requires memory to buffer the entire clip, so trimming
2236 @subsection Examples
2240 Take the first 5 seconds of a clip, and reverse it.
2242 atrim=end=5,areverse
2248 Reduce noise from speech using Recurrent Neural Networks.
2250 This filter accepts the following options:
2254 Set train model file to load. This option is always required.
2257 @section asetnsamples
2259 Set the number of samples per each output audio frame.
2261 The last output packet may contain a different number of samples, as
2262 the filter will flush all the remaining samples when the input audio
2265 The filter accepts the following options:
2269 @item nb_out_samples, n
2270 Set the number of frames per each output audio frame. The number is
2271 intended as the number of samples @emph{per each channel}.
2272 Default value is 1024.
2275 If set to 1, the filter will pad the last audio frame with zeroes, so
2276 that the last frame will contain the same number of samples as the
2277 previous ones. Default value is 1.
2280 For example, to set the number of per-frame samples to 1234 and
2281 disable padding for the last frame, use:
2283 asetnsamples=n=1234:p=0
2288 Set the sample rate without altering the PCM data.
2289 This will result in a change of speed and pitch.
2291 The filter accepts the following options:
2294 @item sample_rate, r
2295 Set the output sample rate. Default is 44100 Hz.
2300 Show a line containing various information for each input audio frame.
2301 The input audio is not modified.
2303 The shown line contains a sequence of key/value pairs of the form
2304 @var{key}:@var{value}.
2306 The following values are shown in the output:
2310 The (sequential) number of the input frame, starting from 0.
2313 The presentation timestamp of the input frame, in time base units; the time base
2314 depends on the filter input pad, and is usually 1/@var{sample_rate}.
2317 The presentation timestamp of the input frame in seconds.
2320 position of the frame in the input stream, -1 if this information in
2321 unavailable and/or meaningless (for example in case of synthetic audio)
2330 The sample rate for the audio frame.
2333 The number of samples (per channel) in the frame.
2336 The Adler-32 checksum (printed in hexadecimal) of the audio data. For planar
2337 audio, the data is treated as if all the planes were concatenated.
2339 @item plane_checksums
2340 A list of Adler-32 checksums for each data plane.
2344 Apply audio soft clipping.
2346 Soft clipping is a type of distortion effect where the amplitude of a signal is saturated
2347 along a smooth curve, rather than the abrupt shape of hard-clipping.
2349 This filter accepts the following options:
2353 Set type of soft-clipping.
2355 It accepts the following values:
2369 Set additional parameter which controls sigmoid function.
2372 Set oversampling factor.
2375 @subsection Commands
2377 This filter supports the all above options as @ref{commands}.
2380 Automatic Speech Recognition
2382 This filter uses PocketSphinx for speech recognition. To enable
2383 compilation of this filter, you need to configure FFmpeg with
2384 @code{--enable-pocketsphinx}.
2386 It accepts the following options:
2390 Set sampling rate of input audio. Defaults is @code{16000}.
2391 This need to match speech models, otherwise one will get poor results.
2394 Set dictionary containing acoustic model files.
2397 Set pronunciation dictionary.
2400 Set language model file.
2403 Set language model set.
2406 Set which language model to use.
2409 Set output for log messages.
2412 The filter exports recognized speech as the frame metadata @code{lavfi.asr.text}.
2417 Display time domain statistical information about the audio channels.
2418 Statistics are calculated and displayed for each audio channel and,
2419 where applicable, an overall figure is also given.
2421 It accepts the following option:
2424 Short window length in seconds, used for peak and trough RMS measurement.
2425 Default is @code{0.05} (50 milliseconds). Allowed range is @code{[0.01 - 10]}.
2429 Set metadata injection. All the metadata keys are prefixed with @code{lavfi.astats.X},
2430 where @code{X} is channel number starting from 1 or string @code{Overall}. Default is
2433 Available keys for each channel are:
2479 For example full key look like this @code{lavfi.astats.1.DC_offset} or
2480 this @code{lavfi.astats.Overall.Peak_count}.
2482 For description what each key means read below.
2485 Set number of frame after which stats are going to be recalculated.
2486 Default is disabled.
2488 @item measure_perchannel
2489 Select the entries which need to be measured per channel. The metadata keys can
2490 be used as flags, default is @option{all} which measures everything.
2491 @option{none} disables all per channel measurement.
2493 @item measure_overall
2494 Select the entries which need to be measured overall. The metadata keys can
2495 be used as flags, default is @option{all} which measures everything.
2496 @option{none} disables all overall measurement.
2500 A description of each shown parameter follows:
2504 Mean amplitude displacement from zero.
2507 Minimal sample level.
2510 Maximal sample level.
2512 @item Min difference
2513 Minimal difference between two consecutive samples.
2515 @item Max difference
2516 Maximal difference between two consecutive samples.
2518 @item Mean difference
2519 Mean difference between two consecutive samples.
2520 The average of each difference between two consecutive samples.
2522 @item RMS difference
2523 Root Mean Square difference between two consecutive samples.
2527 Standard peak and RMS level measured in dBFS.
2531 Peak and trough values for RMS level measured over a short window.
2534 Standard ratio of peak to RMS level (note: not in dB).
2537 Flatness (i.e. consecutive samples with the same value) of the signal at its peak levels
2538 (i.e. either @var{Min level} or @var{Max level}).
2541 Number of occasions (not the number of samples) that the signal attained either
2542 @var{Min level} or @var{Max level}.
2544 @item Noise floor dB
2545 Minimum local peak measured in dBFS over a short window.
2547 @item Noise floor count
2548 Number of occasions (not the number of samples) that the signal attained
2552 Overall bit depth of audio. Number of bits used for each sample.
2555 Measured dynamic range of audio in dB.
2557 @item Zero crossings
2558 Number of points where the waveform crosses the zero level axis.
2560 @item Zero crossings rate
2561 Rate of Zero crossings and number of audio samples.
2565 Boost subwoofer frequencies.
2567 The filter accepts the following options:
2571 Set dry gain, how much of original signal is kept. Allowed range is from 0 to 1.
2572 Default value is 0.5.
2575 Set wet gain, how much of filtered signal is kept. Allowed range is from 0 to 1.
2576 Default value is 0.8.
2579 Set delay line decay gain value. Allowed range is from 0 to 1.
2580 Default value is 0.7.
2583 Set delay line feedback gain value. Allowed range is from 0 to 1.
2584 Default value is 0.5.
2587 Set cutoff frequency in herz. Allowed range is 50 to 900.
2588 Default value is 100.
2591 Set slope amount for cutoff frequency. Allowed range is 0.0001 to 1.
2592 Default value is 0.5.
2595 Set delay. Allowed range is from 1 to 100.
2596 Default value is 20.
2599 @subsection Commands
2601 This filter supports the all above options as @ref{commands}.
2607 The filter accepts exactly one parameter, the audio tempo. If not
2608 specified then the filter will assume nominal 1.0 tempo. Tempo must
2609 be in the [0.5, 100.0] range.
2611 Note that tempo greater than 2 will skip some samples rather than
2612 blend them in. If for any reason this is a concern it is always
2613 possible to daisy-chain several instances of atempo to achieve the
2614 desired product tempo.
2616 @subsection Examples
2620 Slow down audio to 80% tempo:
2626 To speed up audio to 300% tempo:
2632 To speed up audio to 300% tempo by daisy-chaining two atempo instances:
2634 atempo=sqrt(3),atempo=sqrt(3)
2638 @subsection Commands
2640 This filter supports the following commands:
2643 Change filter tempo scale factor.
2644 Syntax for the command is : "@var{tempo}"
2649 Trim the input so that the output contains one continuous subpart of the input.
2651 It accepts the following parameters:
2654 Timestamp (in seconds) of the start of the section to keep. I.e. the audio
2655 sample with the timestamp @var{start} will be the first sample in the output.
2658 Specify time of the first audio sample that will be dropped, i.e. the
2659 audio sample immediately preceding the one with the timestamp @var{end} will be
2660 the last sample in the output.
2663 Same as @var{start}, except this option sets the start timestamp in samples
2667 Same as @var{end}, except this option sets the end timestamp in samples instead
2671 The maximum duration of the output in seconds.
2674 The number of the first sample that should be output.
2677 The number of the first sample that should be dropped.
2680 @option{start}, @option{end}, and @option{duration} are expressed as time
2681 duration specifications; see
2682 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}.
2684 Note that the first two sets of the start/end options and the @option{duration}
2685 option look at the frame timestamp, while the _sample options simply count the
2686 samples that pass through the filter. So start/end_pts and start/end_sample will
2687 give different results when the timestamps are wrong, inexact or do not start at
2688 zero. Also note that this filter does not modify the timestamps. If you wish
2689 to have the output timestamps start at zero, insert the asetpts filter after the
2692 If multiple start or end options are set, this filter tries to be greedy and
2693 keep all samples that match at least one of the specified constraints. To keep
2694 only the part that matches all the constraints at once, chain multiple atrim
2697 The defaults are such that all the input is kept. So it is possible to set e.g.
2698 just the end values to keep everything before the specified time.
2703 Drop everything except the second minute of input:
2705 ffmpeg -i INPUT -af atrim=60:120
2709 Keep only the first 1000 samples:
2711 ffmpeg -i INPUT -af atrim=end_sample=1000
2716 @section axcorrelate
2717 Calculate normalized cross-correlation between two input audio streams.
2719 Resulted samples are always between -1 and 1 inclusive.
2720 If result is 1 it means two input samples are highly correlated in that selected segment.
2721 Result 0 means they are not correlated at all.
2722 If result is -1 it means two input samples are out of phase, which means they cancel each
2725 The filter accepts the following options:
2729 Set size of segment over which cross-correlation is calculated.
2730 Default is 256. Allowed range is from 2 to 131072.
2733 Set algorithm for cross-correlation. Can be @code{slow} or @code{fast}.
2734 Default is @code{slow}. Fast algorithm assumes mean values over any given segment
2735 are always zero and thus need much less calculations to make.
2736 This is generally not true, but is valid for typical audio streams.
2739 @subsection Examples
2743 Calculate correlation between channels in stereo audio stream:
2745 ffmpeg -i stereo.wav -af channelsplit,axcorrelate=size=1024:algo=fast correlation.wav
2751 Apply a two-pole Butterworth band-pass filter with central
2752 frequency @var{frequency}, and (3dB-point) band-width width.
2753 The @var{csg} option selects a constant skirt gain (peak gain = Q)
2754 instead of the default: constant 0dB peak gain.
2755 The filter roll off at 6dB per octave (20dB per decade).
2757 The filter accepts the following options:
2761 Set the filter's central frequency. Default is @code{3000}.
2764 Constant skirt gain if set to 1. Defaults to 0.
2767 Set method to specify band-width of filter.
2782 Specify the band-width of a filter in width_type units.
2785 How much to use filtered signal in output. Default is 1.
2786 Range is between 0 and 1.
2789 Specify which channels to filter, by default all available are filtered.
2792 Normalize biquad coefficients, by default is disabled.
2793 Enabling it will normalize magnitude response at DC to 0dB.
2796 Set transform type of IIR filter.
2805 @subsection Commands
2807 This filter supports the following commands:
2810 Change bandpass frequency.
2811 Syntax for the command is : "@var{frequency}"
2814 Change bandpass width_type.
2815 Syntax for the command is : "@var{width_type}"
2818 Change bandpass width.
2819 Syntax for the command is : "@var{width}"
2822 Change bandpass mix.
2823 Syntax for the command is : "@var{mix}"
2828 Apply a two-pole Butterworth band-reject filter with central
2829 frequency @var{frequency}, and (3dB-point) band-width @var{width}.
2830 The filter roll off at 6dB per octave (20dB per decade).
2832 The filter accepts the following options:
2836 Set the filter's central frequency. Default is @code{3000}.
2839 Set method to specify band-width of filter.
2854 Specify the band-width of a filter in width_type units.
2857 How much to use filtered signal in output. Default is 1.
2858 Range is between 0 and 1.
2861 Specify which channels to filter, by default all available are filtered.
2864 Normalize biquad coefficients, by default is disabled.
2865 Enabling it will normalize magnitude response at DC to 0dB.
2868 Set transform type of IIR filter.
2877 @subsection Commands
2879 This filter supports the following commands:
2882 Change bandreject frequency.
2883 Syntax for the command is : "@var{frequency}"
2886 Change bandreject width_type.
2887 Syntax for the command is : "@var{width_type}"
2890 Change bandreject width.
2891 Syntax for the command is : "@var{width}"
2894 Change bandreject mix.
2895 Syntax for the command is : "@var{mix}"
2898 @section bass, lowshelf
2900 Boost or cut the bass (lower) frequencies of the audio using a two-pole
2901 shelving filter with a response similar to that of a standard
2902 hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
2904 The filter accepts the following options:
2908 Give the gain at 0 Hz. Its useful range is about -20
2909 (for a large cut) to +20 (for a large boost).
2910 Beware of clipping when using a positive gain.
2913 Set the filter's central frequency and so can be used
2914 to extend or reduce the frequency range to be boosted or cut.
2915 The default value is @code{100} Hz.
2918 Set method to specify band-width of filter.
2933 Determine how steep is the filter's shelf transition.
2936 How much to use filtered signal in output. Default is 1.
2937 Range is between 0 and 1.
2940 Specify which channels to filter, by default all available are filtered.
2943 Normalize biquad coefficients, by default is disabled.
2944 Enabling it will normalize magnitude response at DC to 0dB.
2947 Set transform type of IIR filter.
2956 @subsection Commands
2958 This filter supports the following commands:
2961 Change bass frequency.
2962 Syntax for the command is : "@var{frequency}"
2965 Change bass width_type.
2966 Syntax for the command is : "@var{width_type}"
2970 Syntax for the command is : "@var{width}"
2974 Syntax for the command is : "@var{gain}"
2978 Syntax for the command is : "@var{mix}"
2983 Apply a biquad IIR filter with the given coefficients.
2984 Where @var{b0}, @var{b1}, @var{b2} and @var{a0}, @var{a1}, @var{a2}
2985 are the numerator and denominator coefficients respectively.
2986 and @var{channels}, @var{c} specify which channels to filter, by default all
2987 available are filtered.
2989 @subsection Commands
2991 This filter supports the following commands:
2999 Change biquad parameter.
3000 Syntax for the command is : "@var{value}"
3003 How much to use filtered signal in output. Default is 1.
3004 Range is between 0 and 1.
3007 Specify which channels to filter, by default all available are filtered.
3010 Normalize biquad coefficients, by default is disabled.
3011 Enabling it will normalize magnitude response at DC to 0dB.
3014 Set transform type of IIR filter.
3024 Bauer stereo to binaural transformation, which improves headphone listening of
3025 stereo audio records.
3027 To enable compilation of this filter you need to configure FFmpeg with
3028 @code{--enable-libbs2b}.
3030 It accepts the following parameters:
3034 Pre-defined crossfeed level.
3038 Default level (fcut=700, feed=50).
3041 Chu Moy circuit (fcut=700, feed=60).
3044 Jan Meier circuit (fcut=650, feed=95).
3049 Cut frequency (in Hz).
3058 Remap input channels to new locations.
3060 It accepts the following parameters:
3063 Map channels from input to output. The argument is a '|'-separated list of
3064 mappings, each in the @code{@var{in_channel}-@var{out_channel}} or
3065 @var{in_channel} form. @var{in_channel} can be either the name of the input
3066 channel (e.g. FL for front left) or its index in the input channel layout.
3067 @var{out_channel} is the name of the output channel or its index in the output
3068 channel layout. If @var{out_channel} is not given then it is implicitly an
3069 index, starting with zero and increasing by one for each mapping.
3071 @item channel_layout
3072 The channel layout of the output stream.
3075 If no mapping is present, the filter will implicitly map input channels to
3076 output channels, preserving indices.
3078 @subsection Examples
3082 For example, assuming a 5.1+downmix input MOV file,
3084 ffmpeg -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav
3086 will create an output WAV file tagged as stereo from the downmix channels of
3090 To fix a 5.1 WAV improperly encoded in AAC's native channel order
3092 ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:5.1' out.wav
3096 @section channelsplit
3098 Split each channel from an input audio stream into a separate output stream.
3100 It accepts the following parameters:
3102 @item channel_layout
3103 The channel layout of the input stream. The default is "stereo".
3105 A channel layout describing the channels to be extracted as separate output streams
3106 or "all" to extract each input channel as a separate stream. The default is "all".
3108 Choosing channels not present in channel layout in the input will result in an error.
3111 @subsection Examples
3115 For example, assuming a stereo input MP3 file,
3117 ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv
3119 will create an output Matroska file with two audio streams, one containing only
3120 the left channel and the other the right channel.
3123 Split a 5.1 WAV file into per-channel files:
3125 ffmpeg -i in.wav -filter_complex
3126 'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]'
3127 -map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]'
3128 front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]'
3133 Extract only LFE from a 5.1 WAV file:
3135 ffmpeg -i in.wav -filter_complex 'channelsplit=channel_layout=5.1:channels=LFE[LFE]'
3136 -map '[LFE]' lfe.wav
3141 Add a chorus effect to the audio.
3143 Can make a single vocal sound like a chorus, but can also be applied to instrumentation.
3145 Chorus resembles an echo effect with a short delay, but whereas with echo the delay is
3146 constant, with chorus, it is varied using using sinusoidal or triangular modulation.
3147 The modulation depth defines the range the modulated delay is played before or after
3148 the delay. Hence the delayed sound will sound slower or faster, that is the delayed
3149 sound tuned around the original one, like in a chorus where some vocals are slightly
3152 It accepts the following parameters:
3155 Set input gain. Default is 0.4.
3158 Set output gain. Default is 0.4.
3161 Set delays. A typical delay is around 40ms to 60ms.
3173 @subsection Examples
3179 chorus=0.7:0.9:55:0.4:0.25:2
3185 chorus=0.6:0.9:50|60:0.4|0.32:0.25|0.4:2|1.3
3189 Fuller sounding chorus with three delays:
3191 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
3196 Compress or expand the audio's dynamic range.
3198 It accepts the following parameters:
3204 A list of times in seconds for each channel over which the instantaneous level
3205 of the input signal is averaged to determine its volume. @var{attacks} refers to
3206 increase of volume and @var{decays} refers to decrease of volume. For most
3207 situations, the attack time (response to the audio getting louder) should be
3208 shorter than the decay time, because the human ear is more sensitive to sudden
3209 loud audio than sudden soft audio. A typical value for attack is 0.3 seconds and
3210 a typical value for decay is 0.8 seconds.
3211 If specified number of attacks & decays is lower than number of channels, the last
3212 set attack/decay will be used for all remaining channels.
3215 A list of points for the transfer function, specified in dB relative to the
3216 maximum possible signal amplitude. Each key points list must be defined using
3217 the following syntax: @code{x0/y0|x1/y1|x2/y2|....} or
3218 @code{x0/y0 x1/y1 x2/y2 ....}
3220 The input values must be in strictly increasing order but the transfer function
3221 does not have to be monotonically rising. The point @code{0/0} is assumed but
3222 may be overridden (by @code{0/out-dBn}). Typical values for the transfer
3223 function are @code{-70/-70|-60/-20|1/0}.
3226 Set the curve radius in dB for all joints. It defaults to 0.01.
3229 Set the additional gain in dB to be applied at all points on the transfer
3230 function. This allows for easy adjustment of the overall gain.
3234 Set an initial volume, in dB, to be assumed for each channel when filtering
3235 starts. This permits the user to supply a nominal level initially, so that, for
3236 example, a very large gain is not applied to initial signal levels before the
3237 companding has begun to operate. A typical value for audio which is initially
3238 quiet is -90 dB. It defaults to 0.
3241 Set a delay, in seconds. The input audio is analyzed immediately, but audio is
3242 delayed before being fed to the volume adjuster. Specifying a delay
3243 approximately equal to the attack/decay times allows the filter to effectively
3244 operate in predictive rather than reactive mode. It defaults to 0.
3248 @subsection Examples
3252 Make music with both quiet and loud passages suitable for listening to in a
3255 compand=.3|.3:1|1:-90/-60|-60/-40|-40/-30|-20/-20:6:0:-90:0.2
3258 Another example for audio with whisper and explosion parts:
3260 compand=0|0:1|1:-90/-900|-70/-70|-30/-9|0/-3:6:0:0:0
3264 A noise gate for when the noise is at a lower level than the signal:
3266 compand=.1|.1:.2|.2:-900/-900|-50.1/-900|-50/-50:.01:0:-90:.1
3270 Here is another noise gate, this time for when the noise is at a higher level
3271 than the signal (making it, in some ways, similar to squelch):
3273 compand=.1|.1:.1|.1:-45.1/-45.1|-45/-900|0/-900:.01:45:-90:.1
3277 2:1 compression starting at -6dB:
3279 compand=points=-80/-80|-6/-6|0/-3.8|20/3.5
3283 2:1 compression starting at -9dB:
3285 compand=points=-80/-80|-9/-9|0/-5.3|20/2.9
3289 2:1 compression starting at -12dB:
3291 compand=points=-80/-80|-12/-12|0/-6.8|20/1.9
3295 2:1 compression starting at -18dB:
3297 compand=points=-80/-80|-18/-18|0/-9.8|20/0.7
3301 3:1 compression starting at -15dB:
3303 compand=points=-80/-80|-15/-15|0/-10.8|20/-5.2
3309 compand=points=-80/-105|-62/-80|-15.4/-15.4|0/-12|20/-7.6
3315 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
3319 Hard limiter at -6dB:
3321 compand=attacks=0:points=-80/-80|-6/-6|20/-6
3325 Hard limiter at -12dB:
3327 compand=attacks=0:points=-80/-80|-12/-12|20/-12
3331 Hard noise gate at -35 dB:
3333 compand=attacks=0:points=-80/-115|-35.1/-80|-35/-35|20/20
3339 compand=attacks=0:points=-80/-80|-12.4/-12.4|-6/-8|0/-6.8|20/-2.8
3343 @section compensationdelay
3345 Compensation Delay Line is a metric based delay to compensate differing
3346 positions of microphones or speakers.
3348 For example, you have recorded guitar with two microphones placed in
3349 different locations. Because the front of sound wave has fixed speed in
3350 normal conditions, the phasing of microphones can vary and depends on
3351 their location and interposition. The best sound mix can be achieved when
3352 these microphones are in phase (synchronized). Note that a distance of
3353 ~30 cm between microphones makes one microphone capture the signal in
3354 antiphase to the other microphone. That makes the final mix sound moody.
3355 This filter helps to solve phasing problems by adding different delays
3356 to each microphone track and make them synchronized.
3358 The best result can be reached when you take one track as base and
3359 synchronize other tracks one by one with it.
3360 Remember that synchronization/delay tolerance depends on sample rate, too.
3361 Higher sample rates will give more tolerance.
3363 The filter accepts the following parameters:
3367 Set millimeters distance. This is compensation distance for fine tuning.
3371 Set cm distance. This is compensation distance for tightening distance setup.
3375 Set meters distance. This is compensation distance for hard distance setup.
3379 Set dry amount. Amount of unprocessed (dry) signal.
3383 Set wet amount. Amount of processed (wet) signal.
3387 Set temperature in degrees Celsius. This is the temperature of the environment.
3392 Apply headphone crossfeed filter.
3394 Crossfeed is the process of blending the left and right channels of stereo
3396 It is mainly used to reduce extreme stereo separation of low frequencies.
3398 The intent is to produce more speaker like sound to the listener.
3400 The filter accepts the following options:
3404 Set strength of crossfeed. Default is 0.2. Allowed range is from 0 to 1.
3405 This sets gain of low shelf filter for side part of stereo image.
3406 Default is -6dB. Max allowed is -30db when strength is set to 1.
3409 Set soundstage wideness. Default is 0.5. Allowed range is from 0 to 1.
3410 This sets cut off frequency of low shelf filter. Default is cut off near
3411 1550 Hz. With range set to 1 cut off frequency is set to 2100 Hz.
3414 Set curve slope of low shelf filter. Default is 0.5.
3415 Allowed range is from 0.01 to 1.
3418 Set input gain. Default is 0.9.
3421 Set output gain. Default is 1.
3424 @subsection Commands
3426 This filter supports the all above options as @ref{commands}.
3428 @section crystalizer
3429 Simple algorithm to expand audio dynamic range.
3431 The filter accepts the following options:
3435 Sets the intensity of effect (default: 2.0). Must be in range between 0.0
3436 (unchanged sound) to 10.0 (maximum effect).
3439 Enable clipping. By default is enabled.
3442 @subsection Commands
3444 This filter supports the all above options as @ref{commands}.
3447 Apply a DC shift to the audio.
3449 This can be useful to remove a DC offset (caused perhaps by a hardware problem
3450 in the recording chain) from the audio. The effect of a DC offset is reduced
3451 headroom and hence volume. The @ref{astats} filter can be used to determine if
3452 a signal has a DC offset.
3456 Set the DC shift, allowed range is [-1, 1]. It indicates the amount to shift
3460 Optional. It should have a value much less than 1 (e.g. 0.05 or 0.02) and is
3461 used to prevent clipping.
3466 Apply de-essing to the audio samples.
3470 Set intensity for triggering de-essing. Allowed range is from 0 to 1.
3474 Set amount of ducking on treble part of sound. Allowed range is from 0 to 1.
3478 How much of original frequency content to keep when de-essing. Allowed range is from 0 to 1.
3482 Set the output mode.
3484 It accepts the following values:
3487 Pass input unchanged.
3490 Pass ess filtered out.
3495 Default value is @var{o}.
3501 Measure audio dynamic range.
3503 DR values of 14 and higher is found in very dynamic material. DR of 8 to 13
3504 is found in transition material. And anything less that 8 have very poor dynamics
3505 and is very compressed.
3507 The filter accepts the following options:
3511 Set window length in seconds used to split audio into segments of equal length.
3512 Default is 3 seconds.
3516 Dynamic Audio Normalizer.
3518 This filter applies a certain amount of gain to the input audio in order
3519 to bring its peak magnitude to a target level (e.g. 0 dBFS). However, in
3520 contrast to more "simple" normalization algorithms, the Dynamic Audio
3521 Normalizer *dynamically* re-adjusts the gain factor to the input audio.
3522 This allows for applying extra gain to the "quiet" sections of the audio
3523 while avoiding distortions or clipping the "loud" sections. In other words:
3524 The Dynamic Audio Normalizer will "even out" the volume of quiet and loud
3525 sections, in the sense that the volume of each section is brought to the
3526 same target level. Note, however, that the Dynamic Audio Normalizer achieves
3527 this goal *without* applying "dynamic range compressing". It will retain 100%
3528 of the dynamic range *within* each section of the audio file.
3532 Set the frame length in milliseconds. In range from 10 to 8000 milliseconds.
3533 Default is 500 milliseconds.
3534 The Dynamic Audio Normalizer processes the input audio in small chunks,
3535 referred to as frames. This is required, because a peak magnitude has no
3536 meaning for just a single sample value. Instead, we need to determine the
3537 peak magnitude for a contiguous sequence of sample values. While a "standard"
3538 normalizer would simply use the peak magnitude of the complete file, the
3539 Dynamic Audio Normalizer determines the peak magnitude individually for each
3540 frame. The length of a frame is specified in milliseconds. By default, the
3541 Dynamic Audio Normalizer uses a frame length of 500 milliseconds, which has
3542 been found to give good results with most files.
3543 Note that the exact frame length, in number of samples, will be determined
3544 automatically, based on the sampling rate of the individual input audio file.
3547 Set the Gaussian filter window size. In range from 3 to 301, must be odd
3548 number. Default is 31.
3549 Probably the most important parameter of the Dynamic Audio Normalizer is the
3550 @code{window size} of the Gaussian smoothing filter. The filter's window size
3551 is specified in frames, centered around the current frame. For the sake of
3552 simplicity, this must be an odd number. Consequently, the default value of 31
3553 takes into account the current frame, as well as the 15 preceding frames and
3554 the 15 subsequent frames. Using a larger window results in a stronger
3555 smoothing effect and thus in less gain variation, i.e. slower gain
3556 adaptation. Conversely, using a smaller window results in a weaker smoothing
3557 effect and thus in more gain variation, i.e. faster gain adaptation.
3558 In other words, the more you increase this value, the more the Dynamic Audio
3559 Normalizer will behave like a "traditional" normalization filter. On the
3560 contrary, the more you decrease this value, the more the Dynamic Audio
3561 Normalizer will behave like a dynamic range compressor.
3564 Set the target peak value. This specifies the highest permissible magnitude
3565 level for the normalized audio input. This filter will try to approach the
3566 target peak magnitude as closely as possible, but at the same time it also
3567 makes sure that the normalized signal will never exceed the peak magnitude.
3568 A frame's maximum local gain factor is imposed directly by the target peak
3569 magnitude. The default value is 0.95 and thus leaves a headroom of 5%*.
3570 It is not recommended to go above this value.
3573 Set the maximum gain factor. In range from 1.0 to 100.0. Default is 10.0.
3574 The Dynamic Audio Normalizer determines the maximum possible (local) gain
3575 factor for each input frame, i.e. the maximum gain factor that does not
3576 result in clipping or distortion. The maximum gain factor is determined by
3577 the frame's highest magnitude sample. However, the Dynamic Audio Normalizer
3578 additionally bounds the frame's maximum gain factor by a predetermined
3579 (global) maximum gain factor. This is done in order to avoid excessive gain
3580 factors in "silent" or almost silent frames. By default, the maximum gain
3581 factor is 10.0, For most inputs the default value should be sufficient and
3582 it usually is not recommended to increase this value. Though, for input
3583 with an extremely low overall volume level, it may be necessary to allow even
3584 higher gain factors. Note, however, that the Dynamic Audio Normalizer does
3585 not simply apply a "hard" threshold (i.e. cut off values above the threshold).
3586 Instead, a "sigmoid" threshold function will be applied. This way, the
3587 gain factors will smoothly approach the threshold value, but never exceed that
3591 Set the target RMS. In range from 0.0 to 1.0. Default is 0.0 - disabled.
3592 By default, the Dynamic Audio Normalizer performs "peak" normalization.
3593 This means that the maximum local gain factor for each frame is defined
3594 (only) by the frame's highest magnitude sample. This way, the samples can
3595 be amplified as much as possible without exceeding the maximum signal
3596 level, i.e. without clipping. Optionally, however, the Dynamic Audio
3597 Normalizer can also take into account the frame's root mean square,
3598 abbreviated RMS. In electrical engineering, the RMS is commonly used to
3599 determine the power of a time-varying signal. It is therefore considered
3600 that the RMS is a better approximation of the "perceived loudness" than
3601 just looking at the signal's peak magnitude. Consequently, by adjusting all
3602 frames to a constant RMS value, a uniform "perceived loudness" can be
3603 established. If a target RMS value has been specified, a frame's local gain
3604 factor is defined as the factor that would result in exactly that RMS value.
3605 Note, however, that the maximum local gain factor is still restricted by the
3606 frame's highest magnitude sample, in order to prevent clipping.
3609 Enable channels coupling. By default is enabled.
3610 By default, the Dynamic Audio Normalizer will amplify all channels by the same
3611 amount. This means the same gain factor will be applied to all channels, i.e.
3612 the maximum possible gain factor is determined by the "loudest" channel.
3613 However, in some recordings, it may happen that the volume of the different
3614 channels is uneven, e.g. one channel may be "quieter" than the other one(s).
3615 In this case, this option can be used to disable the channel coupling. This way,
3616 the gain factor will be determined independently for each channel, depending
3617 only on the individual channel's highest magnitude sample. This allows for
3618 harmonizing the volume of the different channels.
3621 Enable DC bias correction. By default is disabled.
3622 An audio signal (in the time domain) is a sequence of sample values.
3623 In the Dynamic Audio Normalizer these sample values are represented in the
3624 -1.0 to 1.0 range, regardless of the original input format. Normally, the
3625 audio signal, or "waveform", should be centered around the zero point.
3626 That means if we calculate the mean value of all samples in a file, or in a
3627 single frame, then the result should be 0.0 or at least very close to that
3628 value. If, however, there is a significant deviation of the mean value from
3629 0.0, in either positive or negative direction, this is referred to as a
3630 DC bias or DC offset. Since a DC bias is clearly undesirable, the Dynamic
3631 Audio Normalizer provides optional DC bias correction.
3632 With DC bias correction enabled, the Dynamic Audio Normalizer will determine
3633 the mean value, or "DC correction" offset, of each input frame and subtract
3634 that value from all of the frame's sample values which ensures those samples
3635 are centered around 0.0 again. Also, in order to avoid "gaps" at the frame
3636 boundaries, the DC correction offset values will be interpolated smoothly
3637 between neighbouring frames.
3639 @item altboundary, b
3640 Enable alternative boundary mode. By default is disabled.
3641 The Dynamic Audio Normalizer takes into account a certain neighbourhood
3642 around each frame. This includes the preceding frames as well as the
3643 subsequent frames. However, for the "boundary" frames, located at the very
3644 beginning and at the very end of the audio file, not all neighbouring
3645 frames are available. In particular, for the first few frames in the audio
3646 file, the preceding frames are not known. And, similarly, for the last few
3647 frames in the audio file, the subsequent frames are not known. Thus, the
3648 question arises which gain factors should be assumed for the missing frames
3649 in the "boundary" region. The Dynamic Audio Normalizer implements two modes
3650 to deal with this situation. The default boundary mode assumes a gain factor
3651 of exactly 1.0 for the missing frames, resulting in a smooth "fade in" and
3652 "fade out" at the beginning and at the end of the input, respectively.
3655 Set the compress factor. In range from 0.0 to 30.0. Default is 0.0.
3656 By default, the Dynamic Audio Normalizer does not apply "traditional"
3657 compression. This means that signal peaks will not be pruned and thus the
3658 full dynamic range will be retained within each local neighbourhood. However,
3659 in some cases it may be desirable to combine the Dynamic Audio Normalizer's
3660 normalization algorithm with a more "traditional" compression.
3661 For this purpose, the Dynamic Audio Normalizer provides an optional compression
3662 (thresholding) function. If (and only if) the compression feature is enabled,
3663 all input frames will be processed by a soft knee thresholding function prior
3664 to the actual normalization process. Put simply, the thresholding function is
3665 going to prune all samples whose magnitude exceeds a certain threshold value.
3666 However, the Dynamic Audio Normalizer does not simply apply a fixed threshold
3667 value. Instead, the threshold value will be adjusted for each individual
3669 In general, smaller parameters result in stronger compression, and vice versa.
3670 Values below 3.0 are not recommended, because audible distortion may appear.
3673 Set the target threshold value. This specifies the lowest permissible
3674 magnitude level for the audio input which will be normalized.
3675 If input frame volume is above this value frame will be normalized.
3676 Otherwise frame may not be normalized at all. The default value is set
3677 to 0, which means all input frames will be normalized.
3678 This option is mostly useful if digital noise is not wanted to be amplified.
3681 @subsection Commands
3683 This filter supports the all above options as @ref{commands}.
3687 Make audio easier to listen to on headphones.
3689 This filter adds `cues' to 44.1kHz stereo (i.e. audio CD format) audio
3690 so that when listened to on headphones the stereo image is moved from
3691 inside your head (standard for headphones) to outside and in front of
3692 the listener (standard for speakers).
3698 Apply a two-pole peaking equalisation (EQ) filter. With this
3699 filter, the signal-level at and around a selected frequency can
3700 be increased or decreased, whilst (unlike bandpass and bandreject
3701 filters) that at all other frequencies is unchanged.
3703 In order to produce complex equalisation curves, this filter can
3704 be given several times, each with a different central frequency.
3706 The filter accepts the following options:
3710 Set the filter's central frequency in Hz.
3713 Set method to specify band-width of filter.
3728 Specify the band-width of a filter in width_type units.
3731 Set the required gain or attenuation in dB.
3732 Beware of clipping when using a positive gain.
3735 How much to use filtered signal in output. Default is 1.
3736 Range is between 0 and 1.
3739 Specify which channels to filter, by default all available are filtered.
3742 Normalize biquad coefficients, by default is disabled.
3743 Enabling it will normalize magnitude response at DC to 0dB.
3746 Set transform type of IIR filter.
3755 @subsection Examples
3758 Attenuate 10 dB at 1000 Hz, with a bandwidth of 200 Hz:
3760 equalizer=f=1000:t=h:width=200:g=-10
3764 Apply 2 dB gain at 1000 Hz with Q 1 and attenuate 5 dB at 100 Hz with Q 2:
3766 equalizer=f=1000:t=q:w=1:g=2,equalizer=f=100:t=q:w=2:g=-5
3770 @subsection Commands
3772 This filter supports the following commands:
3775 Change equalizer frequency.
3776 Syntax for the command is : "@var{frequency}"
3779 Change equalizer width_type.
3780 Syntax for the command is : "@var{width_type}"
3783 Change equalizer width.
3784 Syntax for the command is : "@var{width}"
3787 Change equalizer gain.
3788 Syntax for the command is : "@var{gain}"
3791 Change equalizer mix.
3792 Syntax for the command is : "@var{mix}"
3795 @section extrastereo
3797 Linearly increases the difference between left and right channels which
3798 adds some sort of "live" effect to playback.
3800 The filter accepts the following options:
3804 Sets the difference coefficient (default: 2.5). 0.0 means mono sound
3805 (average of both channels), with 1.0 sound will be unchanged, with
3806 -1.0 left and right channels will be swapped.
3809 Enable clipping. By default is enabled.
3812 @subsection Commands
3814 This filter supports the all above options as @ref{commands}.
3816 @section firequalizer
3817 Apply FIR Equalization using arbitrary frequency response.
3819 The filter accepts the following option:
3823 Set gain curve equation (in dB). The expression can contain variables:
3826 the evaluated frequency
3830 channel number, set to 0 when multichannels evaluation is disabled
3832 channel id, see libavutil/channel_layout.h, set to the first channel id when
3833 multichannels evaluation is disabled
3837 channel_layout, see libavutil/channel_layout.h
3842 @item gain_interpolate(f)
3843 interpolate gain on frequency f based on gain_entry
3844 @item cubic_interpolate(f)
3845 same as gain_interpolate, but smoother
3847 This option is also available as command. Default is @code{gain_interpolate(f)}.
3850 Set gain entry for gain_interpolate function. The expression can
3854 store gain entry at frequency f with value g
3856 This option is also available as command.
3859 Set filter delay in seconds. Higher value means more accurate.
3860 Default is @code{0.01}.
3863 Set filter accuracy in Hz. Lower value means more accurate.
3864 Default is @code{5}.
3867 Set window function. Acceptable values are:
3870 rectangular window, useful when gain curve is already smooth
3872 hann window (default)
3878 3-terms continuous 1st derivative nuttall window
3880 minimum 3-terms discontinuous nuttall window
3882 4-terms continuous 1st derivative nuttall window
3884 minimum 4-terms discontinuous nuttall (blackman-nuttall) window
3886 blackman-harris window
3892 If enabled, use fixed number of audio samples. This improves speed when
3893 filtering with large delay. Default is disabled.
3896 Enable multichannels evaluation on gain. Default is disabled.
3899 Enable zero phase mode by subtracting timestamp to compensate delay.
3900 Default is disabled.
3903 Set scale used by gain. Acceptable values are:
3906 linear frequency, linear gain
3908 linear frequency, logarithmic (in dB) gain (default)
3910 logarithmic (in octave scale where 20 Hz is 0) frequency, linear gain
3912 logarithmic frequency, logarithmic gain
3916 Set file for dumping, suitable for gnuplot.
3919 Set scale for dumpfile. Acceptable values are same with scale option.
3923 Enable 2-channel convolution using complex FFT. This improves speed significantly.
3924 Default is disabled.
3927 Enable minimum phase impulse response. Default is disabled.
3930 @subsection Examples
3935 firequalizer=gain='if(lt(f,1000), 0, -INF)'
3938 lowpass at 1000 Hz with gain_entry:
3940 firequalizer=gain_entry='entry(1000,0); entry(1001, -INF)'
3943 custom equalization:
3945 firequalizer=gain_entry='entry(100,0); entry(400, -4); entry(1000, -6); entry(2000, 0)'
3948 higher delay with zero phase to compensate delay:
3950 firequalizer=delay=0.1:fixed=on:zero_phase=on
3953 lowpass on left channel, highpass on right channel:
3955 firequalizer=gain='if(eq(chid,1), gain_interpolate(f), if(eq(chid,2), gain_interpolate(1e6+f), 0))'
3956 :gain_entry='entry(1000, 0); entry(1001,-INF); entry(1e6+1000,0)':multi=on
3961 Apply a flanging effect to the audio.
3963 The filter accepts the following options:
3967 Set base delay in milliseconds. Range from 0 to 30. Default value is 0.
3970 Set added sweep delay in milliseconds. Range from 0 to 10. Default value is 2.
3973 Set percentage regeneration (delayed signal feedback). Range from -95 to 95.
3977 Set percentage of delayed signal mixed with original. Range from 0 to 100.
3978 Default value is 71.
3981 Set sweeps per second (Hz). Range from 0.1 to 10. Default value is 0.5.
3984 Set swept wave shape, can be @var{triangular} or @var{sinusoidal}.
3985 Default value is @var{sinusoidal}.
3988 Set swept wave percentage-shift for multi channel. Range from 0 to 100.
3989 Default value is 25.
3992 Set delay-line interpolation, @var{linear} or @var{quadratic}.
3993 Default is @var{linear}.
3997 Apply Haas effect to audio.
3999 Note that this makes most sense to apply on mono signals.
4000 With this filter applied to mono signals it give some directionality and
4001 stretches its stereo image.
4003 The filter accepts the following options:
4007 Set input level. By default is @var{1}, or 0dB
4010 Set output level. By default is @var{1}, or 0dB.
4013 Set gain applied to side part of signal. By default is @var{1}.
4016 Set kind of middle source. Can be one of the following:
4026 Pick middle part signal of stereo image.
4029 Pick side part signal of stereo image.
4033 Change middle phase. By default is disabled.
4036 Set left channel delay. By default is @var{2.05} milliseconds.
4039 Set left channel balance. By default is @var{-1}.
4042 Set left channel gain. By default is @var{1}.
4045 Change left phase. By default is disabled.
4048 Set right channel delay. By defaults is @var{2.12} milliseconds.
4051 Set right channel balance. By default is @var{1}.
4054 Set right channel gain. By default is @var{1}.
4057 Change right phase. By default is enabled.
4062 Decodes High Definition Compatible Digital (HDCD) data. A 16-bit PCM stream with
4063 embedded HDCD codes is expanded into a 20-bit PCM stream.
4065 The filter supports the Peak Extend and Low-level Gain Adjustment features
4066 of HDCD, and detects the Transient Filter flag.
4069 ffmpeg -i HDCD16.flac -af hdcd OUT24.flac
4072 When using the filter with wav, note the default encoding for wav is 16-bit,
4073 so the resulting 20-bit stream will be truncated back to 16-bit. Use something
4074 like @command{-acodec pcm_s24le} after the filter to get 24-bit PCM output.
4076 ffmpeg -i HDCD16.wav -af hdcd OUT16.wav
4077 ffmpeg -i HDCD16.wav -af hdcd -c:a pcm_s24le OUT24.wav
4080 The filter accepts the following options:
4083 @item disable_autoconvert
4084 Disable any automatic format conversion or resampling in the filter graph.
4086 @item process_stereo
4087 Process the stereo channels together. If target_gain does not match between
4088 channels, consider it invalid and use the last valid target_gain.
4091 Set the code detect timer period in ms.
4094 Always extend peaks above -3dBFS even if PE isn't signaled.
4097 Replace audio with a solid tone and adjust the amplitude to signal some
4098 specific aspect of the decoding process. The output file can be loaded in
4099 an audio editor alongside the original to aid analysis.
4101 @code{analyze_mode=pe:force_pe=true} can be used to see all samples above the PE level.
4108 Gain adjustment level at each sample
4110 Samples where peak extend occurs
4112 Samples where the code detect timer is active
4114 Samples where the target gain does not match between channels
4120 Apply head-related transfer functions (HRTFs) to create virtual
4121 loudspeakers around the user for binaural listening via headphones.
4122 The HRIRs are provided via additional streams, for each channel
4123 one stereo input stream is needed.
4125 The filter accepts the following options:
4129 Set mapping of input streams for convolution.
4130 The argument is a '|'-separated list of channel names in order as they
4131 are given as additional stream inputs for filter.
4132 This also specify number of input streams. Number of input streams
4133 must be not less than number of channels in first stream plus one.
4136 Set gain applied to audio. Value is in dB. Default is 0.
4139 Set processing type. Can be @var{time} or @var{freq}. @var{time} is
4140 processing audio in time domain which is slow.
4141 @var{freq} is processing audio in frequency domain which is fast.
4142 Default is @var{freq}.
4145 Set custom gain for LFE channels. Value is in dB. Default is 0.
4148 Set size of frame in number of samples which will be processed at once.
4149 Default value is @var{1024}. Allowed range is from 1024 to 96000.
4152 Set format of hrir stream.
4153 Default value is @var{stereo}. Alternative value is @var{multich}.
4154 If value is set to @var{stereo}, number of additional streams should
4155 be greater or equal to number of input channels in first input stream.
4156 Also each additional stream should have stereo number of channels.
4157 If value is set to @var{multich}, number of additional streams should
4158 be exactly one. Also number of input channels of additional stream
4159 should be equal or greater than twice number of channels of first input
4163 @subsection Examples
4167 Full example using wav files as coefficients with amovie filters for 7.1 downmix,
4168 each amovie filter use stereo file with IR coefficients as input.
4169 The files give coefficients for each position of virtual loudspeaker:
4172 -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"
4177 Full example using wav files as coefficients with amovie filters for 7.1 downmix,
4178 but now in @var{multich} @var{hrir} format.
4180 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"
4187 Apply a high-pass filter with 3dB point frequency.
4188 The filter can be either single-pole, or double-pole (the default).
4189 The filter roll off at 6dB per pole per octave (20dB per pole per decade).
4191 The filter accepts the following options:
4195 Set frequency in Hz. Default is 3000.
4198 Set number of poles. Default is 2.
4201 Set method to specify band-width of filter.
4216 Specify the band-width of a filter in width_type units.
4217 Applies only to double-pole filter.
4218 The default is 0.707q and gives a Butterworth response.
4221 How much to use filtered signal in output. Default is 1.
4222 Range is between 0 and 1.
4225 Specify which channels to filter, by default all available are filtered.
4228 Normalize biquad coefficients, by default is disabled.
4229 Enabling it will normalize magnitude response at DC to 0dB.
4232 Set transform type of IIR filter.
4241 @subsection Commands
4243 This filter supports the following commands:
4246 Change highpass frequency.
4247 Syntax for the command is : "@var{frequency}"
4250 Change highpass width_type.
4251 Syntax for the command is : "@var{width_type}"
4254 Change highpass width.
4255 Syntax for the command is : "@var{width}"
4258 Change highpass mix.
4259 Syntax for the command is : "@var{mix}"
4264 Join multiple input streams into one multi-channel stream.
4266 It accepts the following parameters:
4270 The number of input streams. It defaults to 2.
4272 @item channel_layout
4273 The desired output channel layout. It defaults to stereo.
4276 Map channels from inputs to output. The argument is a '|'-separated list of
4277 mappings, each in the @code{@var{input_idx}.@var{in_channel}-@var{out_channel}}
4278 form. @var{input_idx} is the 0-based index of the input stream. @var{in_channel}
4279 can be either the name of the input channel (e.g. FL for front left) or its
4280 index in the specified input stream. @var{out_channel} is the name of the output
4284 The filter will attempt to guess the mappings when they are not specified
4285 explicitly. It does so by first trying to find an unused matching input channel
4286 and if that fails it picks the first unused input channel.
4288 Join 3 inputs (with properly set channel layouts):
4290 ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT
4293 Build a 5.1 output from 6 single-channel streams:
4295 ffmpeg -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex
4296 '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'
4302 Load a LADSPA (Linux Audio Developer's Simple Plugin API) plugin.
4304 To enable compilation of this filter you need to configure FFmpeg with
4305 @code{--enable-ladspa}.
4309 Specifies the name of LADSPA plugin library to load. If the environment
4310 variable @env{LADSPA_PATH} is defined, the LADSPA plugin is searched in
4311 each one of the directories specified by the colon separated list in
4312 @env{LADSPA_PATH}, otherwise in the standard LADSPA paths, which are in
4313 this order: @file{HOME/.ladspa/lib/}, @file{/usr/local/lib/ladspa/},
4314 @file{/usr/lib/ladspa/}.
4317 Specifies the plugin within the library. Some libraries contain only
4318 one plugin, but others contain many of them. If this is not set filter
4319 will list all available plugins within the specified library.
4322 Set the '|' separated list of controls which are zero or more floating point
4323 values that determine the behavior of the loaded plugin (for example delay,
4325 Controls need to be defined using the following syntax:
4326 c0=@var{value0}|c1=@var{value1}|c2=@var{value2}|..., where
4327 @var{valuei} is the value set on the @var{i}-th control.
4328 Alternatively they can be also defined using the following syntax:
4329 @var{value0}|@var{value1}|@var{value2}|..., where
4330 @var{valuei} is the value set on the @var{i}-th control.
4331 If @option{controls} is set to @code{help}, all available controls and
4332 their valid ranges are printed.
4334 @item sample_rate, s
4335 Specify the sample rate, default to 44100. Only used if plugin have
4339 Set the number of samples per channel per each output frame, default
4340 is 1024. Only used if plugin have zero inputs.
4343 Set the minimum duration of the sourced audio. See
4344 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
4345 for the accepted syntax.
4346 Note that the resulting duration may be greater than the specified duration,
4347 as the generated audio is always cut at the end of a complete frame.
4348 If not specified, or the expressed duration is negative, the audio is
4349 supposed to be generated forever.
4350 Only used if plugin have zero inputs.
4353 Enable latency compensation, by default is disabled.
4354 Only used if plugin have inputs.
4357 @subsection Examples
4361 List all available plugins within amp (LADSPA example plugin) library:
4367 List all available controls and their valid ranges for @code{vcf_notch}
4368 plugin from @code{VCF} library:
4370 ladspa=f=vcf:p=vcf_notch:c=help
4374 Simulate low quality audio equipment using @code{Computer Music Toolkit} (CMT)
4377 ladspa=file=cmt:plugin=lofi:controls=c0=22|c1=12|c2=12
4381 Add reverberation to the audio using TAP-plugins
4382 (Tom's Audio Processing plugins):
4384 ladspa=file=tap_reverb:tap_reverb
4388 Generate white noise, with 0.2 amplitude:
4390 ladspa=file=cmt:noise_source_white:c=c0=.2
4394 Generate 20 bpm clicks using plugin @code{C* Click - Metronome} from the
4395 @code{C* Audio Plugin Suite} (CAPS) library:
4397 ladspa=file=caps:Click:c=c1=20'
4401 Apply @code{C* Eq10X2 - Stereo 10-band equaliser} effect:
4403 ladspa=caps:Eq10X2:c=c0=-48|c9=-24|c3=12|c4=2
4407 Increase volume by 20dB using fast lookahead limiter from Steve Harris
4408 @code{SWH Plugins} collection:
4410 ladspa=fast_lookahead_limiter_1913:fastLookaheadLimiter:20|0|2
4414 Attenuate low frequencies using Multiband EQ from Steve Harris
4415 @code{SWH Plugins} collection:
4417 ladspa=mbeq_1197:mbeq:-24|-24|-24|0|0|0|0|0|0|0|0|0|0|0|0
4421 Reduce stereo image using @code{Narrower} from the @code{C* Audio Plugin Suite}
4424 ladspa=caps:Narrower
4428 Another white noise, now using @code{C* Audio Plugin Suite} (CAPS) library:
4430 ladspa=caps:White:.2
4434 Some fractal noise, using @code{C* Audio Plugin Suite} (CAPS) library:
4436 ladspa=caps:Fractal:c=c1=1
4440 Dynamic volume normalization using @code{VLevel} plugin:
4442 ladspa=vlevel-ladspa:vlevel_mono
4446 @subsection Commands
4448 This filter supports the following commands:
4451 Modify the @var{N}-th control value.
4453 If the specified value is not valid, it is ignored and prior one is kept.
4458 EBU R128 loudness normalization. Includes both dynamic and linear normalization modes.
4459 Support for both single pass (livestreams, files) and double pass (files) modes.
4460 This algorithm can target IL, LRA, and maximum true peak. In dynamic mode, to accurately
4461 detect true peaks, the audio stream will be upsampled to 192 kHz.
4462 Use the @code{-ar} option or @code{aresample} filter to explicitly set an output sample rate.
4464 The filter accepts the following options:
4468 Set integrated loudness target.
4469 Range is -70.0 - -5.0. Default value is -24.0.
4472 Set loudness range target.
4473 Range is 1.0 - 20.0. Default value is 7.0.
4476 Set maximum true peak.
4477 Range is -9.0 - +0.0. Default value is -2.0.
4479 @item measured_I, measured_i
4480 Measured IL of input file.
4481 Range is -99.0 - +0.0.
4483 @item measured_LRA, measured_lra
4484 Measured LRA of input file.
4485 Range is 0.0 - 99.0.
4487 @item measured_TP, measured_tp
4488 Measured true peak of input file.
4489 Range is -99.0 - +99.0.
4491 @item measured_thresh
4492 Measured threshold of input file.
4493 Range is -99.0 - +0.0.
4496 Set offset gain. Gain is applied before the true-peak limiter.
4497 Range is -99.0 - +99.0. Default is +0.0.
4500 Normalize by linearly scaling the source audio.
4501 @code{measured_I}, @code{measured_LRA}, @code{measured_TP},
4502 and @code{measured_thresh} must all be specified. Target LRA shouldn't
4503 be lower than source LRA and the change in integrated loudness shouldn't
4504 result in a true peak which exceeds the target TP. If any of these
4505 conditions aren't met, normalization mode will revert to @var{dynamic}.
4506 Options are @code{true} or @code{false}. Default is @code{true}.
4509 Treat mono input files as "dual-mono". If a mono file is intended for playback
4510 on a stereo system, its EBU R128 measurement will be perceptually incorrect.
4511 If set to @code{true}, this option will compensate for this effect.
4512 Multi-channel input files are not affected by this option.
4513 Options are true or false. Default is false.
4516 Set print format for stats. Options are summary, json, or none.
4517 Default value is none.
4522 Apply a low-pass filter with 3dB point frequency.
4523 The filter can be either single-pole or double-pole (the default).
4524 The filter roll off at 6dB per pole per octave (20dB per pole per decade).
4526 The filter accepts the following options:
4530 Set frequency in Hz. Default is 500.
4533 Set number of poles. Default is 2.
4536 Set method to specify band-width of filter.
4551 Specify the band-width of a filter in width_type units.
4552 Applies only to double-pole filter.
4553 The default is 0.707q and gives a Butterworth response.
4556 How much to use filtered signal in output. Default is 1.
4557 Range is between 0 and 1.
4560 Specify which channels to filter, by default all available are filtered.
4563 Normalize biquad coefficients, by default is disabled.
4564 Enabling it will normalize magnitude response at DC to 0dB.
4567 Set transform type of IIR filter.
4576 @subsection Examples
4579 Lowpass only LFE channel, it LFE is not present it does nothing:
4585 @subsection Commands
4587 This filter supports the following commands:
4590 Change lowpass frequency.
4591 Syntax for the command is : "@var{frequency}"
4594 Change lowpass width_type.
4595 Syntax for the command is : "@var{width_type}"
4598 Change lowpass width.
4599 Syntax for the command is : "@var{width}"
4603 Syntax for the command is : "@var{mix}"
4608 Load a LV2 (LADSPA Version 2) plugin.
4610 To enable compilation of this filter you need to configure FFmpeg with
4611 @code{--enable-lv2}.
4615 Specifies the plugin URI. You may need to escape ':'.
4618 Set the '|' separated list of controls which are zero or more floating point
4619 values that determine the behavior of the loaded plugin (for example delay,
4621 If @option{controls} is set to @code{help}, all available controls and
4622 their valid ranges are printed.
4624 @item sample_rate, s
4625 Specify the sample rate, default to 44100. Only used if plugin have
4629 Set the number of samples per channel per each output frame, default
4630 is 1024. Only used if plugin have zero inputs.
4633 Set the minimum duration of the sourced audio. See
4634 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
4635 for the accepted syntax.
4636 Note that the resulting duration may be greater than the specified duration,
4637 as the generated audio is always cut at the end of a complete frame.
4638 If not specified, or the expressed duration is negative, the audio is
4639 supposed to be generated forever.
4640 Only used if plugin have zero inputs.
4643 @subsection Examples
4647 Apply bass enhancer plugin from Calf:
4649 lv2=p=http\\\\://calf.sourceforge.net/plugins/BassEnhancer:c=amount=2
4653 Apply vinyl plugin from Calf:
4655 lv2=p=http\\\\://calf.sourceforge.net/plugins/Vinyl:c=drone=0.2|aging=0.5
4659 Apply bit crusher plugin from ArtyFX:
4661 lv2=p=http\\\\://www.openavproductions.com/artyfx#bitta:c=crush=0.3
4666 Multiband Compress or expand the audio's dynamic range.
4668 The input audio is divided into bands using 4th order Linkwitz-Riley IIRs.
4669 This is akin to the crossover of a loudspeaker, and results in flat frequency
4670 response when absent compander action.
4672 It accepts the following parameters:
4676 This option syntax is:
4677 attack,decay,[attack,decay..] soft-knee points crossover_frequency [delay [initial_volume [gain]]] | attack,decay ...
4678 For explanation of each item refer to compand filter documentation.
4684 Mix channels with specific gain levels. The filter accepts the output
4685 channel layout followed by a set of channels definitions.
4687 This filter is also designed to efficiently remap the channels of an audio
4690 The filter accepts parameters of the form:
4691 "@var{l}|@var{outdef}|@var{outdef}|..."
4695 output channel layout or number of channels
4698 output channel specification, of the form:
4699 "@var{out_name}=[@var{gain}*]@var{in_name}[(+-)[@var{gain}*]@var{in_name}...]"
4702 output channel to define, either a channel name (FL, FR, etc.) or a channel
4703 number (c0, c1, etc.)
4706 multiplicative coefficient for the channel, 1 leaving the volume unchanged
4709 input channel to use, see out_name for details; it is not possible to mix
4710 named and numbered input channels
4713 If the `=' in a channel specification is replaced by `<', then the gains for
4714 that specification will be renormalized so that the total is 1, thus
4715 avoiding clipping noise.
4717 @subsection Mixing examples
4719 For example, if you want to down-mix from stereo to mono, but with a bigger
4720 factor for the left channel:
4722 pan=1c|c0=0.9*c0+0.1*c1
4725 A customized down-mix to stereo that works automatically for 3-, 4-, 5- and
4726 7-channels surround:
4728 pan=stereo| FL < FL + 0.5*FC + 0.6*BL + 0.6*SL | FR < FR + 0.5*FC + 0.6*BR + 0.6*SR
4731 Note that @command{ffmpeg} integrates a default down-mix (and up-mix) system
4732 that should be preferred (see "-ac" option) unless you have very specific
4735 @subsection Remapping examples
4737 The channel remapping will be effective if, and only if:
4740 @item gain coefficients are zeroes or ones,
4741 @item only one input per channel output,
4744 If all these conditions are satisfied, the filter will notify the user ("Pure
4745 channel mapping detected"), and use an optimized and lossless method to do the
4748 For example, if you have a 5.1 source and want a stereo audio stream by
4749 dropping the extra channels:
4751 pan="stereo| c0=FL | c1=FR"
4754 Given the same source, you can also switch front left and front right channels
4755 and keep the input channel layout:
4757 pan="5.1| c0=c1 | c1=c0 | c2=c2 | c3=c3 | c4=c4 | c5=c5"
4760 If the input is a stereo audio stream, you can mute the front left channel (and
4761 still keep the stereo channel layout) with:
4766 Still with a stereo audio stream input, you can copy the right channel in both
4767 front left and right:
4769 pan="stereo| c0=FR | c1=FR"
4774 ReplayGain scanner filter. This filter takes an audio stream as an input and
4775 outputs it unchanged.
4776 At end of filtering it displays @code{track_gain} and @code{track_peak}.
4780 Convert the audio sample format, sample rate and channel layout. It is
4781 not meant to be used directly.
4784 Apply time-stretching and pitch-shifting with librubberband.
4786 To enable compilation of this filter, you need to configure FFmpeg with
4787 @code{--enable-librubberband}.
4789 The filter accepts the following options:
4793 Set tempo scale factor.
4796 Set pitch scale factor.
4799 Set transients detector.
4800 Possible values are:
4809 Possible values are:
4818 Possible values are:
4825 Set processing window size.
4826 Possible values are:
4835 Possible values are:
4842 Enable formant preservation when shift pitching.
4843 Possible values are:
4851 Possible values are:
4860 Possible values are:
4867 @subsection Commands
4869 This filter supports the following commands:
4872 Change filter tempo scale factor.
4873 Syntax for the command is : "@var{tempo}"
4876 Change filter pitch scale factor.
4877 Syntax for the command is : "@var{pitch}"
4880 @section sidechaincompress
4882 This filter acts like normal compressor but has the ability to compress
4883 detected signal using second input signal.
4884 It needs two input streams and returns one output stream.
4885 First input stream will be processed depending on second stream signal.
4886 The filtered signal then can be filtered with other filters in later stages of
4887 processing. See @ref{pan} and @ref{amerge} filter.
4889 The filter accepts the following options:
4893 Set input gain. Default is 1. Range is between 0.015625 and 64.
4896 Set mode of compressor operation. Can be @code{upward} or @code{downward}.
4897 Default is @code{downward}.
4900 If a signal of second stream raises above this level it will affect the gain
4901 reduction of first stream.
4902 By default is 0.125. Range is between 0.00097563 and 1.
4905 Set a ratio about which the signal is reduced. 1:2 means that if the level
4906 raised 4dB above the threshold, it will be only 2dB above after the reduction.
4907 Default is 2. Range is between 1 and 20.
4910 Amount of milliseconds the signal has to rise above the threshold before gain
4911 reduction starts. Default is 20. Range is between 0.01 and 2000.
4914 Amount of milliseconds the signal has to fall below the threshold before
4915 reduction is decreased again. Default is 250. Range is between 0.01 and 9000.
4918 Set the amount by how much signal will be amplified after processing.
4919 Default is 1. Range is from 1 to 64.
4922 Curve the sharp knee around the threshold to enter gain reduction more softly.
4923 Default is 2.82843. Range is between 1 and 8.
4926 Choose if the @code{average} level between all channels of side-chain stream
4927 or the louder(@code{maximum}) channel of side-chain stream affects the
4928 reduction. Default is @code{average}.
4931 Should the exact signal be taken in case of @code{peak} or an RMS one in case
4932 of @code{rms}. Default is @code{rms} which is mainly smoother.
4935 Set sidechain gain. Default is 1. Range is between 0.015625 and 64.
4938 How much to use compressed signal in output. Default is 1.
4939 Range is between 0 and 1.
4942 @subsection Commands
4944 This filter supports the all above options as @ref{commands}.
4946 @subsection Examples
4950 Full ffmpeg example taking 2 audio inputs, 1st input to be compressed
4951 depending on the signal of 2nd input and later compressed signal to be
4952 merged with 2nd input:
4954 ffmpeg -i main.flac -i sidechain.flac -filter_complex "[1:a]asplit=2[sc][mix];[0:a][sc]sidechaincompress[compr];[compr][mix]amerge"
4958 @section sidechaingate
4960 A sidechain gate acts like a normal (wideband) gate but has the ability to
4961 filter the detected signal before sending it to the gain reduction stage.
4962 Normally a gate uses the full range signal to detect a level above the
4964 For example: If you cut all lower frequencies from your sidechain signal
4965 the gate will decrease the volume of your track only if not enough highs
4966 appear. With this technique you are able to reduce the resonation of a
4967 natural drum or remove "rumbling" of muted strokes from a heavily distorted
4969 It needs two input streams and returns one output stream.
4970 First input stream will be processed depending on second stream signal.
4972 The filter accepts the following options:
4976 Set input level before filtering.
4977 Default is 1. Allowed range is from 0.015625 to 64.
4980 Set the mode of operation. Can be @code{upward} or @code{downward}.
4981 Default is @code{downward}. If set to @code{upward} mode, higher parts of signal
4982 will be amplified, expanding dynamic range in upward direction.
4983 Otherwise, in case of @code{downward} lower parts of signal will be reduced.
4986 Set the level of gain reduction when the signal is below the threshold.
4987 Default is 0.06125. Allowed range is from 0 to 1.
4988 Setting this to 0 disables reduction and then filter behaves like expander.
4991 If a signal rises above this level the gain reduction is released.
4992 Default is 0.125. Allowed range is from 0 to 1.
4995 Set a ratio about which the signal is reduced.
4996 Default is 2. Allowed range is from 1 to 9000.
4999 Amount of milliseconds the signal has to rise above the threshold before gain
5001 Default is 20 milliseconds. Allowed range is from 0.01 to 9000.
5004 Amount of milliseconds the signal has to fall below the threshold before the
5005 reduction is increased again. Default is 250 milliseconds.
5006 Allowed range is from 0.01 to 9000.
5009 Set amount of amplification of signal after processing.
5010 Default is 1. Allowed range is from 1 to 64.
5013 Curve the sharp knee around the threshold to enter gain reduction more softly.
5014 Default is 2.828427125. Allowed range is from 1 to 8.
5017 Choose if exact signal should be taken for detection or an RMS like one.
5018 Default is rms. Can be peak or rms.
5021 Choose if the average level between all channels or the louder channel affects
5023 Default is average. Can be average or maximum.
5026 Set sidechain gain. Default is 1. Range is from 0.015625 to 64.
5029 @section silencedetect
5031 Detect silence in an audio stream.
5033 This filter logs a message when it detects that the input audio volume is less
5034 or equal to a noise tolerance value for a duration greater or equal to the
5035 minimum detected noise duration.
5037 The printed times and duration are expressed in seconds. The
5038 @code{lavfi.silence_start} or @code{lavfi.silence_start.X} metadata key
5039 is set on the first frame whose timestamp equals or exceeds the detection
5040 duration and it contains the timestamp of the first frame of the silence.
5042 The @code{lavfi.silence_duration} or @code{lavfi.silence_duration.X}
5043 and @code{lavfi.silence_end} or @code{lavfi.silence_end.X} metadata
5044 keys are set on the first frame after the silence. If @option{mono} is
5045 enabled, and each channel is evaluated separately, the @code{.X}
5046 suffixed keys are used, and @code{X} corresponds to the channel number.
5048 The filter accepts the following options:
5052 Set noise tolerance. Can be specified in dB (in case "dB" is appended to the
5053 specified value) or amplitude ratio. Default is -60dB, or 0.001.
5056 Set silence duration until notification (default is 2 seconds). See
5057 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
5058 for the accepted syntax.
5061 Process each channel separately, instead of combined. By default is disabled.
5064 @subsection Examples
5068 Detect 5 seconds of silence with -50dB noise tolerance:
5070 silencedetect=n=-50dB:d=5
5074 Complete example with @command{ffmpeg} to detect silence with 0.0001 noise
5075 tolerance in @file{silence.mp3}:
5077 ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null -
5081 @section silenceremove
5083 Remove silence from the beginning, middle or end of the audio.
5085 The filter accepts the following options:
5089 This value is used to indicate if audio should be trimmed at beginning of
5090 the audio. A value of zero indicates no silence should be trimmed from the
5091 beginning. When specifying a non-zero value, it trims audio up until it
5092 finds non-silence. Normally, when trimming silence from beginning of audio
5093 the @var{start_periods} will be @code{1} but it can be increased to higher
5094 values to trim all audio up to specific count of non-silence periods.
5095 Default value is @code{0}.
5097 @item start_duration
5098 Specify the amount of time that non-silence must be detected before it stops
5099 trimming audio. By increasing the duration, bursts of noises can be treated
5100 as silence and trimmed off. Default value is @code{0}.
5102 @item start_threshold
5103 This indicates what sample value should be treated as silence. For digital
5104 audio, a value of @code{0} may be fine but for audio recorded from analog,
5105 you may wish to increase the value to account for background noise.
5106 Can be specified in dB (in case "dB" is appended to the specified value)
5107 or amplitude ratio. Default value is @code{0}.
5110 Specify max duration of silence at beginning that will be kept after
5111 trimming. Default is 0, which is equal to trimming all samples detected
5115 Specify mode of detection of silence end in start of multi-channel audio.
5116 Can be @var{any} or @var{all}. Default is @var{any}.
5117 With @var{any}, any sample that is detected as non-silence will cause
5118 stopped trimming of silence.
5119 With @var{all}, only if all channels are detected as non-silence will cause
5120 stopped trimming of silence.
5123 Set the count for trimming silence from the end of audio.
5124 To remove silence from the middle of a file, specify a @var{stop_periods}
5125 that is negative. This value is then treated as a positive value and is
5126 used to indicate the effect should restart processing as specified by
5127 @var{start_periods}, making it suitable for removing periods of silence
5128 in the middle of the audio.
5129 Default value is @code{0}.
5132 Specify a duration of silence that must exist before audio is not copied any
5133 more. By specifying a higher duration, silence that is wanted can be left in
5135 Default value is @code{0}.
5137 @item stop_threshold
5138 This is the same as @option{start_threshold} but for trimming silence from
5140 Can be specified in dB (in case "dB" is appended to the specified value)
5141 or amplitude ratio. Default value is @code{0}.
5144 Specify max duration of silence at end that will be kept after
5145 trimming. Default is 0, which is equal to trimming all samples detected
5149 Specify mode of detection of silence start in end of multi-channel audio.
5150 Can be @var{any} or @var{all}. Default is @var{any}.
5151 With @var{any}, any sample that is detected as non-silence will cause
5152 stopped trimming of silence.
5153 With @var{all}, only if all channels are detected as non-silence will cause
5154 stopped trimming of silence.
5157 Set how is silence detected. Can be @code{rms} or @code{peak}. Second is faster
5158 and works better with digital silence which is exactly 0.
5159 Default value is @code{rms}.
5162 Set duration in number of seconds used to calculate size of window in number
5163 of samples for detecting silence.
5164 Default value is @code{0.02}. Allowed range is from @code{0} to @code{10}.
5167 @subsection Examples
5171 The following example shows how this filter can be used to start a recording
5172 that does not contain the delay at the start which usually occurs between
5173 pressing the record button and the start of the performance:
5175 silenceremove=start_periods=1:start_duration=5:start_threshold=0.02
5179 Trim all silence encountered from beginning to end where there is more than 1
5180 second of silence in audio:
5182 silenceremove=stop_periods=-1:stop_duration=1:stop_threshold=-90dB
5186 Trim all digital silence samples, using peak detection, from beginning to end
5187 where there is more than 0 samples of digital silence in audio and digital
5188 silence is detected in all channels at same positions in stream:
5190 silenceremove=window=0:detection=peak:stop_mode=all:start_mode=all:stop_periods=-1:stop_threshold=0
5196 SOFAlizer uses head-related transfer functions (HRTFs) to create virtual
5197 loudspeakers around the user for binaural listening via headphones (audio
5198 formats up to 9 channels supported).
5199 The HRTFs are stored in SOFA files (see @url{http://www.sofacoustics.org/} for a database).
5200 SOFAlizer is developed at the Acoustics Research Institute (ARI) of the
5201 Austrian Academy of Sciences.
5203 To enable compilation of this filter you need to configure FFmpeg with
5204 @code{--enable-libmysofa}.
5206 The filter accepts the following options:
5210 Set the SOFA file used for rendering.
5213 Set gain applied to audio. Value is in dB. Default is 0.
5216 Set rotation of virtual loudspeakers in deg. Default is 0.
5219 Set elevation of virtual speakers in deg. Default is 0.
5222 Set distance in meters between loudspeakers and the listener with near-field
5223 HRTFs. Default is 1.
5226 Set processing type. Can be @var{time} or @var{freq}. @var{time} is
5227 processing audio in time domain which is slow.
5228 @var{freq} is processing audio in frequency domain which is fast.
5229 Default is @var{freq}.
5232 Set custom positions of virtual loudspeakers. Syntax for this option is:
5233 <CH> <AZIM> <ELEV>[|<CH> <AZIM> <ELEV>|...].
5234 Each virtual loudspeaker is described with short channel name following with
5235 azimuth and elevation in degrees.
5236 Each virtual loudspeaker description is separated by '|'.
5237 For example to override front left and front right channel positions use:
5238 'speakers=FL 45 15|FR 345 15'.
5239 Descriptions with unrecognised channel names are ignored.
5242 Set custom gain for LFE channels. Value is in dB. Default is 0.
5245 Set custom frame size in number of samples. Default is 1024.
5246 Allowed range is from 1024 to 96000. Only used if option @samp{type}
5247 is set to @var{freq}.
5250 Should all IRs be normalized upon importing SOFA file.
5251 By default is enabled.
5254 Should nearest IRs be interpolated with neighbor IRs if exact position
5255 does not match. By default is disabled.
5258 Minphase all IRs upon loading of SOFA file. By default is disabled.
5261 Set neighbor search angle step. Only used if option @var{interpolate} is enabled.
5264 Set neighbor search radius step. Only used if option @var{interpolate} is enabled.
5267 @subsection Examples
5271 Using ClubFritz6 sofa file:
5273 sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=1
5277 Using ClubFritz12 sofa file and bigger radius with small rotation:
5279 sofalizer=sofa=/path/to/ClubFritz12.sofa:type=freq:radius=2:rotation=5
5283 Similar as above but with custom speaker positions for front left, front right, back left and back right
5284 and also with custom gain:
5286 "sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=2:speakers=FL 45|FR 315|BL 135|BR 225:gain=28"
5293 This filter expands or compresses each half-cycle of audio samples
5294 (local set of samples all above or all below zero and between two nearest zero crossings) depending
5295 on threshold value, so audio reaches target peak value under conditions controlled by below options.
5297 The filter accepts the following options:
5301 Set the expansion target peak value. This specifies the highest allowed absolute amplitude
5302 level for the normalized audio input. Default value is 0.95. Allowed range is from 0.0 to 1.0.
5305 Set the maximum expansion factor. Allowed range is from 1.0 to 50.0. Default value is 2.0.
5306 This option controls maximum local half-cycle of samples expansion. The maximum expansion
5307 would be such that local peak value reaches target peak value but never to surpass it and that
5308 ratio between new and previous peak value does not surpass this option value.
5310 @item compression, c
5311 Set the maximum compression factor. Allowed range is from 1.0 to 50.0. Default value is 2.0.
5312 This option controls maximum local half-cycle of samples compression. This option is used
5313 only if @option{threshold} option is set to value greater than 0.0, then in such cases
5314 when local peak is lower or same as value set by @option{threshold} all samples belonging to
5315 that peak's half-cycle will be compressed by current compression factor.
5318 Set the threshold value. Default value is 0.0. Allowed range is from 0.0 to 1.0.
5319 This option specifies which half-cycles of samples will be compressed and which will be expanded.
5320 Any half-cycle samples with their local peak value below or same as this option value will be
5321 compressed by current compression factor, otherwise, if greater than threshold value they will be
5322 expanded with expansion factor so that it could reach peak target value but never surpass it.
5325 Set the expansion raising amount per each half-cycle of samples. Default value is 0.001.
5326 Allowed range is from 0.0 to 1.0. This controls how fast expansion factor is raised per
5327 each new half-cycle until it reaches @option{expansion} value.
5328 Setting this options too high may lead to distortions.
5331 Set the compression raising amount per each half-cycle of samples. Default value is 0.001.
5332 Allowed range is from 0.0 to 1.0. This controls how fast compression factor is raised per
5333 each new half-cycle until it reaches @option{compression} value.
5336 Specify which channels to filter, by default all available channels are filtered.
5339 Enable inverted filtering, by default is disabled. This inverts interpretation of @option{threshold}
5340 option. When enabled any half-cycle of samples with their local peak value below or same as
5341 @option{threshold} option will be expanded otherwise it will be compressed.
5344 Link channels when calculating gain applied to each filtered channel sample, by default is disabled.
5345 When disabled each filtered channel gain calculation is independent, otherwise when this option
5346 is enabled the minimum of all possible gains for each filtered channel is used.
5349 @subsection Commands
5351 This filter supports the all above options as @ref{commands}.
5353 @section stereotools
5355 This filter has some handy utilities to manage stereo signals, for converting
5356 M/S stereo recordings to L/R signal while having control over the parameters
5357 or spreading the stereo image of master track.
5359 The filter accepts the following options:
5363 Set input level before filtering for both channels. Defaults is 1.
5364 Allowed range is from 0.015625 to 64.
5367 Set output level after filtering for both channels. Defaults is 1.
5368 Allowed range is from 0.015625 to 64.
5371 Set input balance between both channels. Default is 0.
5372 Allowed range is from -1 to 1.
5375 Set output balance between both channels. Default is 0.
5376 Allowed range is from -1 to 1.
5379 Enable softclipping. Results in analog distortion instead of harsh digital 0dB
5380 clipping. Disabled by default.
5383 Mute the left channel. Disabled by default.
5386 Mute the right channel. Disabled by default.
5389 Change the phase of the left channel. Disabled by default.
5392 Change the phase of the right channel. Disabled by default.
5395 Set stereo mode. Available values are:
5399 Left/Right to Left/Right, this is default.
5402 Left/Right to Mid/Side.
5405 Mid/Side to Left/Right.
5408 Left/Right to Left/Left.
5411 Left/Right to Right/Right.
5414 Left/Right to Left + Right.
5417 Left/Right to Right/Left.
5420 Mid/Side to Left/Left.
5423 Mid/Side to Right/Right.
5427 Set level of side signal. Default is 1.
5428 Allowed range is from 0.015625 to 64.
5431 Set balance of side signal. Default is 0.
5432 Allowed range is from -1 to 1.
5435 Set level of the middle signal. Default is 1.
5436 Allowed range is from 0.015625 to 64.
5439 Set middle signal pan. Default is 0. Allowed range is from -1 to 1.
5442 Set stereo base between mono and inversed channels. Default is 0.
5443 Allowed range is from -1 to 1.
5446 Set delay in milliseconds how much to delay left from right channel and
5447 vice versa. Default is 0. Allowed range is from -20 to 20.
5450 Set S/C level. Default is 1. Allowed range is from 1 to 100.
5453 Set the stereo phase in degrees. Default is 0. Allowed range is from 0 to 360.
5455 @item bmode_in, bmode_out
5456 Set balance mode for balance_in/balance_out option.
5458 Can be one of the following:
5462 Classic balance mode. Attenuate one channel at time.
5463 Gain is raised up to 1.
5466 Similar as classic mode above but gain is raised up to 2.
5469 Equal power distribution, from -6dB to +6dB range.
5473 @subsection Examples
5477 Apply karaoke like effect:
5479 stereotools=mlev=0.015625
5483 Convert M/S signal to L/R:
5485 "stereotools=mode=ms>lr"
5489 @section stereowiden
5491 This filter enhance the stereo effect by suppressing signal common to both
5492 channels and by delaying the signal of left into right and vice versa,
5493 thereby widening the stereo effect.
5495 The filter accepts the following options:
5499 Time in milliseconds of the delay of left signal into right and vice versa.
5500 Default is 20 milliseconds.
5503 Amount of gain in delayed signal into right and vice versa. Gives a delay
5504 effect of left signal in right output and vice versa which gives widening
5505 effect. Default is 0.3.
5508 Cross feed of left into right with inverted phase. This helps in suppressing
5509 the mono. If the value is 1 it will cancel all the signal common to both
5510 channels. Default is 0.3.
5513 Set level of input signal of original channel. Default is 0.8.
5516 @subsection Commands
5518 This filter supports the all above options except @code{delay} as @ref{commands}.
5520 @section superequalizer
5521 Apply 18 band equalizer.
5523 The filter accepts the following options:
5530 Set 131Hz band gain.
5532 Set 185Hz band gain.
5534 Set 262Hz band gain.
5536 Set 370Hz band gain.
5538 Set 523Hz band gain.
5540 Set 740Hz band gain.
5542 Set 1047Hz band gain.
5544 Set 1480Hz band gain.
5546 Set 2093Hz band gain.
5548 Set 2960Hz band gain.
5550 Set 4186Hz band gain.
5552 Set 5920Hz band gain.
5554 Set 8372Hz band gain.
5556 Set 11840Hz band gain.
5558 Set 16744Hz band gain.
5560 Set 20000Hz band gain.
5564 Apply audio surround upmix filter.
5566 This filter allows to produce multichannel output from audio stream.
5568 The filter accepts the following options:
5572 Set output channel layout. By default, this is @var{5.1}.
5574 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
5575 for the required syntax.
5578 Set input channel layout. By default, this is @var{stereo}.
5580 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
5581 for the required syntax.
5584 Set input volume level. By default, this is @var{1}.
5587 Set output volume level. By default, this is @var{1}.
5590 Enable LFE channel output if output channel layout has it. By default, this is enabled.
5593 Set LFE low cut off frequency. By default, this is @var{128} Hz.
5596 Set LFE high cut off frequency. By default, this is @var{256} Hz.
5599 Set LFE mode, can be @var{add} or @var{sub}. Default is @var{add}.
5600 In @var{add} mode, LFE channel is created from input audio and added to output.
5601 In @var{sub} mode, LFE channel is created from input audio and added to output but
5602 also all non-LFE output channels are subtracted with output LFE channel.
5605 Set angle of stereo surround transform, Allowed range is from @var{0} to @var{360}.
5606 Default is @var{90}.
5609 Set front center input volume. By default, this is @var{1}.
5612 Set front center output volume. By default, this is @var{1}.
5615 Set front left input volume. By default, this is @var{1}.
5618 Set front left output volume. By default, this is @var{1}.
5621 Set front right input volume. By default, this is @var{1}.
5624 Set front right output volume. By default, this is @var{1}.
5627 Set side left input volume. By default, this is @var{1}.
5630 Set side left output volume. By default, this is @var{1}.
5633 Set side right input volume. By default, this is @var{1}.
5636 Set side right output volume. By default, this is @var{1}.
5639 Set back left input volume. By default, this is @var{1}.
5642 Set back left output volume. By default, this is @var{1}.
5645 Set back right input volume. By default, this is @var{1}.
5648 Set back right output volume. By default, this is @var{1}.
5651 Set back center input volume. By default, this is @var{1}.
5654 Set back center output volume. By default, this is @var{1}.
5657 Set LFE input volume. By default, this is @var{1}.
5660 Set LFE output volume. By default, this is @var{1}.
5663 Set spread usage of stereo image across X axis for all channels.
5666 Set spread usage of stereo image across Y axis for all channels.
5668 @item fcx, flx, frx, blx, brx, slx, srx, bcx
5669 Set spread usage of stereo image across X axis for each channel.
5671 @item fcy, fly, fry, bly, bry, sly, sry, bcy
5672 Set spread usage of stereo image across Y axis for each channel.
5675 Set window size. Allowed range is from @var{1024} to @var{65536}. Default size is @var{4096}.
5678 Set window function.
5680 It accepts the following values:
5703 Default is @code{hann}.
5706 Set window overlap. If set to 1, the recommended overlap for selected
5707 window function will be picked. Default is @code{0.5}.
5710 @section treble, highshelf
5712 Boost or cut treble (upper) frequencies of the audio using a two-pole
5713 shelving filter with a response similar to that of a standard
5714 hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
5716 The filter accepts the following options:
5720 Give the gain at whichever is the lower of ~22 kHz and the
5721 Nyquist frequency. Its useful range is about -20 (for a large cut)
5722 to +20 (for a large boost). Beware of clipping when using a positive gain.
5725 Set the filter's central frequency and so can be used
5726 to extend or reduce the frequency range to be boosted or cut.
5727 The default value is @code{3000} Hz.
5730 Set method to specify band-width of filter.
5745 Determine how steep is the filter's shelf transition.
5748 How much to use filtered signal in output. Default is 1.
5749 Range is between 0 and 1.
5752 Specify which channels to filter, by default all available are filtered.
5755 Normalize biquad coefficients, by default is disabled.
5756 Enabling it will normalize magnitude response at DC to 0dB.
5759 Set transform type of IIR filter.
5768 @subsection Commands
5770 This filter supports the following commands:
5773 Change treble frequency.
5774 Syntax for the command is : "@var{frequency}"
5777 Change treble width_type.
5778 Syntax for the command is : "@var{width_type}"
5781 Change treble width.
5782 Syntax for the command is : "@var{width}"
5786 Syntax for the command is : "@var{gain}"
5790 Syntax for the command is : "@var{mix}"
5795 Sinusoidal amplitude modulation.
5797 The filter accepts the following options:
5801 Modulation frequency in Hertz. Modulation frequencies in the subharmonic range
5802 (20 Hz or lower) will result in a tremolo effect.
5803 This filter may also be used as a ring modulator by specifying
5804 a modulation frequency higher than 20 Hz.
5805 Range is 0.1 - 20000.0. Default value is 5.0 Hz.
5808 Depth of modulation as a percentage. Range is 0.0 - 1.0.
5809 Default value is 0.5.
5814 Sinusoidal phase modulation.
5816 The filter accepts the following options:
5820 Modulation frequency in Hertz.
5821 Range is 0.1 - 20000.0. Default value is 5.0 Hz.
5824 Depth of modulation as a percentage. Range is 0.0 - 1.0.
5825 Default value is 0.5.
5830 Adjust the input audio volume.
5832 It accepts the following parameters:
5836 Set audio volume expression.
5838 Output values are clipped to the maximum value.
5840 The output audio volume is given by the relation:
5842 @var{output_volume} = @var{volume} * @var{input_volume}
5845 The default value for @var{volume} is "1.0".
5848 This parameter represents the mathematical precision.
5850 It determines which input sample formats will be allowed, which affects the
5851 precision of the volume scaling.
5855 8-bit fixed-point; this limits input sample format to U8, S16, and S32.
5857 32-bit floating-point; this limits input sample format to FLT. (default)
5859 64-bit floating-point; this limits input sample format to DBL.
5863 Choose the behaviour on encountering ReplayGain side data in input frames.
5867 Remove ReplayGain side data, ignoring its contents (the default).
5870 Ignore ReplayGain side data, but leave it in the frame.
5873 Prefer the track gain, if present.
5876 Prefer the album gain, if present.
5879 @item replaygain_preamp
5880 Pre-amplification gain in dB to apply to the selected replaygain gain.
5882 Default value for @var{replaygain_preamp} is 0.0.
5884 @item replaygain_noclip
5885 Prevent clipping by limiting the gain applied.
5887 Default value for @var{replaygain_noclip} is 1.
5890 Set when the volume expression is evaluated.
5892 It accepts the following values:
5895 only evaluate expression once during the filter initialization, or
5896 when the @samp{volume} command is sent
5899 evaluate expression for each incoming frame
5902 Default value is @samp{once}.
5905 The volume expression can contain the following parameters.
5909 frame number (starting at zero)
5912 @item nb_consumed_samples
5913 number of samples consumed by the filter
5915 number of samples in the current frame
5917 original frame position in the file
5923 PTS at start of stream
5925 time at start of stream
5931 last set volume value
5934 Note that when @option{eval} is set to @samp{once} only the
5935 @var{sample_rate} and @var{tb} variables are available, all other
5936 variables will evaluate to NAN.
5938 @subsection Commands
5940 This filter supports the following commands:
5943 Modify the volume expression.
5944 The command accepts the same syntax of the corresponding option.
5946 If the specified expression is not valid, it is kept at its current
5950 @subsection Examples
5954 Halve the input audio volume:
5958 volume=volume=-6.0206dB
5961 In all the above example the named key for @option{volume} can be
5962 omitted, for example like in:
5968 Increase input audio power by 6 decibels using fixed-point precision:
5970 volume=volume=6dB:precision=fixed
5974 Fade volume after time 10 with an annihilation period of 5 seconds:
5976 volume='if(lt(t,10),1,max(1-(t-10)/5,0))':eval=frame
5980 @section volumedetect
5982 Detect the volume of the input video.
5984 The filter has no parameters. The input is not modified. Statistics about
5985 the volume will be printed in the log when the input stream end is reached.
5987 In particular it will show the mean volume (root mean square), maximum
5988 volume (on a per-sample basis), and the beginning of a histogram of the
5989 registered volume values (from the maximum value to a cumulated 1/1000 of
5992 All volumes are in decibels relative to the maximum PCM value.
5994 @subsection Examples
5996 Here is an excerpt of the output:
5998 [Parsed_volumedetect_0 @ 0xa23120] mean_volume: -27 dB
5999 [Parsed_volumedetect_0 @ 0xa23120] max_volume: -4 dB
6000 [Parsed_volumedetect_0 @ 0xa23120] histogram_4db: 6
6001 [Parsed_volumedetect_0 @ 0xa23120] histogram_5db: 62
6002 [Parsed_volumedetect_0 @ 0xa23120] histogram_6db: 286
6003 [Parsed_volumedetect_0 @ 0xa23120] histogram_7db: 1042
6004 [Parsed_volumedetect_0 @ 0xa23120] histogram_8db: 2551
6005 [Parsed_volumedetect_0 @ 0xa23120] histogram_9db: 4609
6006 [Parsed_volumedetect_0 @ 0xa23120] histogram_10db: 8409
6012 The mean square energy is approximately -27 dB, or 10^-2.7.
6014 The largest sample is at -4 dB, or more precisely between -4 dB and -5 dB.
6016 There are 6 samples at -4 dB, 62 at -5 dB, 286 at -6 dB, etc.
6019 In other words, raising the volume by +4 dB does not cause any clipping,
6020 raising it by +5 dB causes clipping for 6 samples, etc.
6022 @c man end AUDIO FILTERS
6024 @chapter Audio Sources
6025 @c man begin AUDIO SOURCES
6027 Below is a description of the currently available audio sources.
6031 Buffer audio frames, and make them available to the filter chain.
6033 This source is mainly intended for a programmatic use, in particular
6034 through the interface defined in @file{libavfilter/buffersrc.h}.
6036 It accepts the following parameters:
6040 The timebase which will be used for timestamps of submitted frames. It must be
6041 either a floating-point number or in @var{numerator}/@var{denominator} form.
6044 The sample rate of the incoming audio buffers.
6047 The sample format of the incoming audio buffers.
6048 Either a sample format name or its corresponding integer representation from
6049 the enum AVSampleFormat in @file{libavutil/samplefmt.h}
6051 @item channel_layout
6052 The channel layout of the incoming audio buffers.
6053 Either a channel layout name from channel_layout_map in
6054 @file{libavutil/channel_layout.c} or its corresponding integer representation
6055 from the AV_CH_LAYOUT_* macros in @file{libavutil/channel_layout.h}
6058 The number of channels of the incoming audio buffers.
6059 If both @var{channels} and @var{channel_layout} are specified, then they
6064 @subsection Examples
6067 abuffer=sample_rate=44100:sample_fmt=s16p:channel_layout=stereo
6070 will instruct the source to accept planar 16bit signed stereo at 44100Hz.
6071 Since the sample format with name "s16p" corresponds to the number
6072 6 and the "stereo" channel layout corresponds to the value 0x3, this is
6075 abuffer=sample_rate=44100:sample_fmt=6:channel_layout=0x3
6080 Generate an audio signal specified by an expression.
6082 This source accepts in input one or more expressions (one for each
6083 channel), which are evaluated and used to generate a corresponding
6086 This source accepts the following options:
6090 Set the '|'-separated expressions list for each separate channel. In case the
6091 @option{channel_layout} option is not specified, the selected channel layout
6092 depends on the number of provided expressions. Otherwise the last
6093 specified expression is applied to the remaining output channels.
6095 @item channel_layout, c
6096 Set the channel layout. The number of channels in the specified layout
6097 must be equal to the number of specified expressions.
6100 Set the minimum duration of the sourced audio. See
6101 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
6102 for the accepted syntax.
6103 Note that the resulting duration may be greater than the specified
6104 duration, as the generated audio is always cut at the end of a
6107 If not specified, or the expressed duration is negative, the audio is
6108 supposed to be generated forever.
6111 Set the number of samples per channel per each output frame,
6114 @item sample_rate, s
6115 Specify the sample rate, default to 44100.
6118 Each expression in @var{exprs} can contain the following constants:
6122 number of the evaluated sample, starting from 0
6125 time of the evaluated sample expressed in seconds, starting from 0
6132 @subsection Examples
6142 Generate a sin signal with frequency of 440 Hz, set sample rate to
6145 aevalsrc="sin(440*2*PI*t):s=8000"
6149 Generate a two channels signal, specify the channel layout (Front
6150 Center + Back Center) explicitly:
6152 aevalsrc="sin(420*2*PI*t)|cos(430*2*PI*t):c=FC|BC"
6156 Generate white noise:
6158 aevalsrc="-2+random(0)"
6162 Generate an amplitude modulated signal:
6164 aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)"
6168 Generate 2.5 Hz binaural beats on a 360 Hz carrier:
6170 aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) | 0.1*sin(2*PI*(360+2.5/2)*t)"
6177 Generate a FIR coefficients using frequency sampling method.
6179 The resulting stream can be used with @ref{afir} filter for filtering the audio signal.
6181 The filter accepts the following options:
6185 Set number of filter coefficents in output audio stream.
6186 Default value is 1025.
6189 Set frequency points from where magnitude and phase are set.
6190 This must be in non decreasing order, and first element must be 0, while last element
6191 must be 1. Elements are separated by white spaces.
6194 Set magnitude value for every frequency point set by @option{frequency}.
6195 Number of values must be same as number of frequency points.
6196 Values are separated by white spaces.
6199 Set phase value for every frequency point set by @option{frequency}.
6200 Number of values must be same as number of frequency points.
6201 Values are separated by white spaces.
6203 @item sample_rate, r
6204 Set sample rate, default is 44100.
6207 Set number of samples per each frame. Default is 1024.
6210 Set window function. Default is blackman.
6215 The null audio source, return unprocessed audio frames. It is mainly useful
6216 as a template and to be employed in analysis / debugging tools, or as
6217 the source for filters which ignore the input data (for example the sox
6220 This source accepts the following options:
6224 @item channel_layout, cl
6226 Specifies the channel layout, and can be either an integer or a string
6227 representing a channel layout. The default value of @var{channel_layout}
6230 Check the channel_layout_map definition in
6231 @file{libavutil/channel_layout.c} for the mapping between strings and
6232 channel layout values.
6234 @item sample_rate, r
6235 Specifies the sample rate, and defaults to 44100.
6238 Set the number of samples per requested frames.
6241 Set the duration of the sourced audio. See
6242 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
6243 for the accepted syntax.
6245 If not specified, or the expressed duration is negative, the audio is
6246 supposed to be generated forever.
6249 @subsection Examples
6253 Set the sample rate to 48000 Hz and the channel layout to AV_CH_LAYOUT_MONO.
6255 anullsrc=r=48000:cl=4
6259 Do the same operation with a more obvious syntax:
6261 anullsrc=r=48000:cl=mono
6265 All the parameters need to be explicitly defined.
6269 Synthesize a voice utterance using the libflite library.
6271 To enable compilation of this filter you need to configure FFmpeg with
6272 @code{--enable-libflite}.
6274 Note that versions of the flite library prior to 2.0 are not thread-safe.
6276 The filter accepts the following options:
6281 If set to 1, list the names of the available voices and exit
6282 immediately. Default value is 0.
6285 Set the maximum number of samples per frame. Default value is 512.
6288 Set the filename containing the text to speak.
6291 Set the text to speak.
6294 Set the voice to use for the speech synthesis. Default value is
6295 @code{kal}. See also the @var{list_voices} option.
6298 @subsection Examples
6302 Read from file @file{speech.txt}, and synthesize the text using the
6303 standard flite voice:
6305 flite=textfile=speech.txt
6309 Read the specified text selecting the @code{slt} voice:
6311 flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
6315 Input text to ffmpeg:
6317 ffmpeg -f lavfi -i flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
6321 Make @file{ffplay} speak the specified text, using @code{flite} and
6322 the @code{lavfi} device:
6324 ffplay -f lavfi flite=text='No more be grieved for which that thou hast done.'
6328 For more information about libflite, check:
6329 @url{http://www.festvox.org/flite/}
6333 Generate a noise audio signal.
6335 The filter accepts the following options:
6338 @item sample_rate, r
6339 Specify the sample rate. Default value is 48000 Hz.
6342 Specify the amplitude (0.0 - 1.0) of the generated audio stream. Default value
6346 Specify the duration of the generated audio stream. Not specifying this option
6347 results in noise with an infinite length.
6349 @item color, colour, c
6350 Specify the color of noise. Available noise colors are white, pink, brown,
6351 blue, violet and velvet. Default color is white.
6354 Specify a value used to seed the PRNG.
6357 Set the number of samples per each output frame, default is 1024.
6360 @subsection Examples
6365 Generate 60 seconds of pink noise, with a 44.1 kHz sampling rate and an amplitude of 0.5:
6367 anoisesrc=d=60:c=pink:r=44100:a=0.5
6373 Generate odd-tap Hilbert transform FIR coefficients.
6375 The resulting stream can be used with @ref{afir} filter for phase-shifting
6376 the signal by 90 degrees.
6378 This is used in many matrix coding schemes and for analytic signal generation.
6379 The process is often written as a multiplication by i (or j), the imaginary unit.
6381 The filter accepts the following options:
6385 @item sample_rate, s
6386 Set sample rate, default is 44100.
6389 Set length of FIR filter, default is 22051.
6392 Set number of samples per each frame.
6395 Set window function to be used when generating FIR coefficients.
6400 Generate a sinc kaiser-windowed low-pass, high-pass, band-pass, or band-reject FIR coefficients.
6402 The resulting stream can be used with @ref{afir} filter for filtering the audio signal.
6404 The filter accepts the following options:
6407 @item sample_rate, r
6408 Set sample rate, default is 44100.
6411 Set number of samples per each frame. Default is 1024.
6414 Set high-pass frequency. Default is 0.
6417 Set low-pass frequency. Default is 0.
6418 If high-pass frequency is lower than low-pass frequency and low-pass frequency
6419 is higher than 0 then filter will create band-pass filter coefficients,
6420 otherwise band-reject filter coefficients.
6423 Set filter phase response. Default is 50. Allowed range is from 0 to 100.
6426 Set Kaiser window beta.
6429 Set stop-band attenuation. Default is 120dB, allowed range is from 40 to 180 dB.
6432 Enable rounding, by default is disabled.
6435 Set number of taps for high-pass filter.
6438 Set number of taps for low-pass filter.
6443 Generate an audio signal made of a sine wave with amplitude 1/8.
6445 The audio signal is bit-exact.
6447 The filter accepts the following options:
6452 Set the carrier frequency. Default is 440 Hz.
6454 @item beep_factor, b
6455 Enable a periodic beep every second with frequency @var{beep_factor} times
6456 the carrier frequency. Default is 0, meaning the beep is disabled.
6458 @item sample_rate, r
6459 Specify the sample rate, default is 44100.
6462 Specify the duration of the generated audio stream.
6464 @item samples_per_frame
6465 Set the number of samples per output frame.
6467 The expression can contain the following constants:
6471 The (sequential) number of the output audio frame, starting from 0.
6474 The PTS (Presentation TimeStamp) of the output audio frame,
6475 expressed in @var{TB} units.
6478 The PTS of the output audio frame, expressed in seconds.
6481 The timebase of the output audio frames.
6484 Default is @code{1024}.
6487 @subsection Examples
6492 Generate a simple 440 Hz sine wave:
6498 Generate a 220 Hz sine wave with a 880 Hz beep each second, for 5 seconds:
6502 sine=frequency=220:beep_factor=4:duration=5
6506 Generate a 1 kHz sine wave following @code{1602,1601,1602,1601,1602} NTSC
6509 sine=1000:samples_per_frame='st(0,mod(n,5)); 1602-not(not(eq(ld(0),1)+eq(ld(0),3)))'
6513 @c man end AUDIO SOURCES
6515 @chapter Audio Sinks
6516 @c man begin AUDIO SINKS
6518 Below is a description of the currently available audio sinks.
6520 @section abuffersink
6522 Buffer audio frames, and make them available to the end of filter chain.
6524 This sink is mainly intended for programmatic use, in particular
6525 through the interface defined in @file{libavfilter/buffersink.h}
6526 or the options system.
6528 It accepts a pointer to an AVABufferSinkContext structure, which
6529 defines the incoming buffers' formats, to be passed as the opaque
6530 parameter to @code{avfilter_init_filter} for initialization.
6533 Null audio sink; do absolutely nothing with the input audio. It is
6534 mainly useful as a template and for use in analysis / debugging
6537 @c man end AUDIO SINKS
6539 @chapter Video Filters
6540 @c man begin VIDEO FILTERS
6542 When you configure your FFmpeg build, you can disable any of the
6543 existing filters using @code{--disable-filters}.
6544 The configure output will show the video filters included in your
6547 Below is a description of the currently available video filters.
6551 Mark a region of interest in a video frame.
6553 The frame data is passed through unchanged, but metadata is attached
6554 to the frame indicating regions of interest which can affect the
6555 behaviour of later encoding. Multiple regions can be marked by
6556 applying the filter multiple times.
6560 Region distance in pixels from the left edge of the frame.
6562 Region distance in pixels from the top edge of the frame.
6564 Region width in pixels.
6566 Region height in pixels.
6568 The parameters @var{x}, @var{y}, @var{w} and @var{h} are expressions,
6569 and may contain the following variables:
6572 Width of the input frame.
6574 Height of the input frame.
6578 Quantisation offset to apply within the region.
6580 This must be a real value in the range -1 to +1. A value of zero
6581 indicates no quality change. A negative value asks for better quality
6582 (less quantisation), while a positive value asks for worse quality
6583 (greater quantisation).
6585 The range is calibrated so that the extreme values indicate the
6586 largest possible offset - if the rest of the frame is encoded with the
6587 worst possible quality, an offset of -1 indicates that this region
6588 should be encoded with the best possible quality anyway. Intermediate
6589 values are then interpolated in some codec-dependent way.
6591 For example, in 10-bit H.264 the quantisation parameter varies between
6592 -12 and 51. A typical qoffset value of -1/10 therefore indicates that
6593 this region should be encoded with a QP around one-tenth of the full
6594 range better than the rest of the frame. So, if most of the frame
6595 were to be encoded with a QP of around 30, this region would get a QP
6596 of around 24 (an offset of approximately -1/10 * (51 - -12) = -6.3).
6597 An extreme value of -1 would indicate that this region should be
6598 encoded with the best possible quality regardless of the treatment of
6599 the rest of the frame - that is, should be encoded at a QP of -12.
6601 If set to true, remove any existing regions of interest marked on the
6602 frame before adding the new one.
6605 @subsection Examples
6609 Mark the centre quarter of the frame as interesting.
6611 addroi=iw/4:ih/4:iw/2:ih/2:-1/10
6614 Mark the 100-pixel-wide region on the left edge of the frame as very
6615 uninteresting (to be encoded at much lower quality than the rest of
6618 addroi=0:0:100:ih:+1/5
6622 @section alphaextract
6624 Extract the alpha component from the input as a grayscale video. This
6625 is especially useful with the @var{alphamerge} filter.
6629 Add or replace the alpha component of the primary input with the
6630 grayscale value of a second input. This is intended for use with
6631 @var{alphaextract} to allow the transmission or storage of frame
6632 sequences that have alpha in a format that doesn't support an alpha
6635 For example, to reconstruct full frames from a normal YUV-encoded video
6636 and a separate video created with @var{alphaextract}, you might use:
6638 movie=in_alpha.mkv [alpha]; [in][alpha] alphamerge [out]
6643 Amplify differences between current pixel and pixels of adjacent frames in
6644 same pixel location.
6646 This filter accepts the following options:
6650 Set frame radius. Default is 2. Allowed range is from 1 to 63.
6651 For example radius of 3 will instruct filter to calculate average of 7 frames.
6654 Set factor to amplify difference. Default is 2. Allowed range is from 0 to 65535.
6657 Set threshold for difference amplification. Any difference greater or equal to
6658 this value will not alter source pixel. Default is 10.
6659 Allowed range is from 0 to 65535.
6662 Set tolerance for difference amplification. Any difference lower to
6663 this value will not alter source pixel. Default is 0.
6664 Allowed range is from 0 to 65535.
6667 Set lower limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535.
6668 This option controls maximum possible value that will decrease source pixel value.
6671 Set high limit for changing source pixel. Default is 65535. Allowed range is from 0 to 65535.
6672 This option controls maximum possible value that will increase source pixel value.
6675 Set which planes to filter. Default is all. Allowed range is from 0 to 15.
6678 @subsection Commands
6680 This filter supports the following @ref{commands} that corresponds to option of same name:
6692 Same as the @ref{subtitles} filter, except that it doesn't require libavcodec
6693 and libavformat to work. On the other hand, it is limited to ASS (Advanced
6694 Substation Alpha) subtitles files.
6696 This filter accepts the following option in addition to the common options from
6697 the @ref{subtitles} filter:
6701 Set the shaping engine
6703 Available values are:
6706 The default libass shaping engine, which is the best available.
6708 Fast, font-agnostic shaper that can do only substitutions
6710 Slower shaper using OpenType for substitutions and positioning
6713 The default is @code{auto}.
6717 Apply an Adaptive Temporal Averaging Denoiser to the video input.
6719 The filter accepts the following options:
6723 Set threshold A for 1st plane. Default is 0.02.
6724 Valid range is 0 to 0.3.
6727 Set threshold B for 1st plane. Default is 0.04.
6728 Valid range is 0 to 5.
6731 Set threshold A for 2nd plane. Default is 0.02.
6732 Valid range is 0 to 0.3.
6735 Set threshold B for 2nd plane. Default is 0.04.
6736 Valid range is 0 to 5.
6739 Set threshold A for 3rd plane. Default is 0.02.
6740 Valid range is 0 to 0.3.
6743 Set threshold B for 3rd plane. Default is 0.04.
6744 Valid range is 0 to 5.
6746 Threshold A is designed to react on abrupt changes in the input signal and
6747 threshold B is designed to react on continuous changes in the input signal.
6750 Set number of frames filter will use for averaging. Default is 9. Must be odd
6751 number in range [5, 129].
6754 Set what planes of frame filter will use for averaging. Default is all.
6757 Set what variant of algorithm filter will use for averaging. Default is @code{p} parallel.
6758 Alternatively can be set to @code{s} serial.
6760 Parallel can be faster then serial, while other way around is never true.
6761 Parallel will abort early on first change being greater then thresholds, while serial
6762 will continue processing other side of frames if they are equal or bellow thresholds.
6765 @subsection Commands
6766 This filter supports same @ref{commands} as options except option @code{s}.
6767 The command accepts the same syntax of the corresponding option.
6771 Apply average blur filter.
6773 The filter accepts the following options:
6777 Set horizontal radius size.
6780 Set which planes to filter. By default all planes are filtered.
6783 Set vertical radius size, if zero it will be same as @code{sizeX}.
6784 Default is @code{0}.
6787 @subsection Commands
6788 This filter supports same commands as options.
6789 The command accepts the same syntax of the corresponding option.
6791 If the specified expression is not valid, it is kept at its current
6796 Compute the bounding box for the non-black pixels in the input frame
6799 This filter computes the bounding box containing all the pixels with a
6800 luminance value greater than the minimum allowed value.
6801 The parameters describing the bounding box are printed on the filter
6804 The filter accepts the following option:
6808 Set the minimal luminance value. Default is @code{16}.
6812 Apply bilateral filter, spatial smoothing while preserving edges.
6814 The filter accepts the following options:
6817 Set sigma of gaussian function to calculate spatial weight.
6818 Allowed range is 0 to 512. Default is 0.1.
6821 Set sigma of gaussian function to calculate range weight.
6822 Allowed range is 0 to 1. Default is 0.1.
6825 Set planes to filter. Default is first only.
6828 @section bitplanenoise
6830 Show and measure bit plane noise.
6832 The filter accepts the following options:
6836 Set which plane to analyze. Default is @code{1}.
6839 Filter out noisy pixels from @code{bitplane} set above.
6840 Default is disabled.
6843 @section blackdetect
6845 Detect video intervals that are (almost) completely black. Can be
6846 useful to detect chapter transitions, commercials, or invalid
6849 The filter outputs its detection analysis to both the log as well as
6850 frame metadata. If a black segment of at least the specified minimum
6851 duration is found, a line with the start and end timestamps as well
6852 as duration is printed to the log with level @code{info}. In addition,
6853 a log line with level @code{debug} is printed per frame showing the
6854 black amount detected for that frame.
6856 The filter also attaches metadata to the first frame of a black
6857 segment with key @code{lavfi.black_start} and to the first frame
6858 after the black segment ends with key @code{lavfi.black_end}. The
6859 value is the frame's timestamp. This metadata is added regardless
6860 of the minimum duration specified.
6862 The filter accepts the following options:
6865 @item black_min_duration, d
6866 Set the minimum detected black duration expressed in seconds. It must
6867 be a non-negative floating point number.
6869 Default value is 2.0.
6871 @item picture_black_ratio_th, pic_th
6872 Set the threshold for considering a picture "black".
6873 Express the minimum value for the ratio:
6875 @var{nb_black_pixels} / @var{nb_pixels}
6878 for which a picture is considered black.
6879 Default value is 0.98.
6881 @item pixel_black_th, pix_th
6882 Set the threshold for considering a pixel "black".
6884 The threshold expresses the maximum pixel luminance value for which a
6885 pixel is considered "black". The provided value is scaled according to
6886 the following equation:
6888 @var{absolute_threshold} = @var{luminance_minimum_value} + @var{pixel_black_th} * @var{luminance_range_size}
6891 @var{luminance_range_size} and @var{luminance_minimum_value} depend on
6892 the input video format, the range is [0-255] for YUV full-range
6893 formats and [16-235] for YUV non full-range formats.
6895 Default value is 0.10.
6898 The following example sets the maximum pixel threshold to the minimum
6899 value, and detects only black intervals of 2 or more seconds:
6901 blackdetect=d=2:pix_th=0.00
6906 Detect frames that are (almost) completely black. Can be useful to
6907 detect chapter transitions or commercials. Output lines consist of
6908 the frame number of the detected frame, the percentage of blackness,
6909 the position in the file if known or -1 and the timestamp in seconds.
6911 In order to display the output lines, you need to set the loglevel at
6912 least to the AV_LOG_INFO value.
6914 This filter exports frame metadata @code{lavfi.blackframe.pblack}.
6915 The value represents the percentage of pixels in the picture that
6916 are below the threshold value.
6918 It accepts the following parameters:
6923 The percentage of the pixels that have to be below the threshold; it defaults to
6926 @item threshold, thresh
6927 The threshold below which a pixel value is considered black; it defaults to
6935 Blend two video frames into each other.
6937 The @code{blend} filter takes two input streams and outputs one
6938 stream, the first input is the "top" layer and second input is
6939 "bottom" layer. By default, the output terminates when the longest input terminates.
6941 The @code{tblend} (time blend) filter takes two consecutive frames
6942 from one single stream, and outputs the result obtained by blending
6943 the new frame on top of the old frame.
6945 A description of the accepted options follows.
6953 Set blend mode for specific pixel component or all pixel components in case
6954 of @var{all_mode}. Default value is @code{normal}.
6956 Available values for component modes are:
6998 Set blend opacity for specific pixel component or all pixel components in case
6999 of @var{all_opacity}. Only used in combination with pixel component blend modes.
7006 Set blend expression for specific pixel component or all pixel components in case
7007 of @var{all_expr}. Note that related mode options will be ignored if those are set.
7009 The expressions can use the following variables:
7013 The sequential number of the filtered frame, starting from @code{0}.
7017 the coordinates of the current sample
7021 the width and height of currently filtered plane
7025 Width and height scale for the plane being filtered. It is the
7026 ratio between the dimensions of the current plane to the luma plane,
7027 e.g. for a @code{yuv420p} frame, the values are @code{1,1} for
7028 the luma plane and @code{0.5,0.5} for the chroma planes.
7031 Time of the current frame, expressed in seconds.
7034 Value of pixel component at current location for first video frame (top layer).
7037 Value of pixel component at current location for second video frame (bottom layer).
7041 The @code{blend} filter also supports the @ref{framesync} options.
7043 @subsection Examples
7047 Apply transition from bottom layer to top layer in first 10 seconds:
7049 blend=all_expr='A*(if(gte(T,10),1,T/10))+B*(1-(if(gte(T,10),1,T/10)))'
7053 Apply linear horizontal transition from top layer to bottom layer:
7055 blend=all_expr='A*(X/W)+B*(1-X/W)'
7059 Apply 1x1 checkerboard effect:
7061 blend=all_expr='if(eq(mod(X,2),mod(Y,2)),A,B)'
7065 Apply uncover left effect:
7067 blend=all_expr='if(gte(N*SW+X,W),A,B)'
7071 Apply uncover down effect:
7073 blend=all_expr='if(gte(Y-N*SH,0),A,B)'
7077 Apply uncover up-left effect:
7079 blend=all_expr='if(gte(T*SH*40+Y,H)*gte((T*40*SW+X)*W/H,W),A,B)'
7083 Split diagonally video and shows top and bottom layer on each side:
7085 blend=all_expr='if(gt(X,Y*(W/H)),A,B)'
7089 Display differences between the current and the previous frame:
7091 tblend=all_mode=grainextract
7097 Denoise frames using Block-Matching 3D algorithm.
7099 The filter accepts the following options.
7103 Set denoising strength. Default value is 1.
7104 Allowed range is from 0 to 999.9.
7105 The denoising algorithm is very sensitive to sigma, so adjust it
7106 according to the source.
7109 Set local patch size. This sets dimensions in 2D.
7112 Set sliding step for processing blocks. Default value is 4.
7113 Allowed range is from 1 to 64.
7114 Smaller values allows processing more reference blocks and is slower.
7117 Set maximal number of similar blocks for 3rd dimension. Default value is 1.
7118 When set to 1, no block matching is done. Larger values allows more blocks
7120 Allowed range is from 1 to 256.
7123 Set radius for search block matching. Default is 9.
7124 Allowed range is from 1 to INT32_MAX.
7127 Set step between two search locations for block matching. Default is 1.
7128 Allowed range is from 1 to 64. Smaller is slower.
7131 Set threshold of mean square error for block matching. Valid range is 0 to
7135 Set thresholding parameter for hard thresholding in 3D transformed domain.
7136 Larger values results in stronger hard-thresholding filtering in frequency
7140 Set filtering estimation mode. Can be @code{basic} or @code{final}.
7141 Default is @code{basic}.
7144 If enabled, filter will use 2nd stream for block matching.
7145 Default is disabled for @code{basic} value of @var{estim} option,
7146 and always enabled if value of @var{estim} is @code{final}.
7149 Set planes to filter. Default is all available except alpha.
7152 @subsection Examples
7156 Basic filtering with bm3d:
7158 bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic
7162 Same as above, but filtering only luma:
7164 bm3d=sigma=3:block=4:bstep=2:group=1:estim=basic:planes=1
7168 Same as above, but with both estimation modes:
7170 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
7174 Same as above, but prefilter with @ref{nlmeans} filter instead:
7176 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
7182 Apply a boxblur algorithm to the input video.
7184 It accepts the following parameters:
7188 @item luma_radius, lr
7189 @item luma_power, lp
7190 @item chroma_radius, cr
7191 @item chroma_power, cp
7192 @item alpha_radius, ar
7193 @item alpha_power, ap
7197 A description of the accepted options follows.
7200 @item luma_radius, lr
7201 @item chroma_radius, cr
7202 @item alpha_radius, ar
7203 Set an expression for the box radius in pixels used for blurring the
7204 corresponding input plane.
7206 The radius value must be a non-negative number, and must not be
7207 greater than the value of the expression @code{min(w,h)/2} for the
7208 luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma
7211 Default value for @option{luma_radius} is "2". If not specified,
7212 @option{chroma_radius} and @option{alpha_radius} default to the
7213 corresponding value set for @option{luma_radius}.
7215 The expressions can contain the following constants:
7219 The input width and height in pixels.
7223 The input chroma image width and height in pixels.
7227 The horizontal and vertical chroma subsample values. For example, for the
7228 pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1.
7231 @item luma_power, lp
7232 @item chroma_power, cp
7233 @item alpha_power, ap
7234 Specify how many times the boxblur filter is applied to the
7235 corresponding plane.
7237 Default value for @option{luma_power} is 2. If not specified,
7238 @option{chroma_power} and @option{alpha_power} default to the
7239 corresponding value set for @option{luma_power}.
7241 A value of 0 will disable the effect.
7244 @subsection Examples
7248 Apply a boxblur filter with the luma, chroma, and alpha radii
7251 boxblur=luma_radius=2:luma_power=1
7256 Set the luma radius to 2, and alpha and chroma radius to 0:
7258 boxblur=2:1:cr=0:ar=0
7262 Set the luma and chroma radii to a fraction of the video dimension:
7264 boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1
7270 Deinterlace the input video ("bwdif" stands for "Bob Weaver
7271 Deinterlacing Filter").
7273 Motion adaptive deinterlacing based on yadif with the use of w3fdif and cubic
7274 interpolation algorithms.
7275 It accepts the following parameters:
7279 The interlacing mode to adopt. It accepts one of the following values:
7283 Output one frame for each frame.
7285 Output one frame for each field.
7288 The default value is @code{send_field}.
7291 The picture field parity assumed for the input interlaced video. It accepts one
7292 of the following values:
7296 Assume the top field is first.
7298 Assume the bottom field is first.
7300 Enable automatic detection of field parity.
7303 The default value is @code{auto}.
7304 If the interlacing is unknown or the decoder does not export this information,
7305 top field first will be assumed.
7308 Specify which frames to deinterlace. Accepts one of the following
7313 Deinterlace all frames.
7315 Only deinterlace frames marked as interlaced.
7318 The default value is @code{all}.
7323 Apply Contrast Adaptive Sharpen filter to video stream.
7325 The filter accepts the following options:
7329 Set the sharpening strength. Default value is 0.
7332 Set planes to filter. Default value is to filter all
7333 planes except alpha plane.
7337 Remove all color information for all colors except for certain one.
7339 The filter accepts the following options:
7343 The color which will not be replaced with neutral chroma.
7346 Similarity percentage with the above color.
7347 0.01 matches only the exact key color, while 1.0 matches everything.
7351 0.0 makes pixels either fully gray, or not gray at all.
7352 Higher values result in more preserved color.
7355 Signals that the color passed is already in YUV instead of RGB.
7357 Literal colors like "green" or "red" don't make sense with this enabled anymore.
7358 This can be used to pass exact YUV values as hexadecimal numbers.
7361 @subsection Commands
7362 This filter supports same @ref{commands} as options.
7363 The command accepts the same syntax of the corresponding option.
7365 If the specified expression is not valid, it is kept at its current
7369 YUV colorspace color/chroma keying.
7371 The filter accepts the following options:
7375 The color which will be replaced with transparency.
7378 Similarity percentage with the key color.
7380 0.01 matches only the exact key color, while 1.0 matches everything.
7385 0.0 makes pixels either fully transparent, or not transparent at all.
7387 Higher values result in semi-transparent pixels, with a higher transparency
7388 the more similar the pixels color is to the key color.
7391 Signals that the color passed is already in YUV instead of RGB.
7393 Literal colors like "green" or "red" don't make sense with this enabled anymore.
7394 This can be used to pass exact YUV values as hexadecimal numbers.
7397 @subsection Commands
7398 This filter supports same @ref{commands} as options.
7399 The command accepts the same syntax of the corresponding option.
7401 If the specified expression is not valid, it is kept at its current
7404 @subsection Examples
7408 Make every green pixel in the input image transparent:
7410 ffmpeg -i input.png -vf chromakey=green out.png
7414 Overlay a greenscreen-video on top of a static black background.
7416 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
7421 Reduce chrominance noise.
7423 The filter accepts the following options:
7427 Set threshold for averaging chrominance values.
7428 Sum of absolute difference of U and V pixel components or current
7429 pixel and neighbour pixels lower than this threshold will be used in
7430 averaging. Luma component is left unchanged and is copied to output.
7431 Default value is 30. Allowed range is from 1 to 200.
7434 Set horizontal radius of rectangle used for averaging.
7435 Allowed range is from 1 to 100. Default value is 5.
7438 Set vertical radius of rectangle used for averaging.
7439 Allowed range is from 1 to 100. Default value is 5.
7442 Set horizontal step when averaging. Default value is 1.
7443 Allowed range is from 1 to 50.
7444 Mostly useful to speed-up filtering.
7447 Set vertical step when averaging. Default value is 1.
7448 Allowed range is from 1 to 50.
7449 Mostly useful to speed-up filtering.
7452 @subsection Commands
7453 This filter supports same @ref{commands} as options.
7454 The command accepts the same syntax of the corresponding option.
7456 @section chromashift
7457 Shift chroma pixels horizontally and/or vertically.
7459 The filter accepts the following options:
7462 Set amount to shift chroma-blue horizontally.
7464 Set amount to shift chroma-blue vertically.
7466 Set amount to shift chroma-red horizontally.
7468 Set amount to shift chroma-red vertically.
7470 Set edge mode, can be @var{smear}, default, or @var{warp}.
7473 @subsection Commands
7475 This filter supports the all above options as @ref{commands}.
7479 Display CIE color diagram with pixels overlaid onto it.
7481 The filter accepts the following options:
7496 @item uhdtv, rec2020
7510 Set what gamuts to draw.
7512 See @code{system} option for available values.
7515 Set ciescope size, by default set to 512.
7518 Set intensity used to map input pixel values to CIE diagram.
7521 Set contrast used to draw tongue colors that are out of active color system gamut.
7524 Correct gamma displayed on scope, by default enabled.
7527 Show white point on CIE diagram, by default disabled.
7530 Set input gamma. Used only with XYZ input color space.
7535 Visualize information exported by some codecs.
7537 Some codecs can export information through frames using side-data or other
7538 means. For example, some MPEG based codecs export motion vectors through the
7539 @var{export_mvs} flag in the codec @option{flags2} option.
7541 The filter accepts the following option:
7545 Set motion vectors to visualize.
7547 Available flags for @var{mv} are:
7551 forward predicted MVs of P-frames
7553 forward predicted MVs of B-frames
7555 backward predicted MVs of B-frames
7559 Display quantization parameters using the chroma planes.
7562 Set motion vectors type to visualize. Includes MVs from all frames unless specified by @var{frame_type} option.
7564 Available flags for @var{mv_type} are:
7568 forward predicted MVs
7570 backward predicted MVs
7573 @item frame_type, ft
7574 Set frame type to visualize motion vectors of.
7576 Available flags for @var{frame_type} are:
7580 intra-coded frames (I-frames)
7582 predicted frames (P-frames)
7584 bi-directionally predicted frames (B-frames)
7588 @subsection Examples
7592 Visualize forward predicted MVs of all frames using @command{ffplay}:
7594 ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv_type=fp
7598 Visualize multi-directionals MVs of P and B-Frames using @command{ffplay}:
7600 ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv=pf+bf+bb
7604 @section colorbalance
7605 Modify intensity of primary colors (red, green and blue) of input frames.
7607 The filter allows an input frame to be adjusted in the shadows, midtones or highlights
7608 regions for the red-cyan, green-magenta or blue-yellow balance.
7610 A positive adjustment value shifts the balance towards the primary color, a negative
7611 value towards the complementary color.
7613 The filter accepts the following options:
7619 Adjust red, green and blue shadows (darkest pixels).
7624 Adjust red, green and blue midtones (medium pixels).
7629 Adjust red, green and blue highlights (brightest pixels).
7631 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
7634 Preserve lightness when changing color balance. Default is disabled.
7637 @subsection Examples
7641 Add red color cast to shadows:
7647 @subsection Commands
7649 This filter supports the all above options as @ref{commands}.
7651 @section colorchannelmixer
7653 Adjust video input frames by re-mixing color channels.
7655 This filter modifies a color channel by adding the values associated to
7656 the other channels of the same pixels. For example if the value to
7657 modify is red, the output value will be:
7659 @var{red}=@var{red}*@var{rr} + @var{blue}*@var{rb} + @var{green}*@var{rg} + @var{alpha}*@var{ra}
7662 The filter accepts the following options:
7669 Adjust contribution of input red, green, blue and alpha channels for output red channel.
7670 Default is @code{1} for @var{rr}, and @code{0} for @var{rg}, @var{rb} and @var{ra}.
7676 Adjust contribution of input red, green, blue and alpha channels for output green channel.
7677 Default is @code{1} for @var{gg}, and @code{0} for @var{gr}, @var{gb} and @var{ga}.
7683 Adjust contribution of input red, green, blue and alpha channels for output blue channel.
7684 Default is @code{1} for @var{bb}, and @code{0} for @var{br}, @var{bg} and @var{ba}.
7690 Adjust contribution of input red, green, blue and alpha channels for output alpha channel.
7691 Default is @code{1} for @var{aa}, and @code{0} for @var{ar}, @var{ag} and @var{ab}.
7693 Allowed ranges for options are @code{[-2.0, 2.0]}.
7696 @subsection Examples
7700 Convert source to grayscale:
7702 colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3
7705 Simulate sepia tones:
7707 colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131
7711 @subsection Commands
7713 This filter supports the all above options as @ref{commands}.
7716 RGB colorspace color keying.
7718 The filter accepts the following options:
7722 The color which will be replaced with transparency.
7725 Similarity percentage with the key color.
7727 0.01 matches only the exact key color, while 1.0 matches everything.
7732 0.0 makes pixels either fully transparent, or not transparent at all.
7734 Higher values result in semi-transparent pixels, with a higher transparency
7735 the more similar the pixels color is to the key color.
7738 @subsection Examples
7742 Make every green pixel in the input image transparent:
7744 ffmpeg -i input.png -vf colorkey=green out.png
7748 Overlay a greenscreen-video on top of a static background image.
7750 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
7754 @subsection Commands
7755 This filter supports same @ref{commands} as options.
7756 The command accepts the same syntax of the corresponding option.
7758 If the specified expression is not valid, it is kept at its current
7762 Remove all color information for all RGB colors except for certain one.
7764 The filter accepts the following options:
7768 The color which will not be replaced with neutral gray.
7771 Similarity percentage with the above color.
7772 0.01 matches only the exact key color, while 1.0 matches everything.
7775 Blend percentage. 0.0 makes pixels fully gray.
7776 Higher values result in more preserved color.
7779 @subsection Commands
7780 This filter supports same @ref{commands} as options.
7781 The command accepts the same syntax of the corresponding option.
7783 If the specified expression is not valid, it is kept at its current
7786 @section colorlevels
7788 Adjust video input frames using levels.
7790 The filter accepts the following options:
7797 Adjust red, green, blue and alpha input black point.
7798 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
7804 Adjust red, green, blue and alpha input white point.
7805 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{1}.
7807 Input levels are used to lighten highlights (bright tones), darken shadows
7808 (dark tones), change the balance of bright and dark tones.
7814 Adjust red, green, blue and alpha output black point.
7815 Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{0}.
7821 Adjust red, green, blue and alpha output white point.
7822 Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{1}.
7824 Output levels allows manual selection of a constrained output level range.
7827 @subsection Examples
7831 Make video output darker:
7833 colorlevels=rimin=0.058:gimin=0.058:bimin=0.058
7839 colorlevels=rimin=0.039:gimin=0.039:bimin=0.039:rimax=0.96:gimax=0.96:bimax=0.96
7843 Make video output lighter:
7845 colorlevels=rimax=0.902:gimax=0.902:bimax=0.902
7849 Increase brightness:
7851 colorlevels=romin=0.5:gomin=0.5:bomin=0.5
7855 @subsection Commands
7857 This filter supports the all above options as @ref{commands}.
7859 @section colormatrix
7861 Convert color matrix.
7863 The filter accepts the following options:
7868 Specify the source and destination color matrix. Both values must be
7871 The accepted values are:
7899 For example to convert from BT.601 to SMPTE-240M, use the command:
7901 colormatrix=bt601:smpte240m
7906 Convert colorspace, transfer characteristics or color primaries.
7907 Input video needs to have an even size.
7909 The filter accepts the following options:
7914 Specify all color properties at once.
7916 The accepted values are:
7946 Specify output colorspace.
7948 The accepted values are:
7957 BT.470BG or BT.601-6 625
7960 SMPTE-170M or BT.601-6 525
7969 BT.2020 with non-constant luminance
7975 Specify output transfer characteristics.
7977 The accepted values are:
7989 Constant gamma of 2.2
7992 Constant gamma of 2.8
7995 SMPTE-170M, BT.601-6 625 or BT.601-6 525
8013 BT.2020 for 10-bits content
8016 BT.2020 for 12-bits content
8022 Specify output color primaries.
8024 The accepted values are:
8033 BT.470BG or BT.601-6 625
8036 SMPTE-170M or BT.601-6 525
8060 Specify output color range.
8062 The accepted values are:
8065 TV (restricted) range
8068 MPEG (restricted) range
8079 Specify output color format.
8081 The accepted values are:
8084 YUV 4:2:0 planar 8-bits
8087 YUV 4:2:0 planar 10-bits
8090 YUV 4:2:0 planar 12-bits
8093 YUV 4:2:2 planar 8-bits
8096 YUV 4:2:2 planar 10-bits
8099 YUV 4:2:2 planar 12-bits
8102 YUV 4:4:4 planar 8-bits
8105 YUV 4:4:4 planar 10-bits
8108 YUV 4:4:4 planar 12-bits
8113 Do a fast conversion, which skips gamma/primary correction. This will take
8114 significantly less CPU, but will be mathematically incorrect. To get output
8115 compatible with that produced by the colormatrix filter, use fast=1.
8118 Specify dithering mode.
8120 The accepted values are:
8126 Floyd-Steinberg dithering
8130 Whitepoint adaptation mode.
8132 The accepted values are:
8135 Bradford whitepoint adaptation
8138 von Kries whitepoint adaptation
8141 identity whitepoint adaptation (i.e. no whitepoint adaptation)
8145 Override all input properties at once. Same accepted values as @ref{all}.
8148 Override input colorspace. Same accepted values as @ref{space}.
8151 Override input color primaries. Same accepted values as @ref{primaries}.
8154 Override input transfer characteristics. Same accepted values as @ref{trc}.
8157 Override input color range. Same accepted values as @ref{range}.
8161 The filter converts the transfer characteristics, color space and color
8162 primaries to the specified user values. The output value, if not specified,
8163 is set to a default value based on the "all" property. If that property is
8164 also not specified, the filter will log an error. The output color range and
8165 format default to the same value as the input color range and format. The
8166 input transfer characteristics, color space, color primaries and color range
8167 should be set on the input data. If any of these are missing, the filter will
8168 log an error and no conversion will take place.
8170 For example to convert the input to SMPTE-240M, use the command:
8172 colorspace=smpte240m
8175 @section convolution
8177 Apply convolution of 3x3, 5x5, 7x7 or horizontal/vertical up to 49 elements.
8179 The filter accepts the following options:
8186 Set matrix for each plane.
8187 Matrix is sequence of 9, 25 or 49 signed integers in @var{square} mode,
8188 and from 1 to 49 odd number of signed integers in @var{row} mode.
8194 Set multiplier for calculated value for each plane.
8195 If unset or 0, it will be sum of all matrix elements.
8201 Set bias for each plane. This value is added to the result of the multiplication.
8202 Useful for making the overall image brighter or darker. Default is 0.0.
8208 Set matrix mode for each plane. Can be @var{square}, @var{row} or @var{column}.
8209 Default is @var{square}.
8212 @subsection Examples
8218 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"
8224 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"
8230 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"
8236 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"
8240 Apply laplacian edge detector which includes diagonals:
8242 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"
8248 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"
8254 Apply 2D convolution of video stream in frequency domain using second stream
8257 The filter accepts the following options:
8261 Set which planes to process.
8264 Set which impulse video frames will be processed, can be @var{first}
8265 or @var{all}. Default is @var{all}.
8268 The @code{convolve} filter also supports the @ref{framesync} options.
8272 Copy the input video source unchanged to the output. This is mainly useful for
8277 Video filtering on GPU using Apple's CoreImage API on OSX.
8279 Hardware acceleration is based on an OpenGL context. Usually, this means it is
8280 processed by video hardware. However, software-based OpenGL implementations
8281 exist which means there is no guarantee for hardware processing. It depends on
8284 There are many filters and image generators provided by Apple that come with a
8285 large variety of options. The filter has to be referenced by its name along
8288 The coreimage filter accepts the following options:
8291 List all available filters and generators along with all their respective
8292 options as well as possible minimum and maximum values along with the default
8299 Specify all filters by their respective name and options.
8300 Use @var{list_filters} to determine all valid filter names and options.
8301 Numerical options are specified by a float value and are automatically clamped
8302 to their respective value range. Vector and color options have to be specified
8303 by a list of space separated float values. Character escaping has to be done.
8304 A special option name @code{default} is available to use default options for a
8307 It is required to specify either @code{default} or at least one of the filter options.
8308 All omitted options are used with their default values.
8309 The syntax of the filter string is as follows:
8311 filter=<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...][#<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...]][#...]
8315 Specify a rectangle where the output of the filter chain is copied into the
8316 input image. It is given by a list of space separated float values:
8318 output_rect=x\ y\ width\ height
8320 If not given, the output rectangle equals the dimensions of the input image.
8321 The output rectangle is automatically cropped at the borders of the input
8322 image. Negative values are valid for each component.
8324 output_rect=25\ 25\ 100\ 100
8328 Several filters can be chained for successive processing without GPU-HOST
8329 transfers allowing for fast processing of complex filter chains.
8330 Currently, only filters with zero (generators) or exactly one (filters) input
8331 image and one output image are supported. Also, transition filters are not yet
8334 Some filters generate output images with additional padding depending on the
8335 respective filter kernel. The padding is automatically removed to ensure the
8336 filter output has the same size as the input image.
8338 For image generators, the size of the output image is determined by the
8339 previous output image of the filter chain or the input image of the whole
8340 filterchain, respectively. The generators do not use the pixel information of
8341 this image to generate their output. However, the generated output is
8342 blended onto this image, resulting in partial or complete coverage of the
8345 The @ref{coreimagesrc} video source can be used for generating input images
8346 which are directly fed into the filter chain. By using it, providing input
8347 images by another video source or an input video is not required.
8349 @subsection Examples
8354 List all filters available:
8356 coreimage=list_filters=true
8360 Use the CIBoxBlur filter with default options to blur an image:
8362 coreimage=filter=CIBoxBlur@@default
8366 Use a filter chain with CISepiaTone at default values and CIVignetteEffect with
8367 its center at 100x100 and a radius of 50 pixels:
8369 coreimage=filter=CIBoxBlur@@default#CIVignetteEffect@@inputCenter=100\ 100@@inputRadius=50
8373 Use nullsrc and CIQRCodeGenerator to create a QR code for the FFmpeg homepage,
8374 given as complete and escaped command-line for Apple's standard bash shell:
8376 ffmpeg -f lavfi -i nullsrc=s=100x100,coreimage=filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png
8382 Cover a rectangular object
8384 It accepts the following options:
8388 Filepath of the optional cover image, needs to be in yuv420.
8393 It accepts the following values:
8396 cover it by the supplied image
8398 cover it by interpolating the surrounding pixels
8401 Default value is @var{blur}.
8404 @subsection Examples
8408 Cover a rectangular object by the supplied image of a given video using @command{ffmpeg}:
8410 ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
8416 Crop the input video to given dimensions.
8418 It accepts the following parameters:
8422 The width of the output video. It defaults to @code{iw}.
8423 This expression is evaluated only once during the filter
8424 configuration, or when the @samp{w} or @samp{out_w} command is sent.
8427 The height of the output video. It defaults to @code{ih}.
8428 This expression is evaluated only once during the filter
8429 configuration, or when the @samp{h} or @samp{out_h} command is sent.
8432 The horizontal position, in the input video, of the left edge of the output
8433 video. It defaults to @code{(in_w-out_w)/2}.
8434 This expression is evaluated per-frame.
8437 The vertical position, in the input video, of the top edge of the output video.
8438 It defaults to @code{(in_h-out_h)/2}.
8439 This expression is evaluated per-frame.
8442 If set to 1 will force the output display aspect ratio
8443 to be the same of the input, by changing the output sample aspect
8444 ratio. It defaults to 0.
8447 Enable exact cropping. If enabled, subsampled videos will be cropped at exact
8448 width/height/x/y as specified and will not be rounded to nearest smaller value.
8452 The @var{out_w}, @var{out_h}, @var{x}, @var{y} parameters are
8453 expressions containing the following constants:
8458 The computed values for @var{x} and @var{y}. They are evaluated for
8463 The input width and height.
8467 These are the same as @var{in_w} and @var{in_h}.
8471 The output (cropped) width and height.
8475 These are the same as @var{out_w} and @var{out_h}.
8478 same as @var{iw} / @var{ih}
8481 input sample aspect ratio
8484 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
8488 horizontal and vertical chroma subsample values. For example for the
8489 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
8492 The number of the input frame, starting from 0.
8495 the position in the file of the input frame, NAN if unknown
8498 The timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
8502 The expression for @var{out_w} may depend on the value of @var{out_h},
8503 and the expression for @var{out_h} may depend on @var{out_w}, but they
8504 cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are
8505 evaluated after @var{out_w} and @var{out_h}.
8507 The @var{x} and @var{y} parameters specify the expressions for the
8508 position of the top-left corner of the output (non-cropped) area. They
8509 are evaluated for each frame. If the evaluated value is not valid, it
8510 is approximated to the nearest valid value.
8512 The expression for @var{x} may depend on @var{y}, and the expression
8513 for @var{y} may depend on @var{x}.
8515 @subsection Examples
8519 Crop area with size 100x100 at position (12,34).
8524 Using named options, the example above becomes:
8526 crop=w=100:h=100:x=12:y=34
8530 Crop the central input area with size 100x100:
8536 Crop the central input area with size 2/3 of the input video:
8538 crop=2/3*in_w:2/3*in_h
8542 Crop the input video central square:
8549 Delimit the rectangle with the top-left corner placed at position
8550 100:100 and the right-bottom corner corresponding to the right-bottom
8551 corner of the input image.
8553 crop=in_w-100:in_h-100:100:100
8557 Crop 10 pixels from the left and right borders, and 20 pixels from
8558 the top and bottom borders
8560 crop=in_w-2*10:in_h-2*20
8564 Keep only the bottom right quarter of the input image:
8566 crop=in_w/2:in_h/2:in_w/2:in_h/2
8570 Crop height for getting Greek harmony:
8572 crop=in_w:1/PHI*in_w
8576 Apply trembling effect:
8578 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)
8582 Apply erratic camera effect depending on timestamp:
8584 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)"
8588 Set x depending on the value of y:
8590 crop=in_w/2:in_h/2:y:10+10*sin(n/10)
8594 @subsection Commands
8596 This filter supports the following commands:
8602 Set width/height of the output video and the horizontal/vertical position
8604 The command accepts the same syntax of the corresponding option.
8606 If the specified expression is not valid, it is kept at its current
8612 Auto-detect the crop size.
8614 It calculates the necessary cropping parameters and prints the
8615 recommended parameters via the logging system. The detected dimensions
8616 correspond to the non-black area of the input video.
8618 It accepts the following parameters:
8623 Set higher black value threshold, which can be optionally specified
8624 from nothing (0) to everything (255 for 8-bit based formats). An intensity
8625 value greater to the set value is considered non-black. It defaults to 24.
8626 You can also specify a value between 0.0 and 1.0 which will be scaled depending
8627 on the bitdepth of the pixel format.
8630 The value which the width/height should be divisible by. It defaults to
8631 16. The offset is automatically adjusted to center the video. Use 2 to
8632 get only even dimensions (needed for 4:2:2 video). 16 is best when
8633 encoding to most video codecs.
8635 @item reset_count, reset
8636 Set the counter that determines after how many frames cropdetect will
8637 reset the previously detected largest video area and start over to
8638 detect the current optimal crop area. Default value is 0.
8640 This can be useful when channel logos distort the video area. 0
8641 indicates 'never reset', and returns the largest area encountered during
8648 Delay video filtering until a given wallclock timestamp. The filter first
8649 passes on @option{preroll} amount of frames, then it buffers at most
8650 @option{buffer} amount of frames and waits for the cue. After reaching the cue
8651 it forwards the buffered frames and also any subsequent frames coming in its
8654 The filter can be used synchronize the output of multiple ffmpeg processes for
8655 realtime output devices like decklink. By putting the delay in the filtering
8656 chain and pre-buffering frames the process can pass on data to output almost
8657 immediately after the target wallclock timestamp is reached.
8659 Perfect frame accuracy cannot be guaranteed, but the result is good enough for
8665 The cue timestamp expressed in a UNIX timestamp in microseconds. Default is 0.
8668 The duration of content to pass on as preroll expressed in seconds. Default is 0.
8671 The maximum duration of content to buffer before waiting for the cue expressed
8672 in seconds. Default is 0.
8679 Apply color adjustments using curves.
8681 This filter is similar to the Adobe Photoshop and GIMP curves tools. Each
8682 component (red, green and blue) has its values defined by @var{N} key points
8683 tied from each other using a smooth curve. The x-axis represents the pixel
8684 values from the input frame, and the y-axis the new pixel values to be set for
8687 By default, a component curve is defined by the two points @var{(0;0)} and
8688 @var{(1;1)}. This creates a straight line where each original pixel value is
8689 "adjusted" to its own value, which means no change to the image.
8691 The filter allows you to redefine these two points and add some more. A new
8692 curve (using a natural cubic spline interpolation) will be define to pass
8693 smoothly through all these new coordinates. The new defined points needs to be
8694 strictly increasing over the x-axis, and their @var{x} and @var{y} values must
8695 be in the @var{[0;1]} interval. If the computed curves happened to go outside
8696 the vector spaces, the values will be clipped accordingly.
8698 The filter accepts the following options:
8702 Select one of the available color presets. This option can be used in addition
8703 to the @option{r}, @option{g}, @option{b} parameters; in this case, the later
8704 options takes priority on the preset values.
8705 Available presets are:
8708 @item color_negative
8711 @item increase_contrast
8713 @item linear_contrast
8714 @item medium_contrast
8716 @item strong_contrast
8719 Default is @code{none}.
8721 Set the master key points. These points will define a second pass mapping. It
8722 is sometimes called a "luminance" or "value" mapping. It can be used with
8723 @option{r}, @option{g}, @option{b} or @option{all} since it acts like a
8724 post-processing LUT.
8726 Set the key points for the red component.
8728 Set the key points for the green component.
8730 Set the key points for the blue component.
8732 Set the key points for all components (not including master).
8733 Can be used in addition to the other key points component
8734 options. In this case, the unset component(s) will fallback on this
8735 @option{all} setting.
8737 Specify a Photoshop curves file (@code{.acv}) to import the settings from.
8739 Save Gnuplot script of the curves in specified file.
8742 To avoid some filtergraph syntax conflicts, each key points list need to be
8743 defined using the following syntax: @code{x0/y0 x1/y1 x2/y2 ...}.
8745 @subsection Examples
8749 Increase slightly the middle level of blue:
8751 curves=blue='0/0 0.5/0.58 1/1'
8757 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'
8759 Here we obtain the following coordinates for each components:
8762 @code{(0;0.11) (0.42;0.51) (1;0.95)}
8764 @code{(0;0) (0.50;0.48) (1;1)}
8766 @code{(0;0.22) (0.49;0.44) (1;0.80)}
8770 The previous example can also be achieved with the associated built-in preset:
8772 curves=preset=vintage
8782 Use a Photoshop preset and redefine the points of the green component:
8784 curves=psfile='MyCurvesPresets/purple.acv':green='0/0 0.45/0.53 1/1'
8788 Check out the curves of the @code{cross_process} profile using @command{ffmpeg}
8789 and @command{gnuplot}:
8791 ffmpeg -f lavfi -i color -vf curves=cross_process:plot=/tmp/curves.plt -frames:v 1 -f null -
8792 gnuplot -p /tmp/curves.plt
8798 Video data analysis filter.
8800 This filter shows hexadecimal pixel values of part of video.
8802 The filter accepts the following options:
8806 Set output video size.
8809 Set x offset from where to pick pixels.
8812 Set y offset from where to pick pixels.
8815 Set scope mode, can be one of the following:
8818 Draw hexadecimal pixel values with white color on black background.
8821 Draw hexadecimal pixel values with input video pixel color on black
8825 Draw hexadecimal pixel values on color background picked from input video,
8826 the text color is picked in such way so its always visible.
8830 Draw rows and columns numbers on left and top of video.
8833 Set background opacity.
8836 Set display number format. Can be @code{hex}, or @code{dec}. Default is @code{hex}.
8840 Apply Directional blur filter.
8842 The filter accepts the following options:
8846 Set angle of directional blur. Default is @code{45}.
8849 Set radius of directional blur. Default is @code{5}.
8852 Set which planes to filter. By default all planes are filtered.
8855 @subsection Commands
8856 This filter supports same @ref{commands} as options.
8857 The command accepts the same syntax of the corresponding option.
8859 If the specified expression is not valid, it is kept at its current
8864 Denoise frames using 2D DCT (frequency domain filtering).
8866 This filter is not designed for real time.
8868 The filter accepts the following options:
8872 Set the noise sigma constant.
8874 This @var{sigma} defines a hard threshold of @code{3 * sigma}; every DCT
8875 coefficient (absolute value) below this threshold with be dropped.
8877 If you need a more advanced filtering, see @option{expr}.
8879 Default is @code{0}.
8882 Set number overlapping pixels for each block. Since the filter can be slow, you
8883 may want to reduce this value, at the cost of a less effective filter and the
8884 risk of various artefacts.
8886 If the overlapping value doesn't permit processing the whole input width or
8887 height, a warning will be displayed and according borders won't be denoised.
8889 Default value is @var{blocksize}-1, which is the best possible setting.
8892 Set the coefficient factor expression.
8894 For each coefficient of a DCT block, this expression will be evaluated as a
8895 multiplier value for the coefficient.
8897 If this is option is set, the @option{sigma} option will be ignored.
8899 The absolute value of the coefficient can be accessed through the @var{c}
8903 Set the @var{blocksize} using the number of bits. @code{1<<@var{n}} defines the
8904 @var{blocksize}, which is the width and height of the processed blocks.
8906 The default value is @var{3} (8x8) and can be raised to @var{4} for a
8907 @var{blocksize} of 16x16. Note that changing this setting has huge consequences
8908 on the speed processing. Also, a larger block size does not necessarily means a
8912 @subsection Examples
8914 Apply a denoise with a @option{sigma} of @code{4.5}:
8919 The same operation can be achieved using the expression system:
8921 dctdnoiz=e='gte(c, 4.5*3)'
8924 Violent denoise using a block size of @code{16x16}:
8931 Remove banding artifacts from input video.
8932 It works by replacing banded pixels with average value of referenced pixels.
8934 The filter accepts the following options:
8941 Set banding detection threshold for each plane. Default is 0.02.
8942 Valid range is 0.00003 to 0.5.
8943 If difference between current pixel and reference pixel is less than threshold,
8944 it will be considered as banded.
8947 Banding detection range in pixels. Default is 16. If positive, random number
8948 in range 0 to set value will be used. If negative, exact absolute value
8950 The range defines square of four pixels around current pixel.
8953 Set direction in radians from which four pixel will be compared. If positive,
8954 random direction from 0 to set direction will be picked. If negative, exact of
8955 absolute value will be picked. For example direction 0, -PI or -2*PI radians
8956 will pick only pixels on same row and -PI/2 will pick only pixels on same
8960 If enabled, current pixel is compared with average value of all four
8961 surrounding pixels. The default is enabled. If disabled current pixel is
8962 compared with all four surrounding pixels. The pixel is considered banded
8963 if only all four differences with surrounding pixels are less than threshold.
8966 If enabled, current pixel is changed if and only if all pixel components are banded,
8967 e.g. banding detection threshold is triggered for all color components.
8968 The default is disabled.
8973 Remove blocking artifacts from input video.
8975 The filter accepts the following options:
8979 Set filter type, can be @var{weak} or @var{strong}. Default is @var{strong}.
8980 This controls what kind of deblocking is applied.
8983 Set size of block, allowed range is from 4 to 512. Default is @var{8}.
8989 Set blocking detection thresholds. Allowed range is 0 to 1.
8990 Defaults are: @var{0.098} for @var{alpha} and @var{0.05} for the rest.
8991 Using higher threshold gives more deblocking strength.
8992 Setting @var{alpha} controls threshold detection at exact edge of block.
8993 Remaining options controls threshold detection near the edge. Each one for
8994 below/above or left/right. Setting any of those to @var{0} disables
8998 Set planes to filter. Default is to filter all available planes.
9001 @subsection Examples
9005 Deblock using weak filter and block size of 4 pixels.
9007 deblock=filter=weak:block=4
9011 Deblock using strong filter, block size of 4 pixels and custom thresholds for
9012 deblocking more edges.
9014 deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05
9018 Similar as above, but filter only first plane.
9020 deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=1
9024 Similar as above, but filter only second and third plane.
9026 deblock=filter=strong:block=4:alpha=0.12:beta=0.07:gamma=0.06:delta=0.05:planes=6
9033 Drop duplicated frames at regular intervals.
9035 The filter accepts the following options:
9039 Set the number of frames from which one will be dropped. Setting this to
9040 @var{N} means one frame in every batch of @var{N} frames will be dropped.
9041 Default is @code{5}.
9044 Set the threshold for duplicate detection. If the difference metric for a frame
9045 is less than or equal to this value, then it is declared as duplicate. Default
9049 Set scene change threshold. Default is @code{15}.
9053 Set the size of the x and y-axis blocks used during metric calculations.
9054 Larger blocks give better noise suppression, but also give worse detection of
9055 small movements. Must be a power of two. Default is @code{32}.
9058 Mark main input as a pre-processed input and activate clean source input
9059 stream. This allows the input to be pre-processed with various filters to help
9060 the metrics calculation while keeping the frame selection lossless. When set to
9061 @code{1}, the first stream is for the pre-processed input, and the second
9062 stream is the clean source from where the kept frames are chosen. Default is
9066 Set whether or not chroma is considered in the metric calculations. Default is
9072 Apply 2D deconvolution of video stream in frequency domain using second stream
9075 The filter accepts the following options:
9079 Set which planes to process.
9082 Set which impulse video frames will be processed, can be @var{first}
9083 or @var{all}. Default is @var{all}.
9086 Set noise when doing divisions. Default is @var{0.0000001}. Useful when width
9087 and height are not same and not power of 2 or if stream prior to convolving
9091 The @code{deconvolve} filter also supports the @ref{framesync} options.
9095 Reduce cross-luminance (dot-crawl) and cross-color (rainbows) from video.
9097 It accepts the following options:
9101 Set mode of operation. Can be combination of @var{dotcrawl} for cross-luminance reduction and/or
9102 @var{rainbows} for cross-color reduction.
9105 Set spatial luma threshold. Lower values increases reduction of cross-luminance.
9108 Set tolerance for temporal luma. Higher values increases reduction of cross-luminance.
9111 Set tolerance for chroma temporal variation. Higher values increases reduction of cross-color.
9114 Set temporal chroma threshold. Lower values increases reduction of cross-color.
9119 Apply deflate effect to the video.
9121 This filter replaces the pixel by the local(3x3) average by taking into account
9122 only values lower than the pixel.
9124 It accepts the following options:
9131 Limit the maximum change for each plane, default is 65535.
9132 If 0, plane will remain unchanged.
9135 @subsection Commands
9137 This filter supports the all above options as @ref{commands}.
9141 Remove temporal frame luminance variations.
9143 It accepts the following options:
9147 Set moving-average filter size in frames. Default is 5. Allowed range is 2 - 129.
9150 Set averaging mode to smooth temporal luminance variations.
9152 Available values are:
9177 Do not actually modify frame. Useful when one only wants metadata.
9182 Remove judder produced by partially interlaced telecined content.
9184 Judder can be introduced, for instance, by @ref{pullup} filter. If the original
9185 source was partially telecined content then the output of @code{pullup,dejudder}
9186 will have a variable frame rate. May change the recorded frame rate of the
9187 container. Aside from that change, this filter will not affect constant frame
9190 The option available in this filter is:
9194 Specify the length of the window over which the judder repeats.
9196 Accepts any integer greater than 1. Useful values are:
9200 If the original was telecined from 24 to 30 fps (Film to NTSC).
9203 If the original was telecined from 25 to 30 fps (PAL to NTSC).
9206 If a mixture of the two.
9209 The default is @samp{4}.
9214 Suppress a TV station logo by a simple interpolation of the surrounding
9215 pixels. Just set a rectangle covering the logo and watch it disappear
9216 (and sometimes something even uglier appear - your mileage may vary).
9218 It accepts the following parameters:
9223 Specify the top left corner coordinates of the logo. They must be
9228 Specify the width and height of the logo to clear. They must be
9232 Specify the thickness of the fuzzy edge of the rectangle (added to
9233 @var{w} and @var{h}). The default value is 1. This option is
9234 deprecated, setting higher values should no longer be necessary and
9238 When set to 1, a green rectangle is drawn on the screen to simplify
9239 finding the right @var{x}, @var{y}, @var{w}, and @var{h} parameters.
9240 The default value is 0.
9242 The rectangle is drawn on the outermost pixels which will be (partly)
9243 replaced with interpolated values. The values of the next pixels
9244 immediately outside this rectangle in each direction will be used to
9245 compute the interpolated pixel values inside the rectangle.
9249 @subsection Examples
9253 Set a rectangle covering the area with top left corner coordinates 0,0
9254 and size 100x77, and a band of size 10:
9256 delogo=x=0:y=0:w=100:h=77:band=10
9264 Remove the rain in the input image/video by applying the derain methods based on
9265 convolutional neural networks. Supported models:
9269 Recurrent Squeeze-and-Excitation Context Aggregation Net (RESCAN).
9270 See @url{http://openaccess.thecvf.com/content_ECCV_2018/papers/Xia_Li_Recurrent_Squeeze-and-Excitation_Context_ECCV_2018_paper.pdf}.
9273 Training as well as model generation scripts are provided in
9274 the repository at @url{https://github.com/XueweiMeng/derain_filter.git}.
9276 Native model files (.model) can be generated from TensorFlow model
9277 files (.pb) by using tools/python/convert.py
9279 The filter accepts the following options:
9283 Specify which filter to use. This option accepts the following values:
9287 Derain filter. To conduct derain filter, you need to use a derain model.
9290 Dehaze filter. To conduct dehaze filter, you need to use a dehaze model.
9292 Default value is @samp{derain}.
9295 Specify which DNN backend to use for model loading and execution. This option accepts
9296 the following values:
9300 Native implementation of DNN loading and execution.
9303 TensorFlow backend. To enable this backend you
9304 need to install the TensorFlow for C library (see
9305 @url{https://www.tensorflow.org/install/install_c}) and configure FFmpeg with
9306 @code{--enable-libtensorflow}
9308 Default value is @samp{native}.
9311 Set path to model file specifying network architecture and its parameters.
9312 Note that different backends use different file formats. TensorFlow and native
9313 backend can load files for only its format.
9316 It can also be finished with @ref{dnn_processing} filter.
9320 Attempt to fix small changes in horizontal and/or vertical shift. This
9321 filter helps remove camera shake from hand-holding a camera, bumping a
9322 tripod, moving on a vehicle, etc.
9324 The filter accepts the following options:
9332 Specify a rectangular area where to limit the search for motion
9334 If desired the search for motion vectors can be limited to a
9335 rectangular area of the frame defined by its top left corner, width
9336 and height. These parameters have the same meaning as the drawbox
9337 filter which can be used to visualise the position of the bounding
9340 This is useful when simultaneous movement of subjects within the frame
9341 might be confused for camera motion by the motion vector search.
9343 If any or all of @var{x}, @var{y}, @var{w} and @var{h} are set to -1
9344 then the full frame is used. This allows later options to be set
9345 without specifying the bounding box for the motion vector search.
9347 Default - search the whole frame.
9351 Specify the maximum extent of movement in x and y directions in the
9352 range 0-64 pixels. Default 16.
9355 Specify how to generate pixels to fill blanks at the edge of the
9356 frame. Available values are:
9359 Fill zeroes at blank locations
9361 Original image at blank locations
9363 Extruded edge value at blank locations
9365 Mirrored edge at blank locations
9367 Default value is @samp{mirror}.
9370 Specify the blocksize to use for motion search. Range 4-128 pixels,
9374 Specify the contrast threshold for blocks. Only blocks with more than
9375 the specified contrast (difference between darkest and lightest
9376 pixels) will be considered. Range 1-255, default 125.
9379 Specify the search strategy. Available values are:
9382 Set exhaustive search
9384 Set less exhaustive search.
9386 Default value is @samp{exhaustive}.
9389 If set then a detailed log of the motion search is written to the
9396 Remove unwanted contamination of foreground colors, caused by reflected color of
9397 greenscreen or bluescreen.
9399 This filter accepts the following options:
9403 Set what type of despill to use.
9406 Set how spillmap will be generated.
9409 Set how much to get rid of still remaining spill.
9412 Controls amount of red in spill area.
9415 Controls amount of green in spill area.
9416 Should be -1 for greenscreen.
9419 Controls amount of blue in spill area.
9420 Should be -1 for bluescreen.
9423 Controls brightness of spill area, preserving colors.
9426 Modify alpha from generated spillmap.
9429 @subsection Commands
9431 This filter supports the all above options as @ref{commands}.
9435 Apply an exact inverse of the telecine operation. It requires a predefined
9436 pattern specified using the pattern option which must be the same as that passed
9437 to the telecine filter.
9439 This filter accepts the following options:
9448 The default value is @code{top}.
9452 A string of numbers representing the pulldown pattern you wish to apply.
9453 The default value is @code{23}.
9456 A number representing position of the first frame with respect to the telecine
9457 pattern. This is to be used if the stream is cut. The default value is @code{0}.
9462 Apply dilation effect to the video.
9464 This filter replaces the pixel by the local(3x3) maximum.
9466 It accepts the following options:
9473 Limit the maximum change for each plane, default is 65535.
9474 If 0, plane will remain unchanged.
9477 Flag which specifies the pixel to refer to. Default is 255 i.e. all eight
9480 Flags to local 3x3 coordinates maps like this:
9487 @subsection Commands
9489 This filter supports the all above options as @ref{commands}.
9493 Displace pixels as indicated by second and third input stream.
9495 It takes three input streams and outputs one stream, the first input is the
9496 source, and second and third input are displacement maps.
9498 The second input specifies how much to displace pixels along the
9499 x-axis, while the third input specifies how much to displace pixels
9501 If one of displacement map streams terminates, last frame from that
9502 displacement map will be used.
9504 Note that once generated, displacements maps can be reused over and over again.
9506 A description of the accepted options follows.
9510 Set displace behavior for pixels that are out of range.
9512 Available values are:
9515 Missing pixels are replaced by black pixels.
9518 Adjacent pixels will spread out to replace missing pixels.
9521 Out of range pixels are wrapped so they point to pixels of other side.
9524 Out of range pixels will be replaced with mirrored pixels.
9526 Default is @samp{smear}.
9530 @subsection Examples
9534 Add ripple effect to rgb input of video size hd720:
9536 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
9540 Add wave effect to rgb input of video size hd720:
9542 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
9546 @anchor{dnn_processing}
9547 @section dnn_processing
9549 Do image processing with deep neural networks. It works together with another filter
9550 which converts the pixel format of the Frame to what the dnn network requires.
9552 The filter accepts the following options:
9556 Specify which DNN backend to use for model loading and execution. This option accepts
9557 the following values:
9561 Native implementation of DNN loading and execution.
9564 TensorFlow backend. To enable this backend you
9565 need to install the TensorFlow for C library (see
9566 @url{https://www.tensorflow.org/install/install_c}) and configure FFmpeg with
9567 @code{--enable-libtensorflow}
9570 OpenVINO backend. To enable this backend you
9571 need to build and install the OpenVINO for C library (see
9572 @url{https://github.com/openvinotoolkit/openvino/blob/master/build-instruction.md}) and configure FFmpeg with
9573 @code{--enable-libopenvino} (--extra-cflags=-I... --extra-ldflags=-L... might
9574 be needed if the header files and libraries are not installed into system path)
9578 Default value is @samp{native}.
9581 Set path to model file specifying network architecture and its parameters.
9582 Note that different backends use different file formats. TensorFlow, OpenVINO and native
9583 backend can load files for only its format.
9585 Native model file (.model) can be generated from TensorFlow model file (.pb) by using tools/python/convert.py
9588 Set the input name of the dnn network.
9591 Set the output name of the dnn network.
9595 @subsection Examples
9599 Remove rain in rgb24 frame with can.pb (see @ref{derain} filter):
9601 ./ffmpeg -i rain.jpg -vf format=rgb24,dnn_processing=dnn_backend=tensorflow:model=can.pb:input=x:output=y derain.jpg
9605 Halve the pixel value of the frame with format gray32f:
9607 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
9611 Handle the Y channel with srcnn.pb (see @ref{sr} filter) for frame with yuv420p (planar YUV formats supported):
9613 ./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
9617 Handle the Y channel with espcn.pb (see @ref{sr} filter), which changes frame size, for format yuv420p (planar YUV formats supported):
9619 ./ffmpeg -i 480p.jpg -vf format=yuv420p,dnn_processing=dnn_backend=tensorflow:model=espcn.pb:input=x:output=y -y tmp.espcn.jpg
9626 Draw a colored box on the input image.
9628 It accepts the following parameters:
9633 The expressions which specify the top left corner coordinates of the box. It defaults to 0.
9637 The expressions which specify the width and height of the box; if 0 they are interpreted as
9638 the input width and height. It defaults to 0.
9641 Specify the color of the box to write. For the general syntax of this option,
9642 check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. If the special
9643 value @code{invert} is used, the box edge color is the same as the
9644 video with inverted luma.
9647 The expression which sets the thickness of the box edge.
9648 A value of @code{fill} will create a filled box. Default value is @code{3}.
9650 See below for the list of accepted constants.
9653 Applicable if the input has alpha. With value @code{1}, the pixels of the painted box
9654 will overwrite the video's color and alpha pixels.
9655 Default is @code{0}, which composites the box onto the input, leaving the video's alpha intact.
9658 The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
9659 following constants:
9663 The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
9667 horizontal and vertical chroma subsample values. For example for the
9668 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
9672 The input width and height.
9675 The input sample aspect ratio.
9679 The x and y offset coordinates where the box is drawn.
9683 The width and height of the drawn box.
9686 The thickness of the drawn box.
9688 These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
9689 each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
9693 @subsection Examples
9697 Draw a black box around the edge of the input image:
9703 Draw a box with color red and an opacity of 50%:
9705 drawbox=10:20:200:60:red@@0.5
9708 The previous example can be specified as:
9710 drawbox=x=10:y=20:w=200:h=60:color=red@@0.5
9714 Fill the box with pink color:
9716 drawbox=x=10:y=10:w=100:h=100:color=pink@@0.5:t=fill
9720 Draw a 2-pixel red 2.40:1 mask:
9722 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
9726 @subsection Commands
9727 This filter supports same commands as options.
9728 The command accepts the same syntax of the corresponding option.
9730 If the specified expression is not valid, it is kept at its current
9735 Draw a graph using input video metadata.
9737 It accepts the following parameters:
9741 Set 1st frame metadata key from which metadata values will be used to draw a graph.
9744 Set 1st foreground color expression.
9747 Set 2nd frame metadata key from which metadata values will be used to draw a graph.
9750 Set 2nd foreground color expression.
9753 Set 3rd frame metadata key from which metadata values will be used to draw a graph.
9756 Set 3rd foreground color expression.
9759 Set 4th frame metadata key from which metadata values will be used to draw a graph.
9762 Set 4th foreground color expression.
9765 Set minimal value of metadata value.
9768 Set maximal value of metadata value.
9771 Set graph background color. Default is white.
9776 Available values for mode is:
9783 Default is @code{line}.
9788 Available values for slide is:
9791 Draw new frame when right border is reached.
9794 Replace old columns with new ones.
9797 Scroll from right to left.
9800 Scroll from left to right.
9803 Draw single picture.
9806 Default is @code{frame}.
9809 Set size of graph video. For the syntax of this option, check the
9810 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
9811 The default value is @code{900x256}.
9814 Set the output frame rate. Default value is @code{25}.
9816 The foreground color expressions can use the following variables:
9819 Minimal value of metadata value.
9822 Maximal value of metadata value.
9825 Current metadata key value.
9828 The color is defined as 0xAABBGGRR.
9831 Example using metadata from @ref{signalstats} filter:
9833 signalstats,drawgraph=lavfi.signalstats.YAVG:min=0:max=255
9836 Example using metadata from @ref{ebur128} filter:
9838 ebur128=metadata=1,adrawgraph=lavfi.r128.M:min=-120:max=5
9843 Draw a grid on the input image.
9845 It accepts the following parameters:
9850 The expressions which specify the coordinates of some point of grid intersection (meant to configure offset). Both default to 0.
9854 The expressions which specify the width and height of the grid cell, if 0 they are interpreted as the
9855 input width and height, respectively, minus @code{thickness}, so image gets
9856 framed. Default to 0.
9859 Specify the color of the grid. For the general syntax of this option,
9860 check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}. If the special
9861 value @code{invert} is used, the grid color is the same as the
9862 video with inverted luma.
9865 The expression which sets the thickness of the grid line. Default value is @code{1}.
9867 See below for the list of accepted constants.
9870 Applicable if the input has alpha. With @code{1} the pixels of the painted grid
9871 will overwrite the video's color and alpha pixels.
9872 Default is @code{0}, which composites the grid onto the input, leaving the video's alpha intact.
9875 The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
9876 following constants:
9880 The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
9884 horizontal and vertical chroma subsample values. For example for the
9885 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
9889 The input grid cell width and height.
9892 The input sample aspect ratio.
9896 The x and y coordinates of some point of grid intersection (meant to configure offset).
9900 The width and height of the drawn cell.
9903 The thickness of the drawn cell.
9905 These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
9906 each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
9910 @subsection Examples
9914 Draw a grid with cell 100x100 pixels, thickness 2 pixels, with color red and an opacity of 50%:
9916 drawgrid=width=100:height=100:thickness=2:color=red@@0.5
9920 Draw a white 3x3 grid with an opacity of 50%:
9922 drawgrid=w=iw/3:h=ih/3:t=2:c=white@@0.5
9926 @subsection Commands
9927 This filter supports same commands as options.
9928 The command accepts the same syntax of the corresponding option.
9930 If the specified expression is not valid, it is kept at its current
9936 Draw a text string or text from a specified file on top of a video, using the
9937 libfreetype library.
9939 To enable compilation of this filter, you need to configure FFmpeg with
9940 @code{--enable-libfreetype}.
9941 To enable default font fallback and the @var{font} option you need to
9942 configure FFmpeg with @code{--enable-libfontconfig}.
9943 To enable the @var{text_shaping} option, you need to configure FFmpeg with
9944 @code{--enable-libfribidi}.
9948 It accepts the following parameters:
9953 Used to draw a box around text using the background color.
9954 The value must be either 1 (enable) or 0 (disable).
9955 The default value of @var{box} is 0.
9958 Set the width of the border to be drawn around the box using @var{boxcolor}.
9959 The default value of @var{boxborderw} is 0.
9962 The color to be used for drawing box 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{boxcolor} is "white".
9968 Set the line spacing in pixels of the border to be drawn around the box using @var{box}.
9969 The default value of @var{line_spacing} is 0.
9972 Set the width of the border to be drawn around the text using @var{bordercolor}.
9973 The default value of @var{borderw} is 0.
9976 Set the color to be used for drawing border around text. For the syntax of this
9977 option, check the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
9979 The default value of @var{bordercolor} is "black".
9982 Select how the @var{text} is expanded. Can be either @code{none},
9983 @code{strftime} (deprecated) or
9984 @code{normal} (default). See the @ref{drawtext_expansion, Text expansion} section
9988 Set a start time for the count. Value is in microseconds. Only applied
9989 in the deprecated strftime expansion mode. To emulate in normal expansion
9990 mode use the @code{pts} function, supplying the start time (in seconds)
9991 as the second argument.
9994 If true, check and fix text coords to avoid clipping.
9997 The color to be used for drawing fonts. For the syntax of this option, check
9998 the @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
10000 The default value of @var{fontcolor} is "black".
10002 @item fontcolor_expr
10003 String which is expanded the same way as @var{text} to obtain dynamic
10004 @var{fontcolor} value. By default this option has empty value and is not
10005 processed. When this option is set, it overrides @var{fontcolor} option.
10008 The font family to be used for drawing text. By default Sans.
10011 The font file to be used for drawing text. The path must be included.
10012 This parameter is mandatory if the fontconfig support is disabled.
10015 Draw the text applying alpha blending. The value can
10016 be a number between 0.0 and 1.0.
10017 The expression accepts the same variables @var{x, y} as well.
10018 The default value is 1.
10019 Please see @var{fontcolor_expr}.
10022 The font size to be used for drawing text.
10023 The default value of @var{fontsize} is 16.
10026 If set to 1, attempt to shape the text (for example, reverse the order of
10027 right-to-left text and join Arabic characters) before drawing it.
10028 Otherwise, just draw the text exactly as given.
10029 By default 1 (if supported).
10031 @item ft_load_flags
10032 The flags to be used for loading the fonts.
10034 The flags map the corresponding flags supported by libfreetype, and are
10035 a combination of the following values:
10042 @item vertical_layout
10043 @item force_autohint
10046 @item ignore_global_advance_width
10048 @item ignore_transform
10050 @item linear_design
10054 Default value is "default".
10056 For more information consult the documentation for the FT_LOAD_*
10060 The color to be used for drawing a shadow behind the drawn text. For the
10061 syntax of this option, check the @ref{color syntax,,"Color" section in the
10062 ffmpeg-utils manual,ffmpeg-utils}.
10064 The default value of @var{shadowcolor} is "black".
10068 The x and y offsets for the text shadow position with respect to the
10069 position of the text. They can be either positive or negative
10070 values. The default value for both is "0".
10073 The starting frame number for the n/frame_num variable. The default value
10077 The size in number of spaces to use for rendering the tab.
10078 Default value is 4.
10081 Set the initial timecode representation in "hh:mm:ss[:;.]ff"
10082 format. It can be used with or without text parameter. @var{timecode_rate}
10083 option must be specified.
10085 @item timecode_rate, rate, r
10086 Set the timecode frame rate (timecode only). Value will be rounded to nearest
10087 integer. Minimum value is "1".
10088 Drop-frame timecode is supported for frame rates 30 & 60.
10091 If set to 1, the output of the timecode option will wrap around at 24 hours.
10092 Default is 0 (disabled).
10095 The text string to be drawn. The text must be a sequence of UTF-8
10096 encoded characters.
10097 This parameter is mandatory if no file is specified with the parameter
10101 A text file containing text to be drawn. The text must be a sequence
10102 of UTF-8 encoded characters.
10104 This parameter is mandatory if no text string is specified with the
10105 parameter @var{text}.
10107 If both @var{text} and @var{textfile} are specified, an error is thrown.
10110 If set to 1, the @var{textfile} will be reloaded before each frame.
10111 Be sure to update it atomically, or it may be read partially, or even fail.
10115 The expressions which specify the offsets where text will be drawn
10116 within the video frame. They are relative to the top/left border of the
10119 The default value of @var{x} and @var{y} is "0".
10121 See below for the list of accepted constants and functions.
10124 The parameters for @var{x} and @var{y} are expressions containing the
10125 following constants and functions:
10129 input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
10133 horizontal and vertical chroma subsample values. For example for the
10134 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
10137 the height of each text line
10145 @item max_glyph_a, ascent
10146 the maximum distance from the baseline to the highest/upper grid
10147 coordinate used to place a glyph outline point, for all the rendered
10149 It is a positive value, due to the grid's orientation with the Y axis
10152 @item max_glyph_d, descent
10153 the maximum distance from the baseline to the lowest grid coordinate
10154 used to place a glyph outline point, for all the rendered glyphs.
10155 This is a negative value, due to the grid's orientation, with the Y axis
10159 maximum glyph height, that is the maximum height for all the glyphs
10160 contained in the rendered text, it is equivalent to @var{ascent} -
10164 maximum glyph width, that is the maximum width for all the glyphs
10165 contained in the rendered text
10168 the number of input frame, starting from 0
10170 @item rand(min, max)
10171 return a random number included between @var{min} and @var{max}
10174 The input sample aspect ratio.
10177 timestamp expressed in seconds, NAN if the input timestamp is unknown
10180 the height of the rendered text
10183 the width of the rendered text
10187 the x and y offset coordinates where the text is drawn.
10189 These parameters allow the @var{x} and @var{y} expressions to refer
10190 to each other, so you can for example specify @code{y=x/dar}.
10193 A one character description of the current frame's picture type.
10196 The current packet's position in the input file or stream
10197 (in bytes, from the start of the input). A value of -1 indicates
10198 this info is not available.
10201 The current packet's duration, in seconds.
10204 The current packet's size (in bytes).
10207 @anchor{drawtext_expansion}
10208 @subsection Text expansion
10210 If @option{expansion} is set to @code{strftime},
10211 the filter recognizes strftime() sequences in the provided text and
10212 expands them accordingly. Check the documentation of strftime(). This
10213 feature is deprecated.
10215 If @option{expansion} is set to @code{none}, the text is printed verbatim.
10217 If @option{expansion} is set to @code{normal} (which is the default),
10218 the following expansion mechanism is used.
10220 The backslash character @samp{\}, followed by any character, always expands to
10221 the second character.
10223 Sequences of the form @code{%@{...@}} are expanded. The text between the
10224 braces is a function name, possibly followed by arguments separated by ':'.
10225 If the arguments contain special characters or delimiters (':' or '@}'),
10226 they should be escaped.
10228 Note that they probably must also be escaped as the value for the
10229 @option{text} option in the filter argument string and as the filter
10230 argument in the filtergraph description, and possibly also for the shell,
10231 that makes up to four levels of escaping; using a text file avoids these
10234 The following functions are available:
10239 The expression evaluation result.
10241 It must take one argument specifying the expression to be evaluated,
10242 which accepts the same constants and functions as the @var{x} and
10243 @var{y} values. Note that not all constants should be used, for
10244 example the text size is not known when evaluating the expression, so
10245 the constants @var{text_w} and @var{text_h} will have an undefined
10248 @item expr_int_format, eif
10249 Evaluate the expression's value and output as formatted integer.
10251 The first argument is the expression to be evaluated, just as for the @var{expr} function.
10252 The second argument specifies the output format. Allowed values are @samp{x},
10253 @samp{X}, @samp{d} and @samp{u}. They are treated exactly as in the
10254 @code{printf} function.
10255 The third parameter is optional and sets the number of positions taken by the output.
10256 It can be used to add padding with zeros from the left.
10259 The time at which the filter is running, expressed in UTC.
10260 It can accept an argument: a strftime() format string.
10263 The time at which the filter is running, expressed in the local time zone.
10264 It can accept an argument: a strftime() format string.
10267 Frame metadata. Takes one or two arguments.
10269 The first argument is mandatory and specifies the metadata key.
10271 The second argument is optional and specifies a default value, used when the
10272 metadata key is not found or empty.
10274 Available metadata can be identified by inspecting entries
10275 starting with TAG included within each frame section
10276 printed by running @code{ffprobe -show_frames}.
10278 String metadata generated in filters leading to
10279 the drawtext filter are also available.
10282 The frame number, starting from 0.
10285 A one character description of the current picture type.
10288 The timestamp of the current frame.
10289 It can take up to three arguments.
10291 The first argument is the format of the timestamp; it defaults to @code{flt}
10292 for seconds as a decimal number with microsecond accuracy; @code{hms} stands
10293 for a formatted @var{[-]HH:MM:SS.mmm} timestamp with millisecond accuracy.
10294 @code{gmtime} stands for the timestamp of the frame formatted as UTC time;
10295 @code{localtime} stands for the timestamp of the frame formatted as
10296 local time zone time.
10298 The second argument is an offset added to the timestamp.
10300 If the format is set to @code{hms}, a third argument @code{24HH} may be
10301 supplied to present the hour part of the formatted timestamp in 24h format
10304 If the format is set to @code{localtime} or @code{gmtime},
10305 a third argument may be supplied: a strftime() format string.
10306 By default, @var{YYYY-MM-DD HH:MM:SS} format will be used.
10309 @subsection Commands
10311 This filter supports altering parameters via commands:
10314 Alter existing filter parameters.
10316 Syntax for the argument is the same as for filter invocation, e.g.
10319 fontsize=56:fontcolor=green:text='Hello World'
10322 Full filter invocation with sendcmd would look like this:
10325 sendcmd=c='56.0 drawtext reinit fontsize=56\:fontcolor=green\:text=Hello\\ World'
10329 If the entire argument can't be parsed or applied as valid values then the filter will
10330 continue with its existing parameters.
10332 @subsection Examples
10336 Draw "Test Text" with font FreeSerif, using the default values for the
10337 optional parameters.
10340 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"
10344 Draw 'Test Text' with font FreeSerif of size 24 at position x=100
10345 and y=50 (counting from the top-left corner of the screen), text is
10346 yellow with a red box around it. Both the text and the box have an
10350 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
10351 x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2"
10354 Note that the double quotes are not necessary if spaces are not used
10355 within the parameter list.
10358 Show the text at the center of the video frame:
10360 drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h)/2"
10364 Show the text at a random position, switching to a new position every 30 seconds:
10366 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)"
10370 Show a text line sliding from right to left in the last row of the video
10371 frame. The file @file{LONG_LINE} is assumed to contain a single line
10374 drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t"
10378 Show the content of file @file{CREDITS} off the bottom of the frame and scroll up.
10380 drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t"
10384 Draw a single green letter "g", at the center of the input video.
10385 The glyph baseline is placed at half screen height.
10387 drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent"
10391 Show text for 1 second every 3 seconds:
10393 drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:enable=lt(mod(t\,3)\,1):text='blink'"
10397 Use fontconfig to set the font. Note that the colons need to be escaped.
10399 drawtext='fontfile=Linux Libertine O-40\:style=Semibold:text=FFmpeg'
10403 Draw "Test Text" with font size dependent on height of the video.
10405 drawtext="text='Test Text': fontsize=h/30: x=(w-text_w)/2: y=(h-text_h*2)"
10409 Print the date of a real-time encoding (see strftime(3)):
10411 drawtext='fontfile=FreeSans.ttf:text=%@{localtime\:%a %b %d %Y@}'
10415 Show text fading in and out (appearing/disappearing):
10418 DS=1.0 # display start
10419 DE=10.0 # display end
10420 FID=1.5 # fade in duration
10421 FOD=5 # fade out duration
10422 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 @}"
10426 Horizontally align multiple separate texts. Note that @option{max_glyph_a}
10427 and the @option{fontsize} value are included in the @option{y} offset.
10429 drawtext=fontfile=FreeSans.ttf:text=DOG:fontsize=24:x=10:y=20+24-max_glyph_a,
10430 drawtext=fontfile=FreeSans.ttf:text=cow:fontsize=24:x=80:y=20+24-max_glyph_a
10434 Plot special @var{lavf.image2dec.source_basename} metadata onto each frame if
10435 such metadata exists. Otherwise, plot the string "NA". Note that image2 demuxer
10436 must have option @option{-export_path_metadata 1} for the special metadata fields
10437 to be available for filters.
10439 drawtext="fontsize=20:fontcolor=white:fontfile=FreeSans.ttf:text='%@{metadata\:lavf.image2dec.source_basename\:NA@}':x=10:y=10"
10444 For more information about libfreetype, check:
10445 @url{http://www.freetype.org/}.
10447 For more information about fontconfig, check:
10448 @url{http://freedesktop.org/software/fontconfig/fontconfig-user.html}.
10450 For more information about libfribidi, check:
10451 @url{http://fribidi.org/}.
10453 @section edgedetect
10455 Detect and draw edges. The filter uses the Canny Edge Detection algorithm.
10457 The filter accepts the following options:
10462 Set low and high threshold values used by the Canny thresholding
10465 The high threshold selects the "strong" edge pixels, which are then
10466 connected through 8-connectivity with the "weak" edge pixels selected
10467 by the low threshold.
10469 @var{low} and @var{high} threshold values must be chosen in the range
10470 [0,1], and @var{low} should be lesser or equal to @var{high}.
10472 Default value for @var{low} is @code{20/255}, and default value for @var{high}
10476 Define the drawing mode.
10480 Draw white/gray wires on black background.
10483 Mix the colors to create a paint/cartoon effect.
10486 Apply Canny edge detector on all selected planes.
10488 Default value is @var{wires}.
10491 Select planes for filtering. By default all available planes are filtered.
10494 @subsection Examples
10498 Standard edge detection with custom values for the hysteresis thresholding:
10500 edgedetect=low=0.1:high=0.4
10504 Painting effect without thresholding:
10506 edgedetect=mode=colormix:high=0
10512 Apply a posterize effect using the ELBG (Enhanced LBG) algorithm.
10514 For each input image, the filter will compute the optimal mapping from
10515 the input to the output given the codebook length, that is the number
10516 of distinct output colors.
10518 This filter accepts the following options.
10521 @item codebook_length, l
10522 Set codebook length. The value must be a positive integer, and
10523 represents the number of distinct output colors. Default value is 256.
10526 Set the maximum number of iterations to apply for computing the optimal
10527 mapping. The higher the value the better the result and the higher the
10528 computation time. Default value is 1.
10531 Set a random seed, must be an integer included between 0 and
10532 UINT32_MAX. If not specified, or if explicitly set to -1, the filter
10533 will try to use a good random seed on a best effort basis.
10536 Set pal8 output pixel format. This option does not work with codebook
10537 length greater than 256.
10542 Measure graylevel entropy in histogram of color channels of video frames.
10544 It accepts the following parameters:
10548 Can be either @var{normal} or @var{diff}. Default is @var{normal}.
10550 @var{diff} mode measures entropy of histogram delta values, absolute differences
10551 between neighbour histogram values.
10555 Set brightness, contrast, saturation and approximate gamma adjustment.
10557 The filter accepts the following options:
10561 Set the contrast expression. The value must be a float value in range
10562 @code{-1000.0} to @code{1000.0}. The default value is "1".
10565 Set the brightness expression. The value must be a float value in
10566 range @code{-1.0} to @code{1.0}. The default value is "0".
10569 Set the saturation expression. The value must be a float in
10570 range @code{0.0} to @code{3.0}. The default value is "1".
10573 Set the gamma expression. The value must be a float in range
10574 @code{0.1} to @code{10.0}. The default value is "1".
10577 Set the gamma expression for red. The value must be a float in
10578 range @code{0.1} to @code{10.0}. The default value is "1".
10581 Set the gamma expression for green. The value must be a float in range
10582 @code{0.1} to @code{10.0}. The default value is "1".
10585 Set the gamma expression for blue. The value must be a float in range
10586 @code{0.1} to @code{10.0}. The default value is "1".
10589 Set the gamma weight expression. It can be used to reduce the effect
10590 of a high gamma value on bright image areas, e.g. keep them from
10591 getting overamplified and just plain white. The value must be a float
10592 in range @code{0.0} to @code{1.0}. A value of @code{0.0} turns the
10593 gamma correction all the way down while @code{1.0} leaves it at its
10594 full strength. Default is "1".
10597 Set when the expressions for brightness, contrast, saturation and
10598 gamma expressions are evaluated.
10600 It accepts the following values:
10603 only evaluate expressions once during the filter initialization or
10604 when a command is processed
10607 evaluate expressions for each incoming frame
10610 Default value is @samp{init}.
10613 The expressions accept the following parameters:
10616 frame count of the input frame starting from 0
10619 byte position of the corresponding packet in the input file, NAN if
10623 frame rate of the input video, NAN if the input frame rate is unknown
10626 timestamp expressed in seconds, NAN if the input timestamp is unknown
10629 @subsection Commands
10630 The filter supports the following commands:
10634 Set the contrast expression.
10637 Set the brightness expression.
10640 Set the saturation expression.
10643 Set the gamma expression.
10646 Set the gamma_r expression.
10649 Set gamma_g expression.
10652 Set gamma_b expression.
10655 Set gamma_weight expression.
10657 The command accepts the same syntax of the corresponding option.
10659 If the specified expression is not valid, it is kept at its current
10666 Apply erosion effect to the video.
10668 This filter replaces the pixel by the local(3x3) minimum.
10670 It accepts the following options:
10677 Limit the maximum change for each plane, default is 65535.
10678 If 0, plane will remain unchanged.
10681 Flag which specifies the pixel to refer to. Default is 255 i.e. all eight
10684 Flags to local 3x3 coordinates maps like this:
10691 @subsection Commands
10693 This filter supports the all above options as @ref{commands}.
10695 @section extractplanes
10697 Extract color channel components from input video stream into
10698 separate grayscale video streams.
10700 The filter accepts the following option:
10704 Set plane(s) to extract.
10706 Available values for planes are:
10717 Choosing planes not available in the input will result in an error.
10718 That means you cannot select @code{r}, @code{g}, @code{b} planes
10719 with @code{y}, @code{u}, @code{v} planes at same time.
10722 @subsection Examples
10726 Extract luma, u and v color channel component from input video frame
10727 into 3 grayscale outputs:
10729 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
10735 Apply a fade-in/out effect to the input video.
10737 It accepts the following parameters:
10741 The effect type can be either "in" for a fade-in, or "out" for a fade-out
10743 Default is @code{in}.
10745 @item start_frame, s
10746 Specify the number of the frame to start applying the fade
10747 effect at. Default is 0.
10750 The number of frames that the fade effect lasts. At the end of the
10751 fade-in effect, the output video will have the same intensity as the input video.
10752 At the end of the fade-out transition, the output video will be filled with the
10753 selected @option{color}.
10757 If set to 1, fade only alpha channel, if one exists on the input.
10758 Default value is 0.
10760 @item start_time, st
10761 Specify the timestamp (in seconds) of the frame to start to apply the fade
10762 effect. If both start_frame and start_time are specified, the fade will start at
10763 whichever comes last. Default is 0.
10766 The number of seconds for which the fade effect has to last. At the end of the
10767 fade-in effect the output video will have the same intensity as the input video,
10768 at the end of the fade-out transition the output video will be filled with the
10769 selected @option{color}.
10770 If both duration and nb_frames are specified, duration is used. Default is 0
10771 (nb_frames is used by default).
10774 Specify the color of the fade. Default is "black".
10777 @subsection Examples
10781 Fade in the first 30 frames of video:
10786 The command above is equivalent to:
10792 Fade out the last 45 frames of a 200-frame video:
10795 fade=type=out:start_frame=155:nb_frames=45
10799 Fade in the first 25 frames and fade out the last 25 frames of a 1000-frame video:
10801 fade=in:0:25, fade=out:975:25
10805 Make the first 5 frames yellow, then fade in from frame 5-24:
10807 fade=in:5:20:color=yellow
10811 Fade in alpha over first 25 frames of video:
10813 fade=in:0:25:alpha=1
10817 Make the first 5.5 seconds black, then fade in for 0.5 seconds:
10819 fade=t=in:st=5.5:d=0.5
10825 Denoise frames using 3D FFT (frequency domain filtering).
10827 The filter accepts the following options:
10831 Set the noise sigma constant. This sets denoising strength.
10832 Default value is 1. Allowed range is from 0 to 30.
10833 Using very high sigma with low overlap may give blocking artifacts.
10836 Set amount of denoising. By default all detected noise is reduced.
10837 Default value is 1. Allowed range is from 0 to 1.
10840 Set size of block, Default is 4, can be 3, 4, 5 or 6.
10841 Actual size of block in pixels is 2 to power of @var{block}, so by default
10842 block size in pixels is 2^4 which is 16.
10845 Set block overlap. Default is 0.5. Allowed range is from 0.2 to 0.8.
10848 Set number of previous frames to use for denoising. By default is set to 0.
10851 Set number of next frames to to use for denoising. By default is set to 0.
10854 Set planes which will be filtered, by default are all available filtered
10859 Apply arbitrary expressions to samples in frequency domain
10863 Adjust the dc value (gain) of the luma plane of the image. The filter
10864 accepts an integer value in range @code{0} to @code{1000}. The default
10865 value is set to @code{0}.
10868 Adjust the dc value (gain) of the 1st chroma plane of the image. The
10869 filter accepts an integer value in range @code{0} to @code{1000}. The
10870 default value is set to @code{0}.
10873 Adjust the dc value (gain) of the 2nd chroma plane of the image. The
10874 filter accepts an integer value in range @code{0} to @code{1000}. The
10875 default value is set to @code{0}.
10878 Set the frequency domain weight expression for the luma plane.
10881 Set the frequency domain weight expression for the 1st chroma plane.
10884 Set the frequency domain weight expression for the 2nd chroma plane.
10887 Set when the expressions are evaluated.
10889 It accepts the following values:
10892 Only evaluate expressions once during the filter initialization.
10895 Evaluate expressions for each incoming frame.
10898 Default value is @samp{init}.
10900 The filter accepts the following variables:
10903 The coordinates of the current sample.
10907 The width and height of the image.
10910 The number of input frame, starting from 0.
10913 @subsection Examples
10919 fftfilt=dc_Y=128:weight_Y='squish(1-(Y+X)/100)'
10925 fftfilt=dc_Y=0:weight_Y='squish((Y+X)/100-1)'
10931 fftfilt=dc_Y=0:weight_Y='1+squish(1-(Y+X)/100)'
10937 fftfilt=dc_Y=0:weight_Y='exp(-4 * ((Y+X)/(W+H)))'
10944 Extract a single field from an interlaced image using stride
10945 arithmetic to avoid wasting CPU time. The output frames are marked as
10948 The filter accepts the following options:
10952 Specify whether to extract the top (if the value is @code{0} or
10953 @code{top}) or the bottom field (if the value is @code{1} or
10959 Create new frames by copying the top and bottom fields from surrounding frames
10960 supplied as numbers by the hint file.
10964 Set file containing hints: absolute/relative frame numbers.
10966 There must be one line for each frame in a clip. Each line must contain two
10967 numbers separated by the comma, optionally followed by @code{-} or @code{+}.
10968 Numbers supplied on each line of file can not be out of [N-1,N+1] where N
10969 is current frame number for @code{absolute} mode or out of [-1, 1] range
10970 for @code{relative} mode. First number tells from which frame to pick up top
10971 field and second number tells from which frame to pick up bottom field.
10973 If optionally followed by @code{+} output frame will be marked as interlaced,
10974 else if followed by @code{-} output frame will be marked as progressive, else
10975 it will be marked same as input frame.
10976 If optionally followed by @code{t} output frame will use only top field, or in
10977 case of @code{b} it will use only bottom field.
10978 If line starts with @code{#} or @code{;} that line is skipped.
10981 Can be item @code{absolute} or @code{relative}. Default is @code{absolute}.
10984 Example of first several lines of @code{hint} file for @code{relative} mode:
10986 0,0 - # first frame
10987 1,0 - # second frame, use third's frame top field and second's frame bottom field
10988 1,0 - # third frame, use fourth's frame top field and third's frame bottom field
11003 @section fieldmatch
11005 Field matching filter for inverse telecine. It is meant to reconstruct the
11006 progressive frames from a telecined stream. The filter does not drop duplicated
11007 frames, so to achieve a complete inverse telecine @code{fieldmatch} needs to be
11008 followed by a decimation filter such as @ref{decimate} in the filtergraph.
11010 The separation of the field matching and the decimation is notably motivated by
11011 the possibility of inserting a de-interlacing filter fallback between the two.
11012 If the source has mixed telecined and real interlaced content,
11013 @code{fieldmatch} will not be able to match fields for the interlaced parts.
11014 But these remaining combed frames will be marked as interlaced, and thus can be
11015 de-interlaced by a later filter such as @ref{yadif} before decimation.
11017 In addition to the various configuration options, @code{fieldmatch} can take an
11018 optional second stream, activated through the @option{ppsrc} option. If
11019 enabled, the frames reconstruction will be based on the fields and frames from
11020 this second stream. This allows the first input to be pre-processed in order to
11021 help the various algorithms of the filter, while keeping the output lossless
11022 (assuming the fields are matched properly). Typically, a field-aware denoiser,
11023 or brightness/contrast adjustments can help.
11025 Note that this filter uses the same algorithms as TIVTC/TFM (AviSynth project)
11026 and VIVTC/VFM (VapourSynth project). The later is a light clone of TFM from
11027 which @code{fieldmatch} is based on. While the semantic and usage are very
11028 close, some behaviour and options names can differ.
11030 The @ref{decimate} filter currently only works for constant frame rate input.
11031 If your input has mixed telecined (30fps) and progressive content with a lower
11032 framerate like 24fps use the following filterchain to produce the necessary cfr
11033 stream: @code{dejudder,fps=30000/1001,fieldmatch,decimate}.
11035 The filter accepts the following options:
11039 Specify the assumed field order of the input stream. Available values are:
11043 Auto detect parity (use FFmpeg's internal parity value).
11045 Assume bottom field first.
11047 Assume top field first.
11050 Note that it is sometimes recommended not to trust the parity announced by the
11053 Default value is @var{auto}.
11056 Set the matching mode or strategy to use. @option{pc} mode is the safest in the
11057 sense that it won't risk creating jerkiness due to duplicate frames when
11058 possible, but if there are bad edits or blended fields it will end up
11059 outputting combed frames when a good match might actually exist. On the other
11060 hand, @option{pcn_ub} mode is the most risky in terms of creating jerkiness,
11061 but will almost always find a good frame if there is one. The other values are
11062 all somewhere in between @option{pc} and @option{pcn_ub} in terms of risking
11063 jerkiness and creating duplicate frames versus finding good matches in sections
11064 with bad edits, orphaned fields, blended fields, etc.
11066 More details about p/c/n/u/b are available in @ref{p/c/n/u/b meaning} section.
11068 Available values are:
11072 2-way matching (p/c)
11074 2-way matching, and trying 3rd match if still combed (p/c + n)
11076 2-way matching, and trying 3rd match (same order) if still combed (p/c + u)
11078 2-way matching, trying 3rd match if still combed, and trying 4th/5th matches if
11079 still combed (p/c + n + u/b)
11081 3-way matching (p/c/n)
11083 3-way matching, and trying 4th/5th matches if all 3 of the original matches are
11084 detected as combed (p/c/n + u/b)
11087 The parenthesis at the end indicate the matches that would be used for that
11088 mode assuming @option{order}=@var{tff} (and @option{field} on @var{auto} or
11091 In terms of speed @option{pc} mode is by far the fastest and @option{pcn_ub} is
11094 Default value is @var{pc_n}.
11097 Mark the main input stream as a pre-processed input, and enable the secondary
11098 input stream as the clean source to pick the fields from. See the filter
11099 introduction for more details. It is similar to the @option{clip2} feature from
11102 Default value is @code{0} (disabled).
11105 Set the field to match from. It is recommended to set this to the same value as
11106 @option{order} unless you experience matching failures with that setting. In
11107 certain circumstances changing the field that is used to match from can have a
11108 large impact on matching performance. Available values are:
11112 Automatic (same value as @option{order}).
11114 Match from the bottom field.
11116 Match from the top field.
11119 Default value is @var{auto}.
11122 Set whether or not chroma is included during the match comparisons. In most
11123 cases it is recommended to leave this enabled. You should set this to @code{0}
11124 only if your clip has bad chroma problems such as heavy rainbowing or other
11125 artifacts. Setting this to @code{0} could also be used to speed things up at
11126 the cost of some accuracy.
11128 Default value is @code{1}.
11132 These define an exclusion band which excludes the lines between @option{y0} and
11133 @option{y1} from being included in the field matching decision. An exclusion
11134 band can be used to ignore subtitles, a logo, or other things that may
11135 interfere with the matching. @option{y0} sets the starting scan line and
11136 @option{y1} sets the ending line; all lines in between @option{y0} and
11137 @option{y1} (including @option{y0} and @option{y1}) will be ignored. Setting
11138 @option{y0} and @option{y1} to the same value will disable the feature.
11139 @option{y0} and @option{y1} defaults to @code{0}.
11142 Set the scene change detection threshold as a percentage of maximum change on
11143 the luma plane. Good values are in the @code{[8.0, 14.0]} range. Scene change
11144 detection is only relevant in case @option{combmatch}=@var{sc}. The range for
11145 @option{scthresh} is @code{[0.0, 100.0]}.
11147 Default value is @code{12.0}.
11150 When @option{combatch} is not @var{none}, @code{fieldmatch} will take into
11151 account the combed scores of matches when deciding what match to use as the
11152 final match. Available values are:
11156 No final matching based on combed scores.
11158 Combed scores are only used when a scene change is detected.
11160 Use combed scores all the time.
11163 Default is @var{sc}.
11166 Force @code{fieldmatch} to calculate the combed metrics for certain matches and
11167 print them. This setting is known as @option{micout} in TFM/VFM vocabulary.
11168 Available values are:
11172 No forced calculation.
11174 Force p/c/n calculations.
11176 Force p/c/n/u/b calculations.
11179 Default value is @var{none}.
11182 This is the area combing threshold used for combed frame detection. This
11183 essentially controls how "strong" or "visible" combing must be to be detected.
11184 Larger values mean combing must be more visible and smaller values mean combing
11185 can be less visible or strong and still be detected. Valid settings are from
11186 @code{-1} (every pixel will be detected as combed) to @code{255} (no pixel will
11187 be detected as combed). This is basically a pixel difference value. A good
11188 range is @code{[8, 12]}.
11190 Default value is @code{9}.
11193 Sets whether or not chroma is considered in the combed frame decision. Only
11194 disable this if your source has chroma problems (rainbowing, etc.) that are
11195 causing problems for the combed frame detection with chroma enabled. Actually,
11196 using @option{chroma}=@var{0} is usually more reliable, except for the case
11197 where there is chroma only combing in the source.
11199 Default value is @code{0}.
11203 Respectively set the x-axis and y-axis size of the window used during combed
11204 frame detection. This has to do with the size of the area in which
11205 @option{combpel} pixels are required to be detected as combed for a frame to be
11206 declared combed. See the @option{combpel} parameter description for more info.
11207 Possible values are any number that is a power of 2 starting at 4 and going up
11210 Default value is @code{16}.
11213 The number of combed pixels inside any of the @option{blocky} by
11214 @option{blockx} size blocks on the frame for the frame to be detected as
11215 combed. While @option{cthresh} controls how "visible" the combing must be, this
11216 setting controls "how much" combing there must be in any localized area (a
11217 window defined by the @option{blockx} and @option{blocky} settings) on the
11218 frame. Minimum value is @code{0} and maximum is @code{blocky x blockx} (at
11219 which point no frames will ever be detected as combed). This setting is known
11220 as @option{MI} in TFM/VFM vocabulary.
11222 Default value is @code{80}.
11225 @anchor{p/c/n/u/b meaning}
11226 @subsection p/c/n/u/b meaning
11228 @subsubsection p/c/n
11230 We assume the following telecined stream:
11233 Top fields: 1 2 2 3 4
11234 Bottom fields: 1 2 3 4 4
11237 The numbers correspond to the progressive frame the fields relate to. Here, the
11238 first two frames are progressive, the 3rd and 4th are combed, and so on.
11240 When @code{fieldmatch} is configured to run a matching from bottom
11241 (@option{field}=@var{bottom}) this is how this input stream get transformed:
11246 B 1 2 3 4 4 <-- matching reference
11255 As a result of the field matching, we can see that some frames get duplicated.
11256 To perform a complete inverse telecine, you need to rely on a decimation filter
11257 after this operation. See for instance the @ref{decimate} filter.
11259 The same operation now matching from top fields (@option{field}=@var{top})
11264 T 1 2 2 3 4 <-- matching reference
11274 In these examples, we can see what @var{p}, @var{c} and @var{n} mean;
11275 basically, they refer to the frame and field of the opposite parity:
11278 @item @var{p} matches the field of the opposite parity in the previous frame
11279 @item @var{c} matches the field of the opposite parity in the current frame
11280 @item @var{n} matches the field of the opposite parity in the next frame
11285 The @var{u} and @var{b} matching are a bit special in the sense that they match
11286 from the opposite parity flag. In the following examples, we assume that we are
11287 currently matching the 2nd frame (Top:2, bottom:2). According to the match, a
11288 'x' is placed above and below each matched fields.
11290 With bottom matching (@option{field}=@var{bottom}):
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 With top matching (@option{field}=@var{top}):
11309 Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2
11310 Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3
11318 @subsection Examples
11320 Simple IVTC of a top field first telecined stream:
11322 fieldmatch=order=tff:combmatch=none, decimate
11325 Advanced IVTC, with fallback on @ref{yadif} for still combed frames:
11327 fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate
11330 @section fieldorder
11332 Transform the field order of the input video.
11334 It accepts the following parameters:
11339 The output field order. Valid values are @var{tff} for top field first or @var{bff}
11340 for bottom field first.
11343 The default value is @samp{tff}.
11345 The transformation is done by shifting the picture content up or down
11346 by one line, and filling the remaining line with appropriate picture content.
11347 This method is consistent with most broadcast field order converters.
11349 If the input video is not flagged as being interlaced, or it is already
11350 flagged as being of the required output field order, then this filter does
11351 not alter the incoming video.
11353 It is very useful when converting to or from PAL DV material,
11354 which is bottom field first.
11358 ffmpeg -i in.vob -vf "fieldorder=bff" out.dv
11361 @section fifo, afifo
11363 Buffer input images and send them when they are requested.
11365 It is mainly useful when auto-inserted by the libavfilter
11368 It does not take parameters.
11370 @section fillborders
11372 Fill borders of the input video, without changing video stream dimensions.
11373 Sometimes video can have garbage at the four edges and you may not want to
11374 crop video input to keep size multiple of some number.
11376 This filter accepts the following options:
11380 Number of pixels to fill from left border.
11383 Number of pixels to fill from right border.
11386 Number of pixels to fill from top border.
11389 Number of pixels to fill from bottom border.
11394 It accepts the following values:
11397 fill pixels using outermost pixels
11400 fill pixels using mirroring
11403 fill pixels with constant value
11406 Default is @var{smear}.
11409 Set color for pixels in fixed mode. Default is @var{black}.
11412 @subsection Commands
11413 This filter supports same @ref{commands} as options.
11414 The command accepts the same syntax of the corresponding option.
11416 If the specified expression is not valid, it is kept at its current
11421 Find a rectangular object
11423 It accepts the following options:
11427 Filepath of the object image, needs to be in gray8.
11430 Detection threshold, default is 0.5.
11433 Number of mipmaps, default is 3.
11435 @item xmin, ymin, xmax, ymax
11436 Specifies the rectangle in which to search.
11439 @subsection Examples
11443 Cover a rectangular object by the supplied image of a given video using @command{ffmpeg}:
11445 ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
11451 Flood area with values of same pixel components with another values.
11453 It accepts the following options:
11456 Set pixel x coordinate.
11459 Set pixel y coordinate.
11462 Set source #0 component value.
11465 Set source #1 component value.
11468 Set source #2 component value.
11471 Set source #3 component value.
11474 Set destination #0 component value.
11477 Set destination #1 component value.
11480 Set destination #2 component value.
11483 Set destination #3 component value.
11489 Convert the input video to one of the specified pixel formats.
11490 Libavfilter will try to pick one that is suitable as input to
11493 It accepts the following parameters:
11497 A '|'-separated list of pixel format names, such as
11498 "pix_fmts=yuv420p|monow|rgb24".
11502 @subsection Examples
11506 Convert the input video to the @var{yuv420p} format
11508 format=pix_fmts=yuv420p
11511 Convert the input video to any of the formats in the list
11513 format=pix_fmts=yuv420p|yuv444p|yuv410p
11520 Convert the video to specified constant frame rate by duplicating or dropping
11521 frames as necessary.
11523 It accepts the following parameters:
11527 The desired output frame rate. The default is @code{25}.
11530 Assume the first PTS should be the given value, in seconds. This allows for
11531 padding/trimming at the start of stream. By default, no assumption is made
11532 about the first frame's expected PTS, so no padding or trimming is done.
11533 For example, this could be set to 0 to pad the beginning with duplicates of
11534 the first frame if a video stream starts after the audio stream or to trim any
11535 frames with a negative PTS.
11538 Timestamp (PTS) rounding method.
11540 Possible values are:
11547 round towards -infinity
11549 round towards +infinity
11553 The default is @code{near}.
11556 Action performed when reading the last frame.
11558 Possible values are:
11561 Use same timestamp rounding method as used for other frames.
11563 Pass through last frame if input duration has not been reached yet.
11565 The default is @code{round}.
11569 Alternatively, the options can be specified as a flat string:
11570 @var{fps}[:@var{start_time}[:@var{round}]].
11572 See also the @ref{setpts} filter.
11574 @subsection Examples
11578 A typical usage in order to set the fps to 25:
11584 Sets the fps to 24, using abbreviation and rounding method to round to nearest:
11586 fps=fps=film:round=near
11592 Pack two different video streams into a stereoscopic video, setting proper
11593 metadata on supported codecs. The two views should have the same size and
11594 framerate and processing will stop when the shorter video ends. Please note
11595 that you may conveniently adjust view properties with the @ref{scale} and
11598 It accepts the following parameters:
11602 The desired packing format. Supported values are:
11607 The views are next to each other (default).
11610 The views are on top of each other.
11613 The views are packed by line.
11616 The views are packed by column.
11619 The views are temporally interleaved.
11628 # Convert left and right views into a frame-sequential video
11629 ffmpeg -i LEFT -i RIGHT -filter_complex framepack=frameseq OUTPUT
11631 # Convert views into a side-by-side video with the same output resolution as the input
11632 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
11637 Change the frame rate by interpolating new video output frames from the source
11640 This filter is not designed to function correctly with interlaced media. If
11641 you wish to change the frame rate of interlaced media then you are required
11642 to deinterlace before this filter and re-interlace after this filter.
11644 A description of the accepted options follows.
11648 Specify the output frames per second. This option can also be specified
11649 as a value alone. The default is @code{50}.
11652 Specify the start of a range where the output frame will be created as a
11653 linear interpolation of two frames. The range is [@code{0}-@code{255}],
11654 the default is @code{15}.
11657 Specify the end of a range where the output frame will be created as a
11658 linear interpolation of two frames. The range is [@code{0}-@code{255}],
11659 the default is @code{240}.
11662 Specify the level at which a scene change is detected as a value between
11663 0 and 100 to indicate a new scene; a low value reflects a low
11664 probability for the current frame to introduce a new scene, while a higher
11665 value means the current frame is more likely to be one.
11666 The default is @code{8.2}.
11669 Specify flags influencing the filter process.
11671 Available value for @var{flags} is:
11674 @item scene_change_detect, scd
11675 Enable scene change detection using the value of the option @var{scene}.
11676 This flag is enabled by default.
11682 Select one frame every N-th frame.
11684 This filter accepts the following option:
11687 Select frame after every @code{step} frames.
11688 Allowed values are positive integers higher than 0. Default value is @code{1}.
11691 @section freezedetect
11693 Detect frozen video.
11695 This filter logs a message and sets frame metadata when it detects that the
11696 input video has no significant change in content during a specified duration.
11697 Video freeze detection calculates the mean average absolute difference of all
11698 the components of video frames and compares it to a noise floor.
11700 The printed times and duration are expressed in seconds. The
11701 @code{lavfi.freezedetect.freeze_start} metadata key is set on the first frame
11702 whose timestamp equals or exceeds the detection duration and it contains the
11703 timestamp of the first frame of the freeze. The
11704 @code{lavfi.freezedetect.freeze_duration} and
11705 @code{lavfi.freezedetect.freeze_end} metadata keys are set on the first frame
11708 The filter accepts the following options:
11712 Set noise tolerance. Can be specified in dB (in case "dB" is appended to the
11713 specified value) or as a difference ratio between 0 and 1. Default is -60dB, or
11717 Set freeze duration until notification (default is 2 seconds).
11720 @section freezeframes
11722 Freeze video frames.
11724 This filter freezes video frames using frame from 2nd input.
11726 The filter accepts the following options:
11730 Set number of first frame from which to start freeze.
11733 Set number of last frame from which to end freeze.
11736 Set number of frame from 2nd input which will be used instead of replaced frames.
11742 Apply a frei0r effect to the input video.
11744 To enable the compilation of this filter, you need to install the frei0r
11745 header and configure FFmpeg with @code{--enable-frei0r}.
11747 It accepts the following parameters:
11752 The name of the frei0r effect to load. If the environment variable
11753 @env{FREI0R_PATH} is defined, the frei0r effect is searched for in each of the
11754 directories specified by the colon-separated list in @env{FREI0R_PATH}.
11755 Otherwise, the standard frei0r paths are searched, in this order:
11756 @file{HOME/.frei0r-1/lib/}, @file{/usr/local/lib/frei0r-1/},
11757 @file{/usr/lib/frei0r-1/}.
11759 @item filter_params
11760 A '|'-separated list of parameters to pass to the frei0r effect.
11764 A frei0r effect parameter can be a boolean (its value is either
11765 "y" or "n"), a double, a color (specified as
11766 @var{R}/@var{G}/@var{B}, where @var{R}, @var{G}, and @var{B} are floating point
11767 numbers between 0.0 and 1.0, inclusive) or a color description as specified in the
11768 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils},
11769 a position (specified as @var{X}/@var{Y}, where
11770 @var{X} and @var{Y} are floating point numbers) and/or a string.
11772 The number and types of parameters depend on the loaded effect. If an
11773 effect parameter is not specified, the default value is set.
11775 @subsection Examples
11779 Apply the distort0r effect, setting the first two double parameters:
11781 frei0r=filter_name=distort0r:filter_params=0.5|0.01
11785 Apply the colordistance effect, taking a color as the first parameter:
11787 frei0r=colordistance:0.2/0.3/0.4
11788 frei0r=colordistance:violet
11789 frei0r=colordistance:0x112233
11793 Apply the perspective effect, specifying the top left and top right image
11796 frei0r=perspective:0.2/0.2|0.8/0.2
11800 For more information, see
11801 @url{http://frei0r.dyne.org}
11803 @subsection Commands
11805 This filter supports the @option{filter_params} option as @ref{commands}.
11809 Apply fast and simple postprocessing. It is a faster version of @ref{spp}.
11811 It splits (I)DCT into horizontal/vertical passes. Unlike the simple post-
11812 processing filter, one of them is performed once per block, not per pixel.
11813 This allows for much higher speed.
11815 The filter accepts the following options:
11819 Set quality. This option defines the number of levels for averaging. It accepts
11820 an integer in the range 4-5. Default value is @code{4}.
11823 Force a constant quantization parameter. It accepts an integer in range 0-63.
11824 If not set, the filter will use the QP from the video stream (if available).
11827 Set filter strength. It accepts an integer in range -15 to 32. Lower values mean
11828 more details but also more artifacts, while higher values make the image smoother
11829 but also blurrier. Default value is @code{0} − PSNR optimal.
11831 @item use_bframe_qp
11832 Enable the use of the QP from the B-Frames if set to @code{1}. Using this
11833 option may cause flicker since the B-Frames have often larger QP. Default is
11834 @code{0} (not enabled).
11840 Apply Gaussian blur filter.
11842 The filter accepts the following options:
11846 Set horizontal sigma, standard deviation of Gaussian blur. Default is @code{0.5}.
11849 Set number of steps for Gaussian approximation. Default is @code{1}.
11852 Set which planes to filter. By default all planes are filtered.
11855 Set vertical sigma, if negative it will be same as @code{sigma}.
11856 Default is @code{-1}.
11859 @subsection Commands
11860 This filter supports same commands as options.
11861 The command accepts the same syntax of the corresponding option.
11863 If the specified expression is not valid, it is kept at its current
11868 Apply generic equation to each pixel.
11870 The filter accepts the following options:
11873 @item lum_expr, lum
11874 Set the luminance expression.
11876 Set the chrominance blue expression.
11878 Set the chrominance red expression.
11879 @item alpha_expr, a
11880 Set the alpha expression.
11882 Set the red expression.
11883 @item green_expr, g
11884 Set the green expression.
11886 Set the blue expression.
11889 The colorspace is selected according to the specified options. If one
11890 of the @option{lum_expr}, @option{cb_expr}, or @option{cr_expr}
11891 options is specified, the filter will automatically select a YCbCr
11892 colorspace. If one of the @option{red_expr}, @option{green_expr}, or
11893 @option{blue_expr} options is specified, it will select an RGB
11896 If one of the chrominance expression is not defined, it falls back on the other
11897 one. If no alpha expression is specified it will evaluate to opaque value.
11898 If none of chrominance expressions are specified, they will evaluate
11899 to the luminance expression.
11901 The expressions can use the following variables and functions:
11905 The sequential number of the filtered frame, starting from @code{0}.
11909 The coordinates of the current sample.
11913 The width and height of the image.
11917 Width and height scale depending on the currently filtered plane. It is the
11918 ratio between the corresponding luma plane number of pixels and the current
11919 plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and
11920 @code{0.5,0.5} for chroma planes.
11923 Time of the current frame, expressed in seconds.
11926 Return the value of the pixel at location (@var{x},@var{y}) of the current
11930 Return the value of the pixel at location (@var{x},@var{y}) of the luminance
11934 Return the value of the pixel at location (@var{x},@var{y}) of the
11935 blue-difference chroma plane. Return 0 if there is no such plane.
11938 Return the value of the pixel at location (@var{x},@var{y}) of the
11939 red-difference chroma plane. Return 0 if there is no such plane.
11944 Return the value of the pixel at location (@var{x},@var{y}) of the
11945 red/green/blue component. Return 0 if there is no such component.
11948 Return the value of the pixel at location (@var{x},@var{y}) of the alpha
11949 plane. Return 0 if there is no such plane.
11951 @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)
11952 Sum of sample values in the rectangle from (0,0) to (x,y), this allows obtaining
11953 sums of samples within a rectangle. See the functions without the sum postfix.
11955 @item interpolation
11956 Set one of interpolation methods:
11961 Default is bilinear.
11964 For functions, if @var{x} and @var{y} are outside the area, the value will be
11965 automatically clipped to the closer edge.
11967 Please note that this filter can use multiple threads in which case each slice
11968 will have its own expression state. If you want to use only a single expression
11969 state because your expressions depend on previous state then you should limit
11970 the number of filter threads to 1.
11972 @subsection Examples
11976 Flip the image horizontally:
11982 Generate a bidimensional sine wave, with angle @code{PI/3} and a
11983 wavelength of 100 pixels:
11985 geq=128 + 100*sin(2*(PI/100)*(cos(PI/3)*(X-50*T) + sin(PI/3)*Y)):128:128
11989 Generate a fancy enigmatic moving light:
11991 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
11995 Generate a quick emboss effect:
11997 format=gray,geq=lum_expr='(p(X,Y)+(256-p(X-4,Y-4)))/2'
12001 Modify RGB components depending on pixel position:
12003 geq=r='X/W*r(X,Y)':g='(1-X/W)*g(X,Y)':b='(H-Y)/H*b(X,Y)'
12007 Create a radial gradient that is the same size as the input (also see
12008 the @ref{vignette} filter):
12010 geq=lum=255*gauss((X/W-0.5)*3)*gauss((Y/H-0.5)*3)/gauss(0)/gauss(0),format=gray
12016 Fix the banding artifacts that are sometimes introduced into nearly flat
12017 regions by truncation to 8-bit color depth.
12018 Interpolate the gradients that should go where the bands are, and
12021 It is designed for playback only. Do not use it prior to
12022 lossy compression, because compression tends to lose the dither and
12023 bring back the bands.
12025 It accepts the following parameters:
12030 The maximum amount by which the filter will change any one pixel. This is also
12031 the threshold for detecting nearly flat regions. Acceptable values range from
12032 .51 to 64; the default value is 1.2. Out-of-range values will be clipped to the
12036 The neighborhood to fit the gradient to. A larger radius makes for smoother
12037 gradients, but also prevents the filter from modifying the pixels near detailed
12038 regions. Acceptable values are 8-32; the default value is 16. Out-of-range
12039 values will be clipped to the valid range.
12043 Alternatively, the options can be specified as a flat string:
12044 @var{strength}[:@var{radius}]
12046 @subsection Examples
12050 Apply the filter with a @code{3.5} strength and radius of @code{8}:
12056 Specify radius, omitting the strength (which will fall-back to the default
12064 @anchor{graphmonitor}
12065 @section graphmonitor
12066 Show various filtergraph stats.
12068 With this filter one can debug complete filtergraph.
12069 Especially issues with links filling with queued frames.
12071 The filter accepts the following options:
12075 Set video output size. Default is @var{hd720}.
12078 Set video opacity. Default is @var{0.9}. Allowed range is from @var{0} to @var{1}.
12081 Set output mode, can be @var{fulll} or @var{compact}.
12082 In @var{compact} mode only filters with some queued frames have displayed stats.
12085 Set flags which enable which stats are shown in video.
12087 Available values for flags are:
12090 Display number of queued frames in each link.
12092 @item frame_count_in
12093 Display number of frames taken from filter.
12095 @item frame_count_out
12096 Display number of frames given out from filter.
12099 Display current filtered frame pts.
12102 Display current filtered frame time.
12105 Display time base for filter link.
12108 Display used format for filter link.
12111 Display video size or number of audio channels in case of audio used by filter link.
12114 Display video frame rate or sample rate in case of audio used by filter link.
12117 Display link output status.
12121 Set upper limit for video rate of output stream, Default value is @var{25}.
12122 This guarantee that output video frame rate will not be higher than this value.
12126 A color constancy variation filter which estimates scene illumination via grey edge algorithm
12127 and corrects the scene colors accordingly.
12129 See: @url{https://staff.science.uva.nl/th.gevers/pub/GeversTIP07.pdf}
12131 The filter accepts the following options:
12135 The order of differentiation to be applied on the scene. Must be chosen in the range
12136 [0,2] and default value is 1.
12139 The Minkowski parameter to be used for calculating the Minkowski distance. Must
12140 be chosen in the range [0,20] and default value is 1. Set to 0 for getting
12141 max value instead of calculating Minkowski distance.
12144 The standard deviation of Gaussian blur to be applied on the scene. Must be
12145 chosen in the range [0,1024.0] and default value = 1. floor( @var{sigma} * break_off_sigma(3) )
12146 can't be equal to 0 if @var{difford} is greater than 0.
12149 @subsection Examples
12155 greyedge=difford=1:minknorm=5:sigma=2
12161 greyedge=difford=1:minknorm=0:sigma=2
12169 Apply a Hald CLUT to a video stream.
12171 First input is the video stream to process, and second one is the Hald CLUT.
12172 The Hald CLUT input can be a simple picture or a complete video stream.
12174 The filter accepts the following options:
12178 Force termination when the shortest input terminates. Default is @code{0}.
12180 Continue applying the last CLUT after the end of the stream. A value of
12181 @code{0} disable the filter after the last frame of the CLUT is reached.
12182 Default is @code{1}.
12185 @code{haldclut} also has the same interpolation options as @ref{lut3d} (both
12186 filters share the same internals).
12188 This filter also supports the @ref{framesync} options.
12190 More information about the Hald CLUT can be found on Eskil Steenberg's website
12191 (Hald CLUT author) at @url{http://www.quelsolaar.com/technology/clut.html}.
12193 @subsection Workflow examples
12195 @subsubsection Hald CLUT video stream
12197 Generate an identity Hald CLUT stream altered with various effects:
12199 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
12202 Note: make sure you use a lossless codec.
12204 Then use it with @code{haldclut} to apply it on some random stream:
12206 ffmpeg -f lavfi -i mandelbrot -i clut.nut -filter_complex '[0][1] haldclut' -t 20 mandelclut.mkv
12209 The Hald CLUT will be applied to the 10 first seconds (duration of
12210 @file{clut.nut}), then the latest picture of that CLUT stream will be applied
12211 to the remaining frames of the @code{mandelbrot} stream.
12213 @subsubsection Hald CLUT with preview
12215 A Hald CLUT is supposed to be a squared image of @code{Level*Level*Level} by
12216 @code{Level*Level*Level} pixels. For a given Hald CLUT, FFmpeg will select the
12217 biggest possible square starting at the top left of the picture. The remaining
12218 padding pixels (bottom or right) will be ignored. This area can be used to add
12219 a preview of the Hald CLUT.
12221 Typically, the following generated Hald CLUT will be supported by the
12222 @code{haldclut} filter:
12225 ffmpeg -f lavfi -i @ref{haldclutsrc}=8 -vf "
12226 pad=iw+320 [padded_clut];
12227 smptebars=s=320x256, split [a][b];
12228 [padded_clut][a] overlay=W-320:h, curves=color_negative [main];
12229 [main][b] overlay=W-320" -frames:v 1 clut.png
12232 It contains the original and a preview of the effect of the CLUT: SMPTE color
12233 bars are displayed on the right-top, and below the same color bars processed by
12236 Then, the effect of this Hald CLUT can be visualized with:
12238 ffplay input.mkv -vf "movie=clut.png, [in] haldclut"
12243 Flip the input video horizontally.
12245 For example, to horizontally flip the input video with @command{ffmpeg}:
12247 ffmpeg -i in.avi -vf "hflip" out.avi
12251 This filter applies a global color histogram equalization on a
12254 It can be used to correct video that has a compressed range of pixel
12255 intensities. The filter redistributes the pixel intensities to
12256 equalize their distribution across the intensity range. It may be
12257 viewed as an "automatically adjusting contrast filter". This filter is
12258 useful only for correcting degraded or poorly captured source
12261 The filter accepts the following options:
12265 Determine the amount of equalization to be applied. As the strength
12266 is reduced, the distribution of pixel intensities more-and-more
12267 approaches that of the input frame. The value must be a float number
12268 in the range [0,1] and defaults to 0.200.
12271 Set the maximum intensity that can generated and scale the output
12272 values appropriately. The strength should be set as desired and then
12273 the intensity can be limited if needed to avoid washing-out. The value
12274 must be a float number in the range [0,1] and defaults to 0.210.
12277 Set the antibanding level. If enabled the filter will randomly vary
12278 the luminance of output pixels by a small amount to avoid banding of
12279 the histogram. Possible values are @code{none}, @code{weak} or
12280 @code{strong}. It defaults to @code{none}.
12286 Compute and draw a color distribution histogram for the input video.
12288 The computed histogram is a representation of the color component
12289 distribution in an image.
12291 Standard histogram displays the color components distribution in an image.
12292 Displays color graph for each color component. Shows distribution of
12293 the Y, U, V, A or R, G, B components, depending on input format, in the
12294 current frame. Below each graph a color component scale meter is shown.
12296 The filter accepts the following options:
12300 Set height of level. Default value is @code{200}.
12301 Allowed range is [50, 2048].
12304 Set height of color scale. Default value is @code{12}.
12305 Allowed range is [0, 40].
12309 It accepts the following values:
12312 Per color component graphs are placed below each other.
12315 Per color component graphs are placed side by side.
12318 Presents information identical to that in the @code{parade}, except
12319 that the graphs representing color components are superimposed directly
12322 Default is @code{stack}.
12325 Set mode. Can be either @code{linear}, or @code{logarithmic}.
12326 Default is @code{linear}.
12329 Set what color components to display.
12330 Default is @code{7}.
12333 Set foreground opacity. Default is @code{0.7}.
12336 Set background opacity. Default is @code{0.5}.
12339 @subsection Examples
12344 Calculate and draw histogram:
12346 ffplay -i input -vf histogram
12354 This is a high precision/quality 3d denoise filter. It aims to reduce
12355 image noise, producing smooth images and making still images really
12356 still. It should enhance compressibility.
12358 It accepts the following optional parameters:
12362 A non-negative floating point number which specifies spatial luma strength.
12363 It defaults to 4.0.
12365 @item chroma_spatial
12366 A non-negative floating point number which specifies spatial chroma strength.
12367 It defaults to 3.0*@var{luma_spatial}/4.0.
12370 A floating point number which specifies luma temporal strength. It defaults to
12371 6.0*@var{luma_spatial}/4.0.
12374 A floating point number which specifies chroma temporal strength. It defaults to
12375 @var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}.
12378 @subsection Commands
12379 This filter supports same @ref{commands} as options.
12380 The command accepts the same syntax of the corresponding option.
12382 If the specified expression is not valid, it is kept at its current
12385 @anchor{hwdownload}
12386 @section hwdownload
12388 Download hardware frames to system memory.
12390 The input must be in hardware frames, and the output a non-hardware format.
12391 Not all formats will be supported on the output - it may be necessary to insert
12392 an additional @option{format} filter immediately following in the graph to get
12393 the output in a supported format.
12397 Map hardware frames to system memory or to another device.
12399 This filter has several different modes of operation; which one is used depends
12400 on the input and output formats:
12403 Hardware frame input, normal frame output
12405 Map the input frames to system memory and pass them to the output. If the
12406 original hardware frame is later required (for example, after overlaying
12407 something else on part of it), the @option{hwmap} filter can be used again
12408 in the next mode to retrieve it.
12410 Normal frame input, hardware frame output
12412 If the input is actually a software-mapped hardware frame, then unmap it -
12413 that is, return the original hardware frame.
12415 Otherwise, a device must be provided. Create new hardware surfaces on that
12416 device for the output, then map them back to the software format at the input
12417 and give those frames to the preceding filter. This will then act like the
12418 @option{hwupload} filter, but may be able to avoid an additional copy when
12419 the input is already in a compatible format.
12421 Hardware frame input and output
12423 A device must be supplied for the output, either directly or with the
12424 @option{derive_device} option. The input and output devices must be of
12425 different types and compatible - the exact meaning of this is
12426 system-dependent, but typically it means that they must refer to the same
12427 underlying hardware context (for example, refer to the same graphics card).
12429 If the input frames were originally created on the output device, then unmap
12430 to retrieve the original frames.
12432 Otherwise, map the frames to the output device - create new hardware frames
12433 on the output corresponding to the frames on the input.
12436 The following additional parameters are accepted:
12440 Set the frame mapping mode. Some combination of:
12443 The mapped frame should be readable.
12445 The mapped frame should be writeable.
12447 The mapping will always overwrite the entire frame.
12449 This may improve performance in some cases, as the original contents of the
12450 frame need not be loaded.
12452 The mapping must not involve any copying.
12454 Indirect mappings to copies of frames are created in some cases where either
12455 direct mapping is not possible or it would have unexpected properties.
12456 Setting this flag ensures that the mapping is direct and will fail if that is
12459 Defaults to @var{read+write} if not specified.
12461 @item derive_device @var{type}
12462 Rather than using the device supplied at initialisation, instead derive a new
12463 device of type @var{type} from the device the input frames exist on.
12466 In a hardware to hardware mapping, map in reverse - create frames in the sink
12467 and map them back to the source. This may be necessary in some cases where
12468 a mapping in one direction is required but only the opposite direction is
12469 supported by the devices being used.
12471 This option is dangerous - it may break the preceding filter in undefined
12472 ways if there are any additional constraints on that filter's output.
12473 Do not use it without fully understanding the implications of its use.
12479 Upload system memory frames to hardware surfaces.
12481 The device to upload to must be supplied when the filter is initialised. If
12482 using ffmpeg, select the appropriate device with the @option{-filter_hw_device}
12483 option or with the @option{derive_device} option. The input and output devices
12484 must be of different types and compatible - the exact meaning of this is
12485 system-dependent, but typically it means that they must refer to the same
12486 underlying hardware context (for example, refer to the same graphics card).
12488 The following additional parameters are accepted:
12491 @item derive_device @var{type}
12492 Rather than using the device supplied at initialisation, instead derive a new
12493 device of type @var{type} from the device the input frames exist on.
12496 @anchor{hwupload_cuda}
12497 @section hwupload_cuda
12499 Upload system memory frames to a CUDA device.
12501 It accepts the following optional parameters:
12505 The number of the CUDA device to use
12510 Apply a high-quality magnification filter designed for pixel art. This filter
12511 was originally created by Maxim Stepin.
12513 It accepts the following option:
12517 Set the scaling dimension: @code{2} for @code{hq2x}, @code{3} for
12518 @code{hq3x} and @code{4} for @code{hq4x}.
12519 Default is @code{3}.
12523 Stack input videos horizontally.
12525 All streams must be of same pixel format and of same height.
12527 Note that this filter is faster than using @ref{overlay} and @ref{pad} filter
12528 to create same output.
12530 The filter accepts the following option:
12534 Set number of input streams. Default is 2.
12537 If set to 1, force the output to terminate when the shortest input
12538 terminates. Default value is 0.
12543 Modify the hue and/or the saturation of the input.
12545 It accepts the following parameters:
12549 Specify the hue angle as a number of degrees. It accepts an expression,
12550 and defaults to "0".
12553 Specify the saturation in the [-10,10] range. It accepts an expression and
12557 Specify the hue angle as a number of radians. It accepts an
12558 expression, and defaults to "0".
12561 Specify the brightness in the [-10,10] range. It accepts an expression and
12565 @option{h} and @option{H} are mutually exclusive, and can't be
12566 specified at the same time.
12568 The @option{b}, @option{h}, @option{H} and @option{s} option values are
12569 expressions containing the following constants:
12573 frame count of the input frame starting from 0
12576 presentation timestamp of the input frame expressed in time base units
12579 frame rate of the input video, NAN if the input frame rate is unknown
12582 timestamp expressed in seconds, NAN if the input timestamp is unknown
12585 time base of the input video
12588 @subsection Examples
12592 Set the hue to 90 degrees and the saturation to 1.0:
12598 Same command but expressing the hue in radians:
12604 Rotate hue and make the saturation swing between 0
12605 and 2 over a period of 1 second:
12607 hue="H=2*PI*t: s=sin(2*PI*t)+1"
12611 Apply a 3 seconds saturation fade-in effect starting at 0:
12613 hue="s=min(t/3\,1)"
12616 The general fade-in expression can be written as:
12618 hue="s=min(0\, max((t-START)/DURATION\, 1))"
12622 Apply a 3 seconds saturation fade-out effect starting at 5 seconds:
12624 hue="s=max(0\, min(1\, (8-t)/3))"
12627 The general fade-out expression can be written as:
12629 hue="s=max(0\, min(1\, (START+DURATION-t)/DURATION))"
12634 @subsection Commands
12636 This filter supports the following commands:
12642 Modify the hue and/or the saturation and/or brightness of the input video.
12643 The command accepts the same syntax of the corresponding option.
12645 If the specified expression is not valid, it is kept at its current
12649 @section hysteresis
12651 Grow first stream into second stream by connecting components.
12652 This makes it possible to build more robust edge masks.
12654 This filter accepts the following options:
12658 Set which planes will be processed as bitmap, unprocessed planes will be
12659 copied from first stream.
12660 By default value 0xf, all planes will be processed.
12663 Set threshold which is used in filtering. If pixel component value is higher than
12664 this value filter algorithm for connecting components is activated.
12665 By default value is 0.
12668 The @code{hysteresis} filter also supports the @ref{framesync} options.
12672 Detect video interlacing type.
12674 This filter tries to detect if the input frames are interlaced, progressive,
12675 top or bottom field first. It will also try to detect fields that are
12676 repeated between adjacent frames (a sign of telecine).
12678 Single frame detection considers only immediately adjacent frames when classifying each frame.
12679 Multiple frame detection incorporates the classification history of previous frames.
12681 The filter will log these metadata values:
12684 @item single.current_frame
12685 Detected type of current frame using single-frame detection. One of:
12686 ``tff'' (top field first), ``bff'' (bottom field first),
12687 ``progressive'', or ``undetermined''
12690 Cumulative number of frames detected as top field first using single-frame detection.
12693 Cumulative number of frames detected as top field first using multiple-frame detection.
12696 Cumulative number of frames detected as bottom field first using single-frame detection.
12698 @item multiple.current_frame
12699 Detected type of current frame using multiple-frame detection. One of:
12700 ``tff'' (top field first), ``bff'' (bottom field first),
12701 ``progressive'', or ``undetermined''
12704 Cumulative number of frames detected as bottom field first using multiple-frame detection.
12706 @item single.progressive
12707 Cumulative number of frames detected as progressive using single-frame detection.
12709 @item multiple.progressive
12710 Cumulative number of frames detected as progressive using multiple-frame detection.
12712 @item single.undetermined
12713 Cumulative number of frames that could not be classified using single-frame detection.
12715 @item multiple.undetermined
12716 Cumulative number of frames that could not be classified using multiple-frame detection.
12718 @item repeated.current_frame
12719 Which field in the current frame is repeated from the last. One of ``neither'', ``top'', or ``bottom''.
12721 @item repeated.neither
12722 Cumulative number of frames with no repeated field.
12725 Cumulative number of frames with the top field repeated from the previous frame's top field.
12727 @item repeated.bottom
12728 Cumulative number of frames with the bottom field repeated from the previous frame's bottom field.
12731 The filter accepts the following options:
12735 Set interlacing threshold.
12737 Set progressive threshold.
12739 Threshold for repeated field detection.
12741 Number of frames after which a given frame's contribution to the
12742 statistics is halved (i.e., it contributes only 0.5 to its
12743 classification). The default of 0 means that all frames seen are given
12744 full weight of 1.0 forever.
12745 @item analyze_interlaced_flag
12746 When this is not 0 then idet will use the specified number of frames to determine
12747 if the interlaced flag is accurate, it will not count undetermined frames.
12748 If the flag is found to be accurate it will be used without any further
12749 computations, if it is found to be inaccurate it will be cleared without any
12750 further computations. This allows inserting the idet filter as a low computational
12751 method to clean up the interlaced flag
12756 Deinterleave or interleave fields.
12758 This filter allows one to process interlaced images fields without
12759 deinterlacing them. Deinterleaving splits the input frame into 2
12760 fields (so called half pictures). Odd lines are moved to the top
12761 half of the output image, even lines to the bottom half.
12762 You can process (filter) them independently and then re-interleave them.
12764 The filter accepts the following options:
12768 @item chroma_mode, c
12769 @item alpha_mode, a
12770 Available values for @var{luma_mode}, @var{chroma_mode} and
12771 @var{alpha_mode} are:
12777 @item deinterleave, d
12778 Deinterleave fields, placing one above the other.
12780 @item interleave, i
12781 Interleave fields. Reverse the effect of deinterleaving.
12783 Default value is @code{none}.
12785 @item luma_swap, ls
12786 @item chroma_swap, cs
12787 @item alpha_swap, as
12788 Swap luma/chroma/alpha fields. Exchange even & odd lines. Default value is @code{0}.
12791 @subsection Commands
12793 This filter supports the all above options as @ref{commands}.
12797 Apply inflate effect to the video.
12799 This filter replaces the pixel by the local(3x3) average by taking into account
12800 only values higher than the pixel.
12802 It accepts the following options:
12809 Limit the maximum change for each plane, default is 65535.
12810 If 0, plane will remain unchanged.
12813 @subsection Commands
12815 This filter supports the all above options as @ref{commands}.
12819 Simple interlacing filter from progressive contents. This interleaves upper (or
12820 lower) lines from odd frames with lower (or upper) lines from even frames,
12821 halving the frame rate and preserving image height.
12824 Original Original New Frame
12825 Frame 'j' Frame 'j+1' (tff)
12826 ========== =========== ==================
12827 Line 0 --------------------> Frame 'j' Line 0
12828 Line 1 Line 1 ----> Frame 'j+1' Line 1
12829 Line 2 ---------------------> Frame 'j' Line 2
12830 Line 3 Line 3 ----> Frame 'j+1' Line 3
12832 New Frame + 1 will be generated by Frame 'j+2' and Frame 'j+3' and so on
12835 It accepts the following optional parameters:
12839 This determines whether the interlaced frame is taken from the even
12840 (tff - default) or odd (bff) lines of the progressive frame.
12843 Vertical lowpass filter to avoid twitter interlacing and
12844 reduce moire patterns.
12848 Disable vertical lowpass filter
12851 Enable linear filter (default)
12854 Enable complex filter. This will slightly less reduce twitter and moire
12855 but better retain detail and subjective sharpness impression.
12862 Deinterlace input video by applying Donald Graft's adaptive kernel
12863 deinterling. Work on interlaced parts of a video to produce
12864 progressive frames.
12866 The description of the accepted parameters follows.
12870 Set the threshold which affects the filter's tolerance when
12871 determining if a pixel line must be processed. It must be an integer
12872 in the range [0,255] and defaults to 10. A value of 0 will result in
12873 applying the process on every pixels.
12876 Paint pixels exceeding the threshold value to white if set to 1.
12880 Set the fields order. Swap fields if set to 1, leave fields alone if
12884 Enable additional sharpening if set to 1. Default is 0.
12887 Enable twoway sharpening if set to 1. Default is 0.
12890 @subsection Examples
12894 Apply default values:
12896 kerndeint=thresh=10:map=0:order=0:sharp=0:twoway=0
12900 Enable additional sharpening:
12906 Paint processed pixels in white:
12914 Slowly update darker pixels.
12916 This filter makes short flashes of light appear longer.
12917 This filter accepts the following options:
12921 Set factor for decaying. Default is .95. Allowed range is from 0 to 1.
12924 Set which planes to filter. Default is all. Allowed range is from 0 to 15.
12927 @section lenscorrection
12929 Correct radial lens distortion
12931 This filter can be used to correct for radial distortion as can result from the use
12932 of wide angle lenses, and thereby re-rectify the image. To find the right parameters
12933 one can use tools available for example as part of opencv or simply trial-and-error.
12934 To use opencv use the calibration sample (under samples/cpp) from the opencv sources
12935 and extract the k1 and k2 coefficients from the resulting matrix.
12937 Note that effectively the same filter is available in the open-source tools Krita and
12938 Digikam from the KDE project.
12940 In contrast to the @ref{vignette} filter, which can also be used to compensate lens errors,
12941 this filter corrects the distortion of the image, whereas @ref{vignette} corrects the
12942 brightness distribution, so you may want to use both filters together in certain
12943 cases, though you will have to take care of ordering, i.e. whether vignetting should
12944 be applied before or after lens correction.
12946 @subsection Options
12948 The filter accepts the following options:
12952 Relative x-coordinate of the focal point of the image, and thereby the center of the
12953 distortion. This value has a range [0,1] and is expressed as fractions of the image
12954 width. Default is 0.5.
12956 Relative y-coordinate of the focal point of the image, and thereby the center of the
12957 distortion. This value has a range [0,1] and is expressed as fractions of the image
12958 height. Default is 0.5.
12960 Coefficient of the quadratic correction term. This value has a range [-1,1]. 0 means
12961 no correction. Default is 0.
12963 Coefficient of the double quadratic correction term. This value has a range [-1,1].
12964 0 means no correction. Default is 0.
12967 The formula that generates the correction is:
12969 @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)
12971 where @var{r_0} is halve of the image diagonal and @var{r_src} and @var{r_tgt} are the
12972 distances from the focal point in the source and target images, respectively.
12976 Apply lens correction via the lensfun library (@url{http://lensfun.sourceforge.net/}).
12978 The @code{lensfun} filter requires the camera make, camera model, and lens model
12979 to apply the lens correction. The filter will load the lensfun database and
12980 query it to find the corresponding camera and lens entries in the database. As
12981 long as these entries can be found with the given options, the filter can
12982 perform corrections on frames. Note that incomplete strings will result in the
12983 filter choosing the best match with the given options, and the filter will
12984 output the chosen camera and lens models (logged with level "info"). You must
12985 provide the make, camera model, and lens model as they are required.
12987 The filter accepts the following options:
12991 The make of the camera (for example, "Canon"). This option is required.
12994 The model of the camera (for example, "Canon EOS 100D"). This option is
12998 The model of the lens (for example, "Canon EF-S 18-55mm f/3.5-5.6 IS STM"). This
12999 option is required.
13002 The type of correction to apply. The following values are valid options:
13006 Enables fixing lens vignetting.
13009 Enables fixing lens geometry. This is the default.
13012 Enables fixing chromatic aberrations.
13015 Enables fixing lens vignetting and lens geometry.
13018 Enables fixing lens vignetting and chromatic aberrations.
13021 Enables fixing both lens geometry and chromatic aberrations.
13024 Enables all possible corrections.
13028 The focal length of the image/video (zoom; expected constant for video). For
13029 example, a 18--55mm lens has focal length range of [18--55], so a value in that
13030 range should be chosen when using that lens. Default 18.
13033 The aperture of the image/video (expected constant for video). Note that
13034 aperture is only used for vignetting correction. Default 3.5.
13036 @item focus_distance
13037 The focus distance of the image/video (expected constant for video). Note that
13038 focus distance is only used for vignetting and only slightly affects the
13039 vignetting correction process. If unknown, leave it at the default value (which
13043 The scale factor which is applied after transformation. After correction the
13044 video is no longer necessarily rectangular. This parameter controls how much of
13045 the resulting image is visible. The value 0 means that a value will be chosen
13046 automatically such that there is little or no unmapped area in the output
13047 image. 1.0 means that no additional scaling is done. Lower values may result
13048 in more of the corrected image being visible, while higher values may avoid
13049 unmapped areas in the output.
13051 @item target_geometry
13052 The target geometry of the output image/video. The following values are valid
13056 @item rectilinear (default)
13059 @item equirectangular
13060 @item fisheye_orthographic
13061 @item fisheye_stereographic
13062 @item fisheye_equisolid
13063 @item fisheye_thoby
13066 Apply the reverse of image correction (instead of correcting distortion, apply
13069 @item interpolation
13070 The type of interpolation used when correcting distortion. The following values
13075 @item linear (default)
13080 @subsection Examples
13084 Apply lens correction with make "Canon", camera model "Canon EOS 100D", and lens
13085 model "Canon EF-S 18-55mm f/3.5-5.6 IS STM" with focal length of "18" and
13089 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
13093 Apply the same as before, but only for the first 5 seconds of video.
13096 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
13103 Obtain the VMAF (Video Multi-Method Assessment Fusion)
13104 score between two input videos.
13106 The obtained VMAF score is printed through the logging system.
13108 It requires Netflix's vmaf library (libvmaf) as a pre-requisite.
13109 After installing the library it can be enabled using:
13110 @code{./configure --enable-libvmaf}.
13111 If no model path is specified it uses the default model: @code{vmaf_v0.6.1.pkl}.
13113 The filter has following options:
13117 Set the model path which is to be used for SVM.
13118 Default value: @code{"/usr/local/share/model/vmaf_v0.6.1.pkl"}
13121 Set the file path to be used to store logs.
13124 Set the format of the log file (csv, json or xml).
13126 @item enable_transform
13127 This option can enable/disable the @code{score_transform} applied to the final predicted VMAF score,
13128 if you have specified score_transform option in the input parameter file passed to @code{run_vmaf_training.py}
13129 Default value: @code{false}
13132 Invokes the phone model which will generate VMAF scores higher than in the
13133 regular model, which is more suitable for laptop, TV, etc. viewing conditions.
13134 Default value: @code{false}
13137 Enables computing psnr along with vmaf.
13138 Default value: @code{false}
13141 Enables computing ssim along with vmaf.
13142 Default value: @code{false}
13145 Enables computing ms_ssim along with vmaf.
13146 Default value: @code{false}
13149 Set the pool method to be used for computing vmaf.
13150 Options are @code{min}, @code{harmonic_mean} or @code{mean} (default).
13153 Set number of threads to be used when computing vmaf.
13154 Default value: @code{0}, which makes use of all available logical processors.
13157 Set interval for frame subsampling used when computing vmaf.
13158 Default value: @code{1}
13160 @item enable_conf_interval
13161 Enables confidence interval.
13162 Default value: @code{false}
13165 This filter also supports the @ref{framesync} options.
13167 @subsection Examples
13170 On the below examples the input file @file{main.mpg} being processed is
13171 compared with the reference file @file{ref.mpg}.
13174 ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf -f null -
13178 Example with options:
13180 ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf="psnr=1:log_fmt=json" -f null -
13184 Example with options and different containers:
13186 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 -
13192 Limits the pixel components values to the specified range [min, max].
13194 The filter accepts the following options:
13198 Lower bound. Defaults to the lowest allowed value for the input.
13201 Upper bound. Defaults to the highest allowed value for the input.
13204 Specify which planes will be processed. Defaults to all available.
13211 The filter accepts the following options:
13215 Set the number of loops. Setting this value to -1 will result in infinite loops.
13219 Set maximal size in number of frames. Default is 0.
13222 Set first frame of loop. Default is 0.
13225 @subsection Examples
13229 Loop single first frame infinitely:
13231 loop=loop=-1:size=1:start=0
13235 Loop single first frame 10 times:
13237 loop=loop=10:size=1:start=0
13241 Loop 10 first frames 5 times:
13243 loop=loop=5:size=10:start=0
13249 Apply a 1D LUT to an input video.
13251 The filter accepts the following options:
13255 Set the 1D LUT file name.
13257 Currently supported formats:
13266 Select interpolation mode.
13268 Available values are:
13272 Use values from the nearest defined point.
13274 Interpolate values using the linear interpolation.
13276 Interpolate values using the cosine interpolation.
13278 Interpolate values using the cubic interpolation.
13280 Interpolate values using the spline interpolation.
13287 Apply a 3D LUT to an input video.
13289 The filter accepts the following options:
13293 Set the 3D LUT file name.
13295 Currently supported formats:
13309 Select interpolation mode.
13311 Available values are:
13315 Use values from the nearest defined point.
13317 Interpolate values using the 8 points defining a cube.
13319 Interpolate values using a tetrahedron.
13325 Turn certain luma values into transparency.
13327 The filter accepts the following options:
13331 Set the luma which will be used as base for transparency.
13332 Default value is @code{0}.
13335 Set the range of luma values to be keyed out.
13336 Default value is @code{0.01}.
13339 Set the range of softness. Default value is @code{0}.
13340 Use this to control gradual transition from zero to full transparency.
13343 @subsection Commands
13344 This filter supports same @ref{commands} as options.
13345 The command accepts the same syntax of the corresponding option.
13347 If the specified expression is not valid, it is kept at its current
13350 @section lut, lutrgb, lutyuv
13352 Compute a look-up table for binding each pixel component input value
13353 to an output value, and apply it to the input video.
13355 @var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb}
13356 to an RGB input video.
13358 These filters accept the following parameters:
13361 set first pixel component expression
13363 set second pixel component expression
13365 set third pixel component expression
13367 set fourth pixel component expression, corresponds to the alpha component
13370 set red component expression
13372 set green component expression
13374 set blue component expression
13376 alpha component expression
13379 set Y/luminance component expression
13381 set U/Cb component expression
13383 set V/Cr component expression
13386 Each of them specifies the expression to use for computing the lookup table for
13387 the corresponding pixel component values.
13389 The exact component associated to each of the @var{c*} options depends on the
13392 The @var{lut} filter requires either YUV or RGB pixel formats in input,
13393 @var{lutrgb} requires RGB pixel formats in input, and @var{lutyuv} requires YUV.
13395 The expressions can contain the following constants and functions:
13400 The input width and height.
13403 The input value for the pixel component.
13406 The input value, clipped to the @var{minval}-@var{maxval} range.
13409 The maximum value for the pixel component.
13412 The minimum value for the pixel component.
13415 The negated value for the pixel component value, clipped to the
13416 @var{minval}-@var{maxval} range; it corresponds to the expression
13417 "maxval-clipval+minval".
13420 The computed value in @var{val}, clipped to the
13421 @var{minval}-@var{maxval} range.
13423 @item gammaval(gamma)
13424 The computed gamma correction value of the pixel component value,
13425 clipped to the @var{minval}-@var{maxval} range. It corresponds to the
13427 "pow((clipval-minval)/(maxval-minval)\,@var{gamma})*(maxval-minval)+minval"
13431 All expressions default to "val".
13433 @subsection Examples
13437 Negate input video:
13439 lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val"
13440 lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val"
13443 The above is the same as:
13445 lutrgb="r=negval:g=negval:b=negval"
13446 lutyuv="y=negval:u=negval:v=negval"
13456 Remove chroma components, turning the video into a graytone image:
13458 lutyuv="u=128:v=128"
13462 Apply a luma burning effect:
13468 Remove green and blue components:
13474 Set a constant alpha channel value on input:
13476 format=rgba,lutrgb=a="maxval-minval/2"
13480 Correct luminance gamma by a factor of 0.5:
13482 lutyuv=y=gammaval(0.5)
13486 Discard least significant bits of luma:
13488 lutyuv=y='bitand(val, 128+64+32)'
13492 Technicolor like effect:
13494 lutyuv=u='(val-maxval/2)*2+maxval/2':v='(val-maxval/2)*2+maxval/2'
13498 @section lut2, tlut2
13500 The @code{lut2} filter takes two input streams and outputs one
13503 The @code{tlut2} (time lut2) filter takes two consecutive frames
13504 from one single stream.
13506 This filter accepts the following parameters:
13509 set first pixel component expression
13511 set second pixel component expression
13513 set third pixel component expression
13515 set fourth pixel component expression, corresponds to the alpha component
13518 set output bit depth, only available for @code{lut2} filter. By default is 0,
13519 which means bit depth is automatically picked from first input format.
13522 The @code{lut2} filter also supports the @ref{framesync} options.
13524 Each of them specifies the expression to use for computing the lookup table for
13525 the corresponding pixel component values.
13527 The exact component associated to each of the @var{c*} options depends on the
13530 The expressions can contain the following constants:
13535 The input width and height.
13538 The first input value for the pixel component.
13541 The second input value for the pixel component.
13544 The first input video bit depth.
13547 The second input video bit depth.
13550 All expressions default to "x".
13552 @subsection Examples
13556 Highlight differences between two RGB video streams:
13558 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)'
13562 Highlight differences between two YUV video streams:
13564 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)'
13568 Show max difference between two video streams:
13570 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)))'
13574 @section maskedclamp
13576 Clamp the first input stream with the second input and third input stream.
13578 Returns the value of first stream to be between second input
13579 stream - @code{undershoot} and third input stream + @code{overshoot}.
13581 This filter accepts the following options:
13584 Default value is @code{0}.
13587 Default value is @code{0}.
13590 Set which planes will be processed as bitmap, unprocessed planes will be
13591 copied from first stream.
13592 By default value 0xf, all planes will be processed.
13597 Merge the second and third input stream into output stream using absolute differences
13598 between second input stream and first input stream and absolute difference between
13599 third input stream and first input stream. The picked value will be from second input
13600 stream if second absolute difference is greater than first one or from third input stream
13603 This filter accepts the following options:
13606 Set which planes will be processed as bitmap, unprocessed planes will be
13607 copied from first stream.
13608 By default value 0xf, all planes will be processed.
13611 @section maskedmerge
13613 Merge the first input stream with the second input stream using per pixel
13614 weights in the third input stream.
13616 A value of 0 in the third stream pixel component means that pixel component
13617 from first stream is returned unchanged, while maximum value (eg. 255 for
13618 8-bit videos) means that pixel component from second stream is returned
13619 unchanged. Intermediate values define the amount of merging between both
13620 input stream's pixel components.
13622 This filter accepts the following options:
13625 Set which planes will be processed as bitmap, unprocessed planes will be
13626 copied from first stream.
13627 By default value 0xf, all planes will be processed.
13632 Merge the second and third input stream into output stream using absolute differences
13633 between second input stream and first input stream and absolute difference between
13634 third input stream and first input stream. The picked value will be from second input
13635 stream if second absolute difference is less than first one or from third input stream
13638 This filter accepts the following options:
13641 Set which planes will be processed as bitmap, unprocessed planes will be
13642 copied from first stream.
13643 By default value 0xf, all planes will be processed.
13646 @section maskedthreshold
13647 Pick pixels comparing absolute difference of two video streams with fixed
13650 If absolute difference between pixel component of first and second video
13651 stream is equal or lower than user supplied threshold than pixel component
13652 from first video stream is picked, otherwise pixel component from second
13653 video stream is picked.
13655 This filter accepts the following options:
13658 Set threshold used when picking pixels from absolute difference from two input
13662 Set which planes will be processed as bitmap, unprocessed planes will be
13663 copied from second stream.
13664 By default value 0xf, all planes will be processed.
13668 Create mask from input video.
13670 For example it is useful to create motion masks after @code{tblend} filter.
13672 This filter accepts the following options:
13676 Set low threshold. Any pixel component lower or exact than this value will be set to 0.
13679 Set high threshold. Any pixel component higher than this value will be set to max value
13680 allowed for current pixel format.
13683 Set planes to filter, by default all available planes are filtered.
13686 Fill all frame pixels with this value.
13689 Set max average pixel value for frame. If sum of all pixel components is higher that this
13690 average, output frame will be completely filled with value set by @var{fill} option.
13691 Typically useful for scene changes when used in combination with @code{tblend} filter.
13696 Apply motion-compensation deinterlacing.
13698 It needs one field per frame as input and must thus be used together
13699 with yadif=1/3 or equivalent.
13701 This filter accepts the following options:
13704 Set the deinterlacing mode.
13706 It accepts one of the following values:
13711 use iterative motion estimation
13713 like @samp{slow}, but use multiple reference frames.
13715 Default value is @samp{fast}.
13718 Set the picture field parity assumed for the input video. It must be
13719 one of the following values:
13723 assume top field first
13725 assume bottom field first
13728 Default value is @samp{bff}.
13731 Set per-block quantization parameter (QP) used by the internal
13734 Higher values should result in a smoother motion vector field but less
13735 optimal individual vectors. Default value is 1.
13740 Pick median pixel from certain rectangle defined by radius.
13742 This filter accepts the following options:
13746 Set horizontal radius size. Default value is @code{1}.
13747 Allowed range is integer from 1 to 127.
13750 Set which planes to process. Default is @code{15}, which is all available planes.
13753 Set vertical radius size. Default value is @code{0}.
13754 Allowed range is integer from 0 to 127.
13755 If it is 0, value will be picked from horizontal @code{radius} option.
13758 Set median percentile. Default value is @code{0.5}.
13759 Default value of @code{0.5} will pick always median values, while @code{0} will pick
13760 minimum values, and @code{1} maximum values.
13763 @subsection Commands
13764 This filter supports same @ref{commands} as options.
13765 The command accepts the same syntax of the corresponding option.
13767 If the specified expression is not valid, it is kept at its current
13770 @section mergeplanes
13772 Merge color channel components from several video streams.
13774 The filter accepts up to 4 input streams, and merge selected input
13775 planes to the output video.
13777 This filter accepts the following options:
13780 Set input to output plane mapping. Default is @code{0}.
13782 The mappings is specified as a bitmap. It should be specified as a
13783 hexadecimal number in the form 0xAa[Bb[Cc[Dd]]]. 'Aa' describes the
13784 mapping for the first plane of the output stream. 'A' sets the number of
13785 the input stream to use (from 0 to 3), and 'a' the plane number of the
13786 corresponding input to use (from 0 to 3). The rest of the mappings is
13787 similar, 'Bb' describes the mapping for the output stream second
13788 plane, 'Cc' describes the mapping for the output stream third plane and
13789 'Dd' describes the mapping for the output stream fourth plane.
13792 Set output pixel format. Default is @code{yuva444p}.
13795 @subsection Examples
13799 Merge three gray video streams of same width and height into single video stream:
13801 [a0][a1][a2]mergeplanes=0x001020:yuv444p
13805 Merge 1st yuv444p stream and 2nd gray video stream into yuva444p video stream:
13807 [a0][a1]mergeplanes=0x00010210:yuva444p
13811 Swap Y and A plane in yuva444p stream:
13813 format=yuva444p,mergeplanes=0x03010200:yuva444p
13817 Swap U and V plane in yuv420p stream:
13819 format=yuv420p,mergeplanes=0x000201:yuv420p
13823 Cast a rgb24 clip to yuv444p:
13825 format=rgb24,mergeplanes=0x000102:yuv444p
13831 Estimate and export motion vectors using block matching algorithms.
13832 Motion vectors are stored in frame side data to be used by other filters.
13834 This filter accepts the following options:
13837 Specify the motion estimation method. Accepts one of the following values:
13841 Exhaustive search algorithm.
13843 Three step search algorithm.
13845 Two dimensional logarithmic search algorithm.
13847 New three step search algorithm.
13849 Four step search algorithm.
13851 Diamond search algorithm.
13853 Hexagon-based search algorithm.
13855 Enhanced predictive zonal search algorithm.
13857 Uneven multi-hexagon search algorithm.
13859 Default value is @samp{esa}.
13862 Macroblock size. Default @code{16}.
13865 Search parameter. Default @code{7}.
13868 @section midequalizer
13870 Apply Midway Image Equalization effect using two video streams.
13872 Midway Image Equalization adjusts a pair of images to have the same
13873 histogram, while maintaining their dynamics as much as possible. It's
13874 useful for e.g. matching exposures from a pair of stereo cameras.
13876 This filter has two inputs and one output, which must be of same pixel format, but
13877 may be of different sizes. The output of filter is first input adjusted with
13878 midway histogram of both inputs.
13880 This filter accepts the following option:
13884 Set which planes to process. Default is @code{15}, which is all available planes.
13887 @section minterpolate
13889 Convert the video to specified frame rate using motion interpolation.
13891 This filter accepts the following options:
13894 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}.
13897 Motion interpolation mode. Following values are accepted:
13900 Duplicate previous or next frame for interpolating new ones.
13902 Blend source frames. Interpolated frame is mean of previous and next frames.
13904 Motion compensated interpolation. Following options are effective when this mode is selected:
13908 Motion compensation mode. Following values are accepted:
13911 Overlapped block motion compensation.
13913 Adaptive overlapped block motion compensation. Window weighting coefficients are controlled adaptively according to the reliabilities of the neighboring motion vectors to reduce oversmoothing.
13915 Default mode is @samp{obmc}.
13918 Motion estimation mode. Following values are accepted:
13921 Bidirectional motion estimation. Motion vectors are estimated for each source frame in both forward and backward directions.
13923 Bilateral motion estimation. Motion vectors are estimated directly for interpolated frame.
13925 Default mode is @samp{bilat}.
13928 The algorithm to be used for motion estimation. Following values are accepted:
13931 Exhaustive search algorithm.
13933 Three step search algorithm.
13935 Two dimensional logarithmic search algorithm.
13937 New three step search algorithm.
13939 Four step search algorithm.
13941 Diamond search algorithm.
13943 Hexagon-based search algorithm.
13945 Enhanced predictive zonal search algorithm.
13947 Uneven multi-hexagon search algorithm.
13949 Default algorithm is @samp{epzs}.
13952 Macroblock size. Default @code{16}.
13955 Motion estimation search parameter. Default @code{32}.
13958 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).
13963 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:
13966 Disable scene change detection.
13968 Frame difference. Corresponding pixel values are compared and if it satisfies @var{scd_threshold} scene change is detected.
13970 Default method is @samp{fdiff}.
13972 @item scd_threshold
13973 Scene change detection threshold. Default is @code{10.}.
13978 Mix several video input streams into one video stream.
13980 A description of the accepted options follows.
13984 The number of inputs. If unspecified, it defaults to 2.
13987 Specify weight of each input video stream as sequence.
13988 Each weight is separated by space. If number of weights
13989 is smaller than number of @var{frames} last specified
13990 weight will be used for all remaining unset weights.
13993 Specify scale, if it is set it will be multiplied with sum
13994 of each weight multiplied with pixel values to give final destination
13995 pixel value. By default @var{scale} is auto scaled to sum of weights.
13998 Specify how end of stream is determined.
14001 The duration of the longest input. (default)
14004 The duration of the shortest input.
14007 The duration of the first input.
14011 @section mpdecimate
14013 Drop frames that do not differ greatly from the previous frame in
14014 order to reduce frame rate.
14016 The main use of this filter is for very-low-bitrate encoding
14017 (e.g. streaming over dialup modem), but it could in theory be used for
14018 fixing movies that were inverse-telecined incorrectly.
14020 A description of the accepted options follows.
14024 Set the maximum number of consecutive frames which can be dropped (if
14025 positive), or the minimum interval between dropped frames (if
14026 negative). If the value is 0, the frame is dropped disregarding the
14027 number of previous sequentially dropped frames.
14029 Default value is 0.
14034 Set the dropping threshold values.
14036 Values for @option{hi} and @option{lo} are for 8x8 pixel blocks and
14037 represent actual pixel value differences, so a threshold of 64
14038 corresponds to 1 unit of difference for each pixel, or the same spread
14039 out differently over the block.
14041 A frame is a candidate for dropping if no 8x8 blocks differ by more
14042 than a threshold of @option{hi}, and if no more than @option{frac} blocks (1
14043 meaning the whole image) differ by more than a threshold of @option{lo}.
14045 Default value for @option{hi} is 64*12, default value for @option{lo} is
14046 64*5, and default value for @option{frac} is 0.33.
14052 Negate (invert) the input video.
14054 It accepts the following option:
14059 With value 1, it negates the alpha component, if present. Default value is 0.
14065 Denoise frames using Non-Local Means algorithm.
14067 Each pixel is adjusted by looking for other pixels with similar contexts. This
14068 context similarity is defined by comparing their surrounding patches of size
14069 @option{p}x@option{p}. Patches are searched in an area of @option{r}x@option{r}
14072 Note that the research area defines centers for patches, which means some
14073 patches will be made of pixels outside that research area.
14075 The filter accepts the following options.
14079 Set denoising strength. Default is 1.0. Must be in range [1.0, 30.0].
14082 Set patch size. Default is 7. Must be odd number in range [0, 99].
14085 Same as @option{p} but for chroma planes.
14087 The default value is @var{0} and means automatic.
14090 Set research size. Default is 15. Must be odd number in range [0, 99].
14093 Same as @option{r} but for chroma planes.
14095 The default value is @var{0} and means automatic.
14100 Deinterlace video using neural network edge directed interpolation.
14102 This filter accepts the following options:
14106 Mandatory option, without binary file filter can not work.
14107 Currently file can be found here:
14108 https://github.com/dubhater/vapoursynth-nnedi3/blob/master/src/nnedi3_weights.bin
14111 Set which frames to deinterlace, by default it is @code{all}.
14112 Can be @code{all} or @code{interlaced}.
14115 Set mode of operation.
14117 Can be one of the following:
14121 Use frame flags, both fields.
14123 Use frame flags, single field.
14125 Use top field only.
14127 Use bottom field only.
14129 Use both fields, top first.
14131 Use both fields, bottom first.
14135 Set which planes to process, by default filter process all frames.
14138 Set size of local neighborhood around each pixel, used by the predictor neural
14141 Can be one of the following:
14154 Set the number of neurons in predictor neural network.
14155 Can be one of the following:
14166 Controls the number of different neural network predictions that are blended
14167 together to compute the final output value. Can be @code{fast}, default or
14171 Set which set of weights to use in the predictor.
14172 Can be one of the following:
14176 weights trained to minimize absolute error
14178 weights trained to minimize squared error
14182 Controls whether or not the prescreener neural network is used to decide
14183 which pixels should be processed by the predictor neural network and which
14184 can be handled by simple cubic interpolation.
14185 The prescreener is trained to know whether cubic interpolation will be
14186 sufficient for a pixel or whether it should be predicted by the predictor nn.
14187 The computational complexity of the prescreener nn is much less than that of
14188 the predictor nn. Since most pixels can be handled by cubic interpolation,
14189 using the prescreener generally results in much faster processing.
14190 The prescreener is pretty accurate, so the difference between using it and not
14191 using it is almost always unnoticeable.
14193 Can be one of the following:
14201 Default is @code{new}.
14204 Set various debugging flags.
14209 Force libavfilter not to use any of the specified pixel formats for the
14210 input to the next filter.
14212 It accepts the following parameters:
14216 A '|'-separated list of pixel format names, such as
14217 pix_fmts=yuv420p|monow|rgb24".
14221 @subsection Examples
14225 Force libavfilter to use a format different from @var{yuv420p} for the
14226 input to the vflip filter:
14228 noformat=pix_fmts=yuv420p,vflip
14232 Convert the input video to any of the formats not contained in the list:
14234 noformat=yuv420p|yuv444p|yuv410p
14240 Add noise on video input frame.
14242 The filter accepts the following options:
14250 Set noise seed for specific pixel component or all pixel components in case
14251 of @var{all_seed}. Default value is @code{123457}.
14253 @item all_strength, alls
14254 @item c0_strength, c0s
14255 @item c1_strength, c1s
14256 @item c2_strength, c2s
14257 @item c3_strength, c3s
14258 Set noise strength for specific pixel component or all pixel components in case
14259 @var{all_strength}. Default value is @code{0}. Allowed range is [0, 100].
14261 @item all_flags, allf
14262 @item c0_flags, c0f
14263 @item c1_flags, c1f
14264 @item c2_flags, c2f
14265 @item c3_flags, c3f
14266 Set pixel component flags or set flags for all components if @var{all_flags}.
14267 Available values for component flags are:
14270 averaged temporal noise (smoother)
14272 mix random noise with a (semi)regular pattern
14274 temporal noise (noise pattern changes between frames)
14276 uniform noise (gaussian otherwise)
14280 @subsection Examples
14282 Add temporal and uniform noise to input video:
14284 noise=alls=20:allf=t+u
14289 Normalize RGB video (aka histogram stretching, contrast stretching).
14290 See: https://en.wikipedia.org/wiki/Normalization_(image_processing)
14292 For each channel of each frame, the filter computes the input range and maps
14293 it linearly to the user-specified output range. The output range defaults
14294 to the full dynamic range from pure black to pure white.
14296 Temporal smoothing can be used on the input range to reduce flickering (rapid
14297 changes in brightness) caused when small dark or bright objects enter or leave
14298 the scene. This is similar to the auto-exposure (automatic gain control) on a
14299 video camera, and, like a video camera, it may cause a period of over- or
14300 under-exposure of the video.
14302 The R,G,B channels can be normalized independently, which may cause some
14303 color shifting, or linked together as a single channel, which prevents
14304 color shifting. Linked normalization preserves hue. Independent normalization
14305 does not, so it can be used to remove some color casts. Independent and linked
14306 normalization can be combined in any ratio.
14308 The normalize filter accepts the following options:
14313 Colors which define the output range. The minimum input value is mapped to
14314 the @var{blackpt}. The maximum input value is mapped to the @var{whitept}.
14315 The defaults are black and white respectively. Specifying white for
14316 @var{blackpt} and black for @var{whitept} will give color-inverted,
14317 normalized video. Shades of grey can be used to reduce the dynamic range
14318 (contrast). Specifying saturated colors here can create some interesting
14322 The number of previous frames to use for temporal smoothing. The input range
14323 of each channel is smoothed using a rolling average over the current frame
14324 and the @var{smoothing} previous frames. The default is 0 (no temporal
14328 Controls the ratio of independent (color shifting) channel normalization to
14329 linked (color preserving) normalization. 0.0 is fully linked, 1.0 is fully
14330 independent. Defaults to 1.0 (fully independent).
14333 Overall strength of the filter. 1.0 is full strength. 0.0 is a rather
14334 expensive no-op. Defaults to 1.0 (full strength).
14338 @subsection Commands
14339 This filter supports same @ref{commands} as options, excluding @var{smoothing} option.
14340 The command accepts the same syntax of the corresponding option.
14342 If the specified expression is not valid, it is kept at its current
14345 @subsection Examples
14347 Stretch video contrast to use the full dynamic range, with no temporal
14348 smoothing; may flicker depending on the source content:
14350 normalize=blackpt=black:whitept=white:smoothing=0
14353 As above, but with 50 frames of temporal smoothing; flicker should be
14354 reduced, depending on the source content:
14356 normalize=blackpt=black:whitept=white:smoothing=50
14359 As above, but with hue-preserving linked channel normalization:
14361 normalize=blackpt=black:whitept=white:smoothing=50:independence=0
14364 As above, but with half strength:
14366 normalize=blackpt=black:whitept=white:smoothing=50:independence=0:strength=0.5
14369 Map the darkest input color to red, the brightest input color to cyan:
14371 normalize=blackpt=red:whitept=cyan
14376 Pass the video source unchanged to the output.
14379 Optical Character Recognition
14381 This filter uses Tesseract for optical character recognition. To enable
14382 compilation of this filter, you need to configure FFmpeg with
14383 @code{--enable-libtesseract}.
14385 It accepts the following options:
14389 Set datapath to tesseract data. Default is to use whatever was
14390 set at installation.
14393 Set language, default is "eng".
14396 Set character whitelist.
14399 Set character blacklist.
14402 The filter exports recognized text as the frame metadata @code{lavfi.ocr.text}.
14403 The filter exports confidence of recognized words as the frame metadata @code{lavfi.ocr.confidence}.
14407 Apply a video transform using libopencv.
14409 To enable this filter, install the libopencv library and headers and
14410 configure FFmpeg with @code{--enable-libopencv}.
14412 It accepts the following parameters:
14417 The name of the libopencv filter to apply.
14419 @item filter_params
14420 The parameters to pass to the libopencv filter. If not specified, the default
14421 values are assumed.
14425 Refer to the official libopencv documentation for more precise
14427 @url{http://docs.opencv.org/master/modules/imgproc/doc/filtering.html}
14429 Several libopencv filters are supported; see the following subsections.
14434 Dilate an image by using a specific structuring element.
14435 It corresponds to the libopencv function @code{cvDilate}.
14437 It accepts the parameters: @var{struct_el}|@var{nb_iterations}.
14439 @var{struct_el} represents a structuring element, and has the syntax:
14440 @var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape}
14442 @var{cols} and @var{rows} represent the number of columns and rows of
14443 the structuring element, @var{anchor_x} and @var{anchor_y} the anchor
14444 point, and @var{shape} the shape for the structuring element. @var{shape}
14445 must be "rect", "cross", "ellipse", or "custom".
14447 If the value for @var{shape} is "custom", it must be followed by a
14448 string of the form "=@var{filename}". The file with name
14449 @var{filename} is assumed to represent a binary image, with each
14450 printable character corresponding to a bright pixel. When a custom
14451 @var{shape} is used, @var{cols} and @var{rows} are ignored, the number
14452 or columns and rows of the read file are assumed instead.
14454 The default value for @var{struct_el} is "3x3+0x0/rect".
14456 @var{nb_iterations} specifies the number of times the transform is
14457 applied to the image, and defaults to 1.
14461 # Use the default values
14464 # Dilate using a structuring element with a 5x5 cross, iterating two times
14465 ocv=filter_name=dilate:filter_params=5x5+2x2/cross|2
14467 # Read the shape from the file diamond.shape, iterating two times.
14468 # The file diamond.shape may contain a pattern of characters like this
14474 # The specified columns and rows are ignored
14475 # but the anchor point coordinates are not
14476 ocv=dilate:0x0+2x2/custom=diamond.shape|2
14481 Erode an image by using a specific structuring element.
14482 It corresponds to the libopencv function @code{cvErode}.
14484 It accepts the parameters: @var{struct_el}:@var{nb_iterations},
14485 with the same syntax and semantics as the @ref{dilate} filter.
14489 Smooth the input video.
14491 The filter takes the following parameters:
14492 @var{type}|@var{param1}|@var{param2}|@var{param3}|@var{param4}.
14494 @var{type} is the type of smooth filter to apply, and must be one of
14495 the following values: "blur", "blur_no_scale", "median", "gaussian",
14496 or "bilateral". The default value is "gaussian".
14498 The meaning of @var{param1}, @var{param2}, @var{param3}, and @var{param4}
14499 depends on the smooth type. @var{param1} and
14500 @var{param2} accept integer positive values or 0. @var{param3} and
14501 @var{param4} accept floating point values.
14503 The default value for @var{param1} is 3. The default value for the
14504 other parameters is 0.
14506 These parameters correspond to the parameters assigned to the
14507 libopencv function @code{cvSmooth}.
14509 @section oscilloscope
14511 2D Video Oscilloscope.
14513 Useful to measure spatial impulse, step responses, chroma delays, etc.
14515 It accepts the following parameters:
14519 Set scope center x position.
14522 Set scope center y position.
14525 Set scope size, relative to frame diagonal.
14528 Set scope tilt/rotation.
14534 Set trace center x position.
14537 Set trace center y position.
14540 Set trace width, relative to width of frame.
14543 Set trace height, relative to height of frame.
14546 Set which components to trace. By default it traces first three components.
14549 Draw trace grid. By default is enabled.
14552 Draw some statistics. By default is enabled.
14555 Draw scope. By default is enabled.
14558 @subsection Commands
14559 This filter supports same @ref{commands} as options.
14560 The command accepts the same syntax of the corresponding option.
14562 If the specified expression is not valid, it is kept at its current
14565 @subsection Examples
14569 Inspect full first row of video frame.
14571 oscilloscope=x=0.5:y=0:s=1
14575 Inspect full last row of video frame.
14577 oscilloscope=x=0.5:y=1:s=1
14581 Inspect full 5th line of video frame of height 1080.
14583 oscilloscope=x=0.5:y=5/1080:s=1
14587 Inspect full last column of video frame.
14589 oscilloscope=x=1:y=0.5:s=1:t=1
14597 Overlay one video on top of another.
14599 It takes two inputs and has one output. The first input is the "main"
14600 video on which the second input is overlaid.
14602 It accepts the following parameters:
14604 A description of the accepted options follows.
14609 Set the expression for the x and y coordinates of the overlaid video
14610 on the main video. Default value is "0" for both expressions. In case
14611 the expression is invalid, it is set to a huge value (meaning that the
14612 overlay will not be displayed within the output visible area).
14615 See @ref{framesync}.
14618 Set when the expressions for @option{x}, and @option{y} are evaluated.
14620 It accepts the following values:
14623 only evaluate expressions once during the filter initialization or
14624 when a command is processed
14627 evaluate expressions for each incoming frame
14630 Default value is @samp{frame}.
14633 See @ref{framesync}.
14636 Set the format for the output video.
14638 It accepts the following values:
14641 force YUV420 output
14644 force YUV420p10 output
14647 force YUV422 output
14650 force YUV422p10 output
14653 force YUV444 output
14656 force packed RGB output
14659 force planar RGB output
14662 automatically pick format
14665 Default value is @samp{yuv420}.
14668 See @ref{framesync}.
14671 Set format of alpha of the overlaid video, it can be @var{straight} or
14672 @var{premultiplied}. Default is @var{straight}.
14675 The @option{x}, and @option{y} expressions can contain the following
14681 The main input width and height.
14685 The overlay input width and height.
14689 The computed values for @var{x} and @var{y}. They are evaluated for
14694 horizontal and vertical chroma subsample values of the output
14695 format. For example for the pixel format "yuv422p" @var{hsub} is 2 and
14699 the number of input frame, starting from 0
14702 the position in the file of the input frame, NAN if unknown
14705 The timestamp, expressed in seconds. It's NAN if the input timestamp is unknown.
14709 This filter also supports the @ref{framesync} options.
14711 Note that the @var{n}, @var{pos}, @var{t} variables are available only
14712 when evaluation is done @emph{per frame}, and will evaluate to NAN
14713 when @option{eval} is set to @samp{init}.
14715 Be aware that frames are taken from each input video in timestamp
14716 order, hence, if their initial timestamps differ, it is a good idea
14717 to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to
14718 have them begin in the same zero timestamp, as the example for
14719 the @var{movie} filter does.
14721 You can chain together more overlays but you should test the
14722 efficiency of such approach.
14724 @subsection Commands
14726 This filter supports the following commands:
14730 Modify the x and y of the overlay input.
14731 The command accepts the same syntax of the corresponding option.
14733 If the specified expression is not valid, it is kept at its current
14737 @subsection Examples
14741 Draw the overlay at 10 pixels from the bottom right corner of the main
14744 overlay=main_w-overlay_w-10:main_h-overlay_h-10
14747 Using named options the example above becomes:
14749 overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10
14753 Insert a transparent PNG logo in the bottom left corner of the input,
14754 using the @command{ffmpeg} tool with the @code{-filter_complex} option:
14756 ffmpeg -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output
14760 Insert 2 different transparent PNG logos (second logo on bottom
14761 right corner) using the @command{ffmpeg} tool:
14763 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
14767 Add a transparent color layer on top of the main video; @code{WxH}
14768 must specify the size of the main input to the overlay filter:
14770 color=color=red@@.3:size=WxH [over]; [in][over] overlay [out]
14774 Play an original video and a filtered version (here with the deshake
14775 filter) side by side using the @command{ffplay} tool:
14777 ffplay input.avi -vf 'split[a][b]; [a]pad=iw*2:ih[src]; [b]deshake[filt]; [src][filt]overlay=w'
14780 The above command is the same as:
14782 ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w'
14786 Make a sliding overlay appearing from the left to the right top part of the
14787 screen starting since time 2:
14789 overlay=x='if(gte(t,2), -w+(t-2)*20, NAN)':y=0
14793 Compose output by putting two input videos side to side:
14795 ffmpeg -i left.avi -i right.avi -filter_complex "
14796 nullsrc=size=200x100 [background];
14797 [0:v] setpts=PTS-STARTPTS, scale=100x100 [left];
14798 [1:v] setpts=PTS-STARTPTS, scale=100x100 [right];
14799 [background][left] overlay=shortest=1 [background+left];
14800 [background+left][right] overlay=shortest=1:x=100 [left+right]
14805 Mask 10-20 seconds of a video by applying the delogo filter to a section
14807 ffmpeg -i test.avi -codec:v:0 wmv2 -ar 11025 -b:v 9000k
14808 -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]'
14813 Chain several overlays in cascade:
14815 nullsrc=s=200x200 [bg];
14816 testsrc=s=100x100, split=4 [in0][in1][in2][in3];
14817 [in0] lutrgb=r=0, [bg] overlay=0:0 [mid0];
14818 [in1] lutrgb=g=0, [mid0] overlay=100:0 [mid1];
14819 [in2] lutrgb=b=0, [mid1] overlay=0:100 [mid2];
14820 [in3] null, [mid2] overlay=100:100 [out0]
14825 @anchor{overlay_cuda}
14826 @section overlay_cuda
14828 Overlay one video on top of another.
14830 This is the CUDA variant of the @ref{overlay} filter.
14831 It only accepts CUDA frames. The underlying input pixel formats have to match.
14833 It takes two inputs and has one output. The first input is the "main"
14834 video on which the second input is overlaid.
14836 It accepts the following parameters:
14841 Set the x and y coordinates of the overlaid video on the main video.
14842 Default value is "0" for both expressions.
14845 See @ref{framesync}.
14848 See @ref{framesync}.
14851 See @ref{framesync}.
14855 This filter also supports the @ref{framesync} options.
14859 Apply Overcomplete Wavelet denoiser.
14861 The filter accepts the following options:
14867 Larger depth values will denoise lower frequency components more, but
14868 slow down filtering.
14870 Must be an int in the range 8-16, default is @code{8}.
14872 @item luma_strength, ls
14875 Must be a double value in the range 0-1000, default is @code{1.0}.
14877 @item chroma_strength, cs
14878 Set chroma strength.
14880 Must be a double value in the range 0-1000, default is @code{1.0}.
14886 Add paddings to the input image, and place the original input at the
14887 provided @var{x}, @var{y} coordinates.
14889 It accepts the following parameters:
14894 Specify an expression for the size of the output image with the
14895 paddings added. If the value for @var{width} or @var{height} is 0, the
14896 corresponding input size is used for the output.
14898 The @var{width} expression can reference the value set by the
14899 @var{height} expression, and vice versa.
14901 The default value of @var{width} and @var{height} is 0.
14905 Specify the offsets to place the input image at within the padded area,
14906 with respect to the top/left border of the output image.
14908 The @var{x} expression can reference the value set by the @var{y}
14909 expression, and vice versa.
14911 The default value of @var{x} and @var{y} is 0.
14913 If @var{x} or @var{y} evaluate to a negative number, they'll be changed
14914 so the input image is centered on the padded area.
14917 Specify the color of the padded area. For the syntax of this option,
14918 check the @ref{color syntax,,"Color" section in the ffmpeg-utils
14919 manual,ffmpeg-utils}.
14921 The default value of @var{color} is "black".
14924 Specify when to evaluate @var{width}, @var{height}, @var{x} and @var{y} expression.
14926 It accepts the following values:
14930 Only evaluate expressions once during the filter initialization or when
14931 a command is processed.
14934 Evaluate expressions for each incoming frame.
14938 Default value is @samp{init}.
14941 Pad to aspect instead to a resolution.
14945 The value for the @var{width}, @var{height}, @var{x}, and @var{y}
14946 options are expressions containing the following constants:
14951 The input video width and height.
14955 These are the same as @var{in_w} and @var{in_h}.
14959 The output width and height (the size of the padded area), as
14960 specified by the @var{width} and @var{height} expressions.
14964 These are the same as @var{out_w} and @var{out_h}.
14968 The x and y offsets as specified by the @var{x} and @var{y}
14969 expressions, or NAN if not yet specified.
14972 same as @var{iw} / @var{ih}
14975 input sample aspect ratio
14978 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
14982 The horizontal and vertical chroma subsample values. For example for the
14983 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
14986 @subsection Examples
14990 Add paddings with the color "violet" to the input video. The output video
14991 size is 640x480, and the top-left corner of the input video is placed at
14994 pad=640:480:0:40:violet
14997 The example above is equivalent to the following command:
14999 pad=width=640:height=480:x=0:y=40:color=violet
15003 Pad the input to get an output with dimensions increased by 3/2,
15004 and put the input video at the center of the padded area:
15006 pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2"
15010 Pad the input to get a squared output with size equal to the maximum
15011 value between the input width and height, and put the input video at
15012 the center of the padded area:
15014 pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2"
15018 Pad the input to get a final w/h ratio of 16:9:
15020 pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2"
15024 In case of anamorphic video, in order to set the output display aspect
15025 correctly, it is necessary to use @var{sar} in the expression,
15026 according to the relation:
15028 (ih * X / ih) * sar = output_dar
15029 X = output_dar / sar
15032 Thus the previous example needs to be modified to:
15034 pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2"
15038 Double the output size and put the input video in the bottom-right
15039 corner of the output padded area:
15041 pad="2*iw:2*ih:ow-iw:oh-ih"
15045 @anchor{palettegen}
15046 @section palettegen
15048 Generate one palette for a whole video stream.
15050 It accepts the following options:
15054 Set the maximum number of colors to quantize in the palette.
15055 Note: the palette will still contain 256 colors; the unused palette entries
15058 @item reserve_transparent
15059 Create a palette of 255 colors maximum and reserve the last one for
15060 transparency. Reserving the transparency color is useful for GIF optimization.
15061 If not set, the maximum of colors in the palette will be 256. You probably want
15062 to disable this option for a standalone image.
15065 @item transparency_color
15066 Set the color that will be used as background for transparency.
15069 Set statistics mode.
15071 It accepts the following values:
15074 Compute full frame histograms.
15076 Compute histograms only for the part that differs from previous frame. This
15077 might be relevant to give more importance to the moving part of your input if
15078 the background is static.
15080 Compute new histogram for each frame.
15083 Default value is @var{full}.
15086 The filter also exports the frame metadata @code{lavfi.color_quant_ratio}
15087 (@code{nb_color_in / nb_color_out}) which you can use to evaluate the degree of
15088 color quantization of the palette. This information is also visible at
15089 @var{info} logging level.
15091 @subsection Examples
15095 Generate a representative palette of a given video using @command{ffmpeg}:
15097 ffmpeg -i input.mkv -vf palettegen palette.png
15101 @section paletteuse
15103 Use a palette to downsample an input video stream.
15105 The filter takes two inputs: one video stream and a palette. The palette must
15106 be a 256 pixels image.
15108 It accepts the following options:
15112 Select dithering mode. Available algorithms are:
15115 Ordered 8x8 bayer dithering (deterministic)
15117 Dithering as defined by Paul Heckbert in 1982 (simple error diffusion).
15118 Note: this dithering is sometimes considered "wrong" and is included as a
15120 @item floyd_steinberg
15121 Floyd and Steingberg dithering (error diffusion)
15123 Frankie Sierra dithering v2 (error diffusion)
15125 Frankie Sierra dithering v2 "Lite" (error diffusion)
15128 Default is @var{sierra2_4a}.
15131 When @var{bayer} dithering is selected, this option defines the scale of the
15132 pattern (how much the crosshatch pattern is visible). A low value means more
15133 visible pattern for less banding, and higher value means less visible pattern
15134 at the cost of more banding.
15136 The option must be an integer value in the range [0,5]. Default is @var{2}.
15139 If set, define the zone to process
15143 Only the changing rectangle will be reprocessed. This is similar to GIF
15144 cropping/offsetting compression mechanism. This option can be useful for speed
15145 if only a part of the image is changing, and has use cases such as limiting the
15146 scope of the error diffusal @option{dither} to the rectangle that bounds the
15147 moving scene (it leads to more deterministic output if the scene doesn't change
15148 much, and as a result less moving noise and better GIF compression).
15151 Default is @var{none}.
15154 Take new palette for each output frame.
15156 @item alpha_threshold
15157 Sets the alpha threshold for transparency. Alpha values above this threshold
15158 will be treated as completely opaque, and values below this threshold will be
15159 treated as completely transparent.
15161 The option must be an integer value in the range [0,255]. Default is @var{128}.
15164 @subsection Examples
15168 Use a palette (generated for example with @ref{palettegen}) to encode a GIF
15169 using @command{ffmpeg}:
15171 ffmpeg -i input.mkv -i palette.png -lavfi paletteuse output.gif
15175 @section perspective
15177 Correct perspective of video not recorded perpendicular to the screen.
15179 A description of the accepted parameters follows.
15190 Set coordinates expression for top left, top right, bottom left and bottom right corners.
15191 Default values are @code{0:0:W:0:0:H:W:H} with which perspective will remain unchanged.
15192 If the @code{sense} option is set to @code{source}, then the specified points will be sent
15193 to the corners of the destination. If the @code{sense} option is set to @code{destination},
15194 then the corners of the source will be sent to the specified coordinates.
15196 The expressions can use the following variables:
15201 the width and height of video frame.
15205 Output frame count.
15208 @item interpolation
15209 Set interpolation for perspective correction.
15211 It accepts the following values:
15217 Default value is @samp{linear}.
15220 Set interpretation of coordinate options.
15222 It accepts the following values:
15226 Send point in the source specified by the given coordinates to
15227 the corners of the destination.
15229 @item 1, destination
15231 Send the corners of the source to the point in the destination specified
15232 by the given coordinates.
15234 Default value is @samp{source}.
15238 Set when the expressions for coordinates @option{x0,y0,...x3,y3} are evaluated.
15240 It accepts the following values:
15243 only evaluate expressions once during the filter initialization or
15244 when a command is processed
15247 evaluate expressions for each incoming frame
15250 Default value is @samp{init}.
15255 Delay interlaced video by one field time so that the field order changes.
15257 The intended use is to fix PAL movies that have been captured with the
15258 opposite field order to the film-to-video transfer.
15260 A description of the accepted parameters follows.
15266 It accepts the following values:
15269 Capture field order top-first, transfer bottom-first.
15270 Filter will delay the bottom field.
15273 Capture field order bottom-first, transfer top-first.
15274 Filter will delay the top field.
15277 Capture and transfer with the same field order. This mode only exists
15278 for the documentation of the other options to refer to, but if you
15279 actually select it, the filter will faithfully do nothing.
15282 Capture field order determined automatically by field flags, transfer
15284 Filter selects among @samp{t} and @samp{b} modes on a frame by frame
15285 basis using field flags. If no field information is available,
15286 then this works just like @samp{u}.
15289 Capture unknown or varying, transfer opposite.
15290 Filter selects among @samp{t} and @samp{b} on a frame by frame basis by
15291 analyzing the images and selecting the alternative that produces best
15292 match between the fields.
15295 Capture top-first, transfer unknown or varying.
15296 Filter selects among @samp{t} and @samp{p} using image analysis.
15299 Capture bottom-first, transfer unknown or varying.
15300 Filter selects among @samp{b} and @samp{p} using image analysis.
15303 Capture determined by field flags, transfer unknown or varying.
15304 Filter selects among @samp{t}, @samp{b} and @samp{p} using field flags and
15305 image analysis. If no field information is available, then this works just
15306 like @samp{U}. This is the default mode.
15309 Both capture and transfer unknown or varying.
15310 Filter selects among @samp{t}, @samp{b} and @samp{p} using image analysis only.
15314 @section photosensitivity
15315 Reduce various flashes in video, so to help users with epilepsy.
15317 It accepts the following options:
15320 Set how many frames to use when filtering. Default is 30.
15323 Set detection threshold factor. Default is 1.
15327 Set how many pixels to skip when sampling frames. Default is 1.
15328 Allowed range is from 1 to 1024.
15331 Leave frames unchanged. Default is disabled.
15334 @section pixdesctest
15336 Pixel format descriptor test filter, mainly useful for internal
15337 testing. The output video should be equal to the input video.
15341 format=monow, pixdesctest
15344 can be used to test the monowhite pixel format descriptor definition.
15348 Display sample values of color channels. Mainly useful for checking color
15349 and levels. Minimum supported resolution is 640x480.
15351 The filters accept the following options:
15355 Set scope X position, relative offset on X axis.
15358 Set scope Y position, relative offset on Y axis.
15367 Set window opacity. This window also holds statistics about pixel area.
15370 Set window X position, relative offset on X axis.
15373 Set window Y position, relative offset on Y axis.
15378 Enable the specified chain of postprocessing subfilters using libpostproc. This
15379 library should be automatically selected with a GPL build (@code{--enable-gpl}).
15380 Subfilters must be separated by '/' and can be disabled by prepending a '-'.
15381 Each subfilter and some options have a short and a long name that can be used
15382 interchangeably, i.e. dr/dering are the same.
15384 The filters accept the following options:
15388 Set postprocessing subfilters string.
15391 All subfilters share common options to determine their scope:
15395 Honor the quality commands for this subfilter.
15398 Do chrominance filtering, too (default).
15401 Do luminance filtering only (no chrominance).
15404 Do chrominance filtering only (no luminance).
15407 These options can be appended after the subfilter name, separated by a '|'.
15409 Available subfilters are:
15412 @item hb/hdeblock[|difference[|flatness]]
15413 Horizontal deblocking filter
15416 Difference factor where higher values mean more deblocking (default: @code{32}).
15418 Flatness threshold where lower values mean more deblocking (default: @code{39}).
15421 @item vb/vdeblock[|difference[|flatness]]
15422 Vertical deblocking filter
15425 Difference factor where higher values mean more deblocking (default: @code{32}).
15427 Flatness threshold where lower values mean more deblocking (default: @code{39}).
15430 @item ha/hadeblock[|difference[|flatness]]
15431 Accurate horizontal deblocking filter
15434 Difference factor where higher values mean more deblocking (default: @code{32}).
15436 Flatness threshold where lower values mean more deblocking (default: @code{39}).
15439 @item va/vadeblock[|difference[|flatness]]
15440 Accurate vertical deblocking filter
15443 Difference factor where higher values mean more deblocking (default: @code{32}).
15445 Flatness threshold where lower values mean more deblocking (default: @code{39}).
15449 The horizontal and vertical deblocking filters share the difference and
15450 flatness values so you cannot set different horizontal and vertical
15454 @item h1/x1hdeblock
15455 Experimental horizontal deblocking filter
15457 @item v1/x1vdeblock
15458 Experimental vertical deblocking filter
15463 @item tn/tmpnoise[|threshold1[|threshold2[|threshold3]]], temporal noise reducer
15466 larger -> stronger filtering
15468 larger -> stronger filtering
15470 larger -> stronger filtering
15473 @item al/autolevels[:f/fullyrange], automatic brightness / contrast correction
15476 Stretch luminance to @code{0-255}.
15479 @item lb/linblenddeint
15480 Linear blend deinterlacing filter that deinterlaces the given block by
15481 filtering all lines with a @code{(1 2 1)} filter.
15483 @item li/linipoldeint
15484 Linear interpolating deinterlacing filter that deinterlaces the given block by
15485 linearly interpolating every second line.
15487 @item ci/cubicipoldeint
15488 Cubic interpolating deinterlacing filter deinterlaces the given block by
15489 cubically interpolating every second line.
15491 @item md/mediandeint
15492 Median deinterlacing filter that deinterlaces the given block by applying a
15493 median filter to every second line.
15495 @item fd/ffmpegdeint
15496 FFmpeg deinterlacing filter that deinterlaces the given block by filtering every
15497 second line with a @code{(-1 4 2 4 -1)} filter.
15500 Vertically applied FIR lowpass deinterlacing filter that deinterlaces the given
15501 block by filtering all lines with a @code{(-1 2 6 2 -1)} filter.
15503 @item fq/forceQuant[|quantizer]
15504 Overrides the quantizer table from the input with the constant quantizer you
15512 Default pp filter combination (@code{hb|a,vb|a,dr|a})
15515 Fast pp filter combination (@code{h1|a,v1|a,dr|a})
15518 High quality pp filter combination (@code{ha|a|128|7,va|a,dr|a})
15521 @subsection Examples
15525 Apply horizontal and vertical deblocking, deringing and automatic
15526 brightness/contrast:
15532 Apply default filters without brightness/contrast correction:
15538 Apply default filters and temporal denoiser:
15540 pp=default/tmpnoise|1|2|3
15544 Apply deblocking on luminance only, and switch vertical deblocking on or off
15545 automatically depending on available CPU time:
15552 Apply Postprocessing filter 7. It is variant of the @ref{spp} filter,
15553 similar to spp = 6 with 7 point DCT, where only the center sample is
15556 The filter accepts the following options:
15560 Force a constant quantization parameter. It accepts an integer in range
15561 0 to 63. If not set, the filter will use the QP from the video stream
15565 Set thresholding mode. Available modes are:
15569 Set hard thresholding.
15571 Set soft thresholding (better de-ringing effect, but likely blurrier).
15573 Set medium thresholding (good results, default).
15577 @section premultiply
15578 Apply alpha premultiply effect to input video stream using first plane
15579 of second stream as alpha.
15581 Both streams must have same dimensions and same pixel format.
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 Do not require 2nd input for processing, instead use alpha plane from input stream.
15595 Apply prewitt operator to input video stream.
15597 The filter accepts the following option:
15601 Set which planes will be processed, unprocessed planes will be copied.
15602 By default value 0xf, all planes will be processed.
15605 Set value which will be multiplied with filtered result.
15608 Set value which will be added to filtered result.
15611 @section pseudocolor
15613 Alter frame colors in video with pseudocolors.
15615 This filter accepts the following options:
15619 set pixel first component expression
15622 set pixel second component expression
15625 set pixel third component expression
15628 set pixel fourth component expression, corresponds to the alpha component
15631 set component to use as base for altering colors
15634 Each of them specifies the expression to use for computing the lookup table for
15635 the corresponding pixel component values.
15637 The expressions can contain the following constants and functions:
15642 The input width and height.
15645 The input value for the pixel component.
15647 @item ymin, umin, vmin, amin
15648 The minimum allowed component value.
15650 @item ymax, umax, vmax, amax
15651 The maximum allowed component value.
15654 All expressions default to "val".
15656 @subsection Examples
15660 Change too high luma values to gradient:
15662 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'"
15668 Obtain the average, maximum and minimum PSNR (Peak Signal to Noise
15669 Ratio) between two input videos.
15671 This filter takes in input two input videos, the first input is
15672 considered the "main" source and is passed unchanged to the
15673 output. The second input is used as a "reference" video for computing
15676 Both video inputs must have the same resolution and pixel format for
15677 this filter to work correctly. Also it assumes that both inputs
15678 have the same number of frames, which are compared one by one.
15680 The obtained average PSNR is printed through the logging system.
15682 The filter stores the accumulated MSE (mean squared error) of each
15683 frame, and at the end of the processing it is averaged across all frames
15684 equally, and the following formula is applied to obtain the PSNR:
15687 PSNR = 10*log10(MAX^2/MSE)
15690 Where MAX is the average of the maximum values of each component of the
15693 The description of the accepted parameters follows.
15696 @item stats_file, f
15697 If specified the filter will use the named file to save the PSNR of
15698 each individual frame. When filename equals "-" the data is sent to
15701 @item stats_version
15702 Specifies which version of the stats file format to use. Details of
15703 each format are written below.
15704 Default value is 1.
15706 @item stats_add_max
15707 Determines whether the max value is output to the stats log.
15708 Default value is 0.
15709 Requires stats_version >= 2. If this is set and stats_version < 2,
15710 the filter will return an error.
15713 This filter also supports the @ref{framesync} options.
15715 The file printed if @var{stats_file} is selected, contains a sequence of
15716 key/value pairs of the form @var{key}:@var{value} for each compared
15719 If a @var{stats_version} greater than 1 is specified, a header line precedes
15720 the list of per-frame-pair stats, with key value pairs following the frame
15721 format with the following parameters:
15724 @item psnr_log_version
15725 The version of the log file format. Will match @var{stats_version}.
15728 A comma separated list of the per-frame-pair parameters included in
15732 A description of each shown per-frame-pair parameter follows:
15736 sequential number of the input frame, starting from 1
15739 Mean Square Error pixel-by-pixel average difference of the compared
15740 frames, averaged over all the image components.
15742 @item mse_y, mse_u, mse_v, mse_r, mse_g, mse_b, mse_a
15743 Mean Square Error pixel-by-pixel average difference of the compared
15744 frames for the component specified by the suffix.
15746 @item psnr_y, psnr_u, psnr_v, psnr_r, psnr_g, psnr_b, psnr_a
15747 Peak Signal to Noise ratio of the compared frames for the component
15748 specified by the suffix.
15750 @item max_avg, max_y, max_u, max_v
15751 Maximum allowed value for each channel, and average over all
15755 @subsection Examples
15760 movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
15761 [main][ref] psnr="stats_file=stats.log" [out]
15764 On this example the input file being processed is compared with the
15765 reference file @file{ref_movie.mpg}. The PSNR of each individual frame
15766 is stored in @file{stats.log}.
15769 Another example with different containers:
15771 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 -
15778 Pulldown reversal (inverse telecine) filter, capable of handling mixed
15779 hard-telecine, 24000/1001 fps progressive, and 30000/1001 fps progressive
15782 The pullup filter is designed to take advantage of future context in making
15783 its decisions. This filter is stateless in the sense that it does not lock
15784 onto a pattern to follow, but it instead looks forward to the following
15785 fields in order to identify matches and rebuild progressive frames.
15787 To produce content with an even framerate, insert the fps filter after
15788 pullup, use @code{fps=24000/1001} if the input frame rate is 29.97fps,
15789 @code{fps=24} for 30fps and the (rare) telecined 25fps input.
15791 The filter accepts the following options:
15798 These options set the amount of "junk" to ignore at the left, right, top, and
15799 bottom of the image, respectively. Left and right are in units of 8 pixels,
15800 while top and bottom are in units of 2 lines.
15801 The default is 8 pixels on each side.
15804 Set the strict breaks. Setting this option to 1 will reduce the chances of
15805 filter generating an occasional mismatched frame, but it may also cause an
15806 excessive number of frames to be dropped during high motion sequences.
15807 Conversely, setting it to -1 will make filter match fields more easily.
15808 This may help processing of video where there is slight blurring between
15809 the fields, but may also cause there to be interlaced frames in the output.
15810 Default value is @code{0}.
15813 Set the metric plane to use. It accepts the following values:
15819 Use chroma blue plane.
15822 Use chroma red plane.
15825 This option may be set to use chroma plane instead of the default luma plane
15826 for doing filter's computations. This may improve accuracy on very clean
15827 source material, but more likely will decrease accuracy, especially if there
15828 is chroma noise (rainbow effect) or any grayscale video.
15829 The main purpose of setting @option{mp} to a chroma plane is to reduce CPU
15830 load and make pullup usable in realtime on slow machines.
15833 For best results (without duplicated frames in the output file) it is
15834 necessary to change the output frame rate. For example, to inverse
15835 telecine NTSC input:
15837 ffmpeg -i input -vf pullup -r 24000/1001 ...
15842 Change video quantization parameters (QP).
15844 The filter accepts the following option:
15848 Set expression for quantization parameter.
15851 The expression is evaluated through the eval API and can contain, among others,
15852 the following constants:
15856 1 if index is not 129, 0 otherwise.
15859 Sequential index starting from -129 to 128.
15862 @subsection Examples
15866 Some equation like:
15874 Flush video frames from internal cache of frames into a random order.
15875 No frame is discarded.
15876 Inspired by @ref{frei0r} nervous filter.
15880 Set size in number of frames of internal cache, in range from @code{2} to
15881 @code{512}. Default is @code{30}.
15884 Set seed for random number generator, must be an integer included between
15885 @code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to
15886 less than @code{0}, the filter will try to use a good random seed on a
15890 @section readeia608
15892 Read closed captioning (EIA-608) information from the top lines of a video frame.
15894 This filter adds frame metadata for @code{lavfi.readeia608.X.cc} and
15895 @code{lavfi.readeia608.X.line}, where @code{X} is the number of the identified line
15896 with EIA-608 data (starting from 0). A description of each metadata value follows:
15899 @item lavfi.readeia608.X.cc
15900 The two bytes stored as EIA-608 data (printed in hexadecimal).
15902 @item lavfi.readeia608.X.line
15903 The number of the line on which the EIA-608 data was identified and read.
15906 This filter accepts the following options:
15910 Set the line to start scanning for EIA-608 data. Default is @code{0}.
15913 Set the line to end scanning for EIA-608 data. Default is @code{29}.
15916 Set the ratio of width reserved for sync code detection.
15917 Default is @code{0.27}. Allowed range is @code{[0.1 - 0.7]}.
15920 Enable checking the parity bit. In the event of a parity error, the filter will output
15921 @code{0x00} for that character. Default is false.
15924 Lowpass lines prior to further processing. Default is enabled.
15927 @subsection Commands
15929 This filter supports the all above options as @ref{commands}.
15931 @subsection Examples
15935 Output a csv with presentation time and the first two lines of identified EIA-608 captioning data.
15937 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
15943 Read vertical interval timecode (VITC) information from the top lines of a
15946 The filter adds frame metadata key @code{lavfi.readvitc.tc_str} with the
15947 timecode value, if a valid timecode has been detected. Further metadata key
15948 @code{lavfi.readvitc.found} is set to 0/1 depending on whether
15949 timecode data has been found or not.
15951 This filter accepts the following options:
15955 Set the maximum number of lines to scan for VITC data. If the value is set to
15956 @code{-1} the full video frame is scanned. Default is @code{45}.
15959 Set the luma threshold for black. Accepts float numbers in the range [0.0,1.0],
15960 default value is @code{0.2}. The value must be equal or less than @code{thr_w}.
15963 Set the luma threshold for white. Accepts float numbers in the range [0.0,1.0],
15964 default value is @code{0.6}. The value must be equal or greater than @code{thr_b}.
15967 @subsection Examples
15971 Detect and draw VITC data onto the video frame; if no valid VITC is detected,
15972 draw @code{--:--:--:--} as a placeholder:
15974 ffmpeg -i input.avi -filter:v 'readvitc,drawtext=fontfile=FreeMono.ttf:text=%@{metadata\\:lavfi.readvitc.tc_str\\:--\\\\\\:--\\\\\\:--\\\\\\:--@}:x=(w-tw)/2:y=400-ascent'
15980 Remap pixels using 2nd: Xmap and 3rd: Ymap input video stream.
15982 Destination pixel at position (X, Y) will be picked from source (x, y) position
15983 where x = Xmap(X, Y) and y = Ymap(X, Y). If mapping values are out of range, zero
15984 value for pixel will be used for destination pixel.
15986 Xmap and Ymap input video streams must be of same dimensions. Output video stream
15987 will have Xmap/Ymap video stream dimensions.
15988 Xmap and Ymap input video streams are 16bit depth, single channel.
15992 Specify pixel format of output from this filter. Can be @code{color} or @code{gray}.
15993 Default is @code{color}.
15996 Specify the color of the unmapped pixels. For the syntax of this option,
15997 check the @ref{color syntax,,"Color" section in the ffmpeg-utils
15998 manual,ffmpeg-utils}. Default color is @code{black}.
16001 @section removegrain
16003 The removegrain filter is a spatial denoiser for progressive video.
16007 Set mode for the first plane.
16010 Set mode for the second plane.
16013 Set mode for the third plane.
16016 Set mode for the fourth plane.
16019 Range of mode is from 0 to 24. Description of each mode follows:
16023 Leave input plane unchanged. Default.
16026 Clips the pixel with the minimum and maximum of the 8 neighbour pixels.
16029 Clips the pixel with the second minimum and maximum of the 8 neighbour pixels.
16032 Clips the pixel with the third minimum and maximum of the 8 neighbour pixels.
16035 Clips the pixel with the fourth minimum and maximum of the 8 neighbour pixels.
16036 This is equivalent to a median filter.
16039 Line-sensitive clipping giving the minimal change.
16042 Line-sensitive clipping, intermediate.
16045 Line-sensitive clipping, intermediate.
16048 Line-sensitive clipping, intermediate.
16051 Line-sensitive clipping on a line where the neighbours pixels are the closest.
16054 Replaces the target pixel with the closest neighbour.
16057 [1 2 1] horizontal and vertical kernel blur.
16063 Bob mode, interpolates top field from the line where the neighbours
16064 pixels are the closest.
16067 Bob mode, interpolates bottom field from the line where the neighbours
16068 pixels are the closest.
16071 Bob mode, interpolates top field. Same as 13 but with a more complicated
16072 interpolation formula.
16075 Bob mode, interpolates bottom field. Same as 14 but with a more complicated
16076 interpolation formula.
16079 Clips the pixel with the minimum and maximum of respectively the maximum and
16080 minimum of each pair of opposite neighbour pixels.
16083 Line-sensitive clipping using opposite neighbours whose greatest distance from
16084 the current pixel is minimal.
16087 Replaces the pixel with the average of its 8 neighbours.
16090 Averages the 9 pixels ([1 1 1] horizontal and vertical blur).
16093 Clips pixels using the averages of opposite neighbour.
16096 Same as mode 21 but simpler and faster.
16099 Small edge and halo removal, but reputed useless.
16105 @section removelogo
16107 Suppress a TV station logo, using an image file to determine which
16108 pixels comprise the logo. It works by filling in the pixels that
16109 comprise the logo with neighboring pixels.
16111 The filter accepts the following options:
16115 Set the filter bitmap file, which can be any image format supported by
16116 libavformat. The width and height of the image file must match those of the
16117 video stream being processed.
16120 Pixels in the provided bitmap image with a value of zero are not
16121 considered part of the logo, non-zero pixels are considered part of
16122 the logo. If you use white (255) for the logo and black (0) for the
16123 rest, you will be safe. For making the filter bitmap, it is
16124 recommended to take a screen capture of a black frame with the logo
16125 visible, and then using a threshold filter followed by the erode
16126 filter once or twice.
16128 If needed, little splotches can be fixed manually. Remember that if
16129 logo pixels are not covered, the filter quality will be much
16130 reduced. Marking too many pixels as part of the logo does not hurt as
16131 much, but it will increase the amount of blurring needed to cover over
16132 the image and will destroy more information than necessary, and extra
16133 pixels will slow things down on a large logo.
16135 @section repeatfields
16137 This filter uses the repeat_field flag from the Video ES headers and hard repeats
16138 fields based on its value.
16142 Reverse a video clip.
16144 Warning: This filter requires memory to buffer the entire clip, so trimming
16147 @subsection Examples
16151 Take the first 5 seconds of a clip, and reverse it.
16158 Shift R/G/B/A pixels horizontally and/or vertically.
16160 The filter accepts the following options:
16163 Set amount to shift red horizontally.
16165 Set amount to shift red vertically.
16167 Set amount to shift green horizontally.
16169 Set amount to shift green vertically.
16171 Set amount to shift blue horizontally.
16173 Set amount to shift blue vertically.
16175 Set amount to shift alpha horizontally.
16177 Set amount to shift alpha vertically.
16179 Set edge mode, can be @var{smear}, default, or @var{warp}.
16182 @subsection Commands
16184 This filter supports the all above options as @ref{commands}.
16187 Apply roberts cross operator to input video stream.
16189 The filter accepts the following option:
16193 Set which planes will be processed, unprocessed planes will be copied.
16194 By default value 0xf, all planes will be processed.
16197 Set value which will be multiplied with filtered result.
16200 Set value which will be added to filtered result.
16205 Rotate video by an arbitrary angle expressed in radians.
16207 The filter accepts the following options:
16209 A description of the optional parameters follows.
16212 Set an expression for the angle by which to rotate the input video
16213 clockwise, expressed as a number of radians. A negative value will
16214 result in a counter-clockwise rotation. By default it is set to "0".
16216 This expression is evaluated for each frame.
16219 Set the output width expression, default value is "iw".
16220 This expression is evaluated just once during configuration.
16223 Set the output height expression, default value is "ih".
16224 This expression is evaluated just once during configuration.
16227 Enable bilinear interpolation if set to 1, a value of 0 disables
16228 it. Default value is 1.
16231 Set the color used to fill the output area not covered by the rotated
16232 image. For the general syntax of this option, check the
16233 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
16234 If the special value "none" is selected then no
16235 background is printed (useful for example if the background is never shown).
16237 Default value is "black".
16240 The expressions for the angle and the output size can contain the
16241 following constants and functions:
16245 sequential number of the input frame, starting from 0. It is always NAN
16246 before the first frame is filtered.
16249 time in seconds of the input frame, it is set to 0 when the filter is
16250 configured. It is always NAN before the first frame is filtered.
16254 horizontal and vertical chroma subsample values. For example for the
16255 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
16259 the input video width and height
16263 the output width and height, that is the size of the padded area as
16264 specified by the @var{width} and @var{height} expressions
16268 the minimal width/height required for completely containing the input
16269 video rotated by @var{a} radians.
16271 These are only available when computing the @option{out_w} and
16272 @option{out_h} expressions.
16275 @subsection Examples
16279 Rotate the input by PI/6 radians clockwise:
16285 Rotate the input by PI/6 radians counter-clockwise:
16291 Rotate the input by 45 degrees clockwise:
16297 Apply a constant rotation with period T, starting from an angle of PI/3:
16299 rotate=PI/3+2*PI*t/T
16303 Make the input video rotation oscillating with a period of T
16304 seconds and an amplitude of A radians:
16306 rotate=A*sin(2*PI/T*t)
16310 Rotate the video, output size is chosen so that the whole rotating
16311 input video is always completely contained in the output:
16313 rotate='2*PI*t:ow=hypot(iw,ih):oh=ow'
16317 Rotate the video, reduce the output size so that no background is ever
16320 rotate=2*PI*t:ow='min(iw,ih)/sqrt(2)':oh=ow:c=none
16324 @subsection Commands
16326 The filter supports the following commands:
16330 Set the angle expression.
16331 The command accepts the same syntax of the corresponding option.
16333 If the specified expression is not valid, it is kept at its current
16339 Apply Shape Adaptive Blur.
16341 The filter accepts the following options:
16344 @item luma_radius, lr
16345 Set luma blur filter strength, must be a value in range 0.1-4.0, default
16346 value is 1.0. A greater value will result in a more blurred image, and
16347 in slower processing.
16349 @item luma_pre_filter_radius, lpfr
16350 Set luma pre-filter radius, must be a value in the 0.1-2.0 range, default
16353 @item luma_strength, ls
16354 Set luma maximum difference between pixels to still be considered, must
16355 be a value in the 0.1-100.0 range, default value is 1.0.
16357 @item chroma_radius, cr
16358 Set chroma blur filter strength, must be a value in range -0.9-4.0. A
16359 greater value will result in a more blurred image, and in slower
16362 @item chroma_pre_filter_radius, cpfr
16363 Set chroma pre-filter radius, must be a value in the -0.9-2.0 range.
16365 @item chroma_strength, cs
16366 Set chroma maximum difference between pixels to still be considered,
16367 must be a value in the -0.9-100.0 range.
16370 Each chroma option value, if not explicitly specified, is set to the
16371 corresponding luma option value.
16376 Scale (resize) the input video, using the libswscale library.
16378 The scale filter forces the output display aspect ratio to be the same
16379 of the input, by changing the output sample aspect ratio.
16381 If the input image format is different from the format requested by
16382 the next filter, the scale filter will convert the input to the
16385 @subsection Options
16386 The filter accepts the following options, or any of the options
16387 supported by the libswscale scaler.
16389 See @ref{scaler_options,,the ffmpeg-scaler manual,ffmpeg-scaler} for
16390 the complete list of scaler options.
16395 Set the output video dimension expression. Default value is the input
16398 If the @var{width} or @var{w} value is 0, the input width is used for
16399 the output. If the @var{height} or @var{h} value is 0, the input height
16400 is used for the output.
16402 If one and only one of the values is -n with n >= 1, the scale filter
16403 will use a value that maintains the aspect ratio of the input image,
16404 calculated from the other specified dimension. After that it will,
16405 however, make sure that the calculated dimension is divisible by n and
16406 adjust the value if necessary.
16408 If both values are -n with n >= 1, the behavior will be identical to
16409 both values being set to 0 as previously detailed.
16411 See below for the list of accepted constants for use in the dimension
16415 Specify when to evaluate @var{width} and @var{height} expression. It accepts the following values:
16419 Only evaluate expressions once during the filter initialization or when a command is processed.
16422 Evaluate expressions for each incoming frame.
16426 Default value is @samp{init}.
16430 Set the interlacing mode. It accepts the following values:
16434 Force interlaced aware scaling.
16437 Do not apply interlaced scaling.
16440 Select interlaced aware scaling depending on whether the source frames
16441 are flagged as interlaced or not.
16444 Default value is @samp{0}.
16447 Set libswscale scaling flags. See
16448 @ref{sws_flags,,the ffmpeg-scaler manual,ffmpeg-scaler} for the
16449 complete list of values. If not explicitly specified the filter applies
16453 @item param0, param1
16454 Set libswscale input parameters for scaling algorithms that need them. See
16455 @ref{sws_params,,the ffmpeg-scaler manual,ffmpeg-scaler} for the
16456 complete documentation. If not explicitly specified the filter applies
16462 Set the video size. For the syntax of this option, check the
16463 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
16465 @item in_color_matrix
16466 @item out_color_matrix
16467 Set in/output YCbCr color space type.
16469 This allows the autodetected value to be overridden as well as allows forcing
16470 a specific value used for the output and encoder.
16472 If not specified, the color space type depends on the pixel format.
16478 Choose automatically.
16481 Format conforming to International Telecommunication Union (ITU)
16482 Recommendation BT.709.
16485 Set color space conforming to the United States Federal Communications
16486 Commission (FCC) Code of Federal Regulations (CFR) Title 47 (2003) 73.682 (a).
16491 Set color space conforming to:
16495 ITU Radiocommunication Sector (ITU-R) Recommendation BT.601
16498 ITU-R Rec. BT.470-6 (1998) Systems B, B1, and G
16501 Society of Motion Picture and Television Engineers (SMPTE) ST 170:2004
16506 Set color space conforming to SMPTE ST 240:1999.
16509 Set color space conforming to ITU-R BT.2020 non-constant luminance system.
16514 Set in/output YCbCr sample range.
16516 This allows the autodetected value to be overridden as well as allows forcing
16517 a specific value used for the output and encoder. If not specified, the
16518 range depends on the pixel format. Possible values:
16522 Choose automatically.
16525 Set full range (0-255 in case of 8-bit luma).
16527 @item mpeg/limited/tv
16528 Set "MPEG" range (16-235 in case of 8-bit luma).
16531 @item force_original_aspect_ratio
16532 Enable decreasing or increasing output video width or height if necessary to
16533 keep the original aspect ratio. Possible values:
16537 Scale the video as specified and disable this feature.
16540 The output video dimensions will automatically be decreased if needed.
16543 The output video dimensions will automatically be increased if needed.
16547 One useful instance of this option is that when you know a specific device's
16548 maximum allowed resolution, you can use this to limit the output video to
16549 that, while retaining the aspect ratio. For example, device A allows
16550 1280x720 playback, and your video is 1920x800. Using this option (set it to
16551 decrease) and specifying 1280x720 to the command line makes the output
16554 Please note that this is a different thing than specifying -1 for @option{w}
16555 or @option{h}, you still need to specify the output resolution for this option
16558 @item force_divisible_by
16559 Ensures that both the output dimensions, width and height, are divisible by the
16560 given integer when used together with @option{force_original_aspect_ratio}. This
16561 works similar to using @code{-n} in the @option{w} and @option{h} options.
16563 This option respects the value set for @option{force_original_aspect_ratio},
16564 increasing or decreasing the resolution accordingly. The video's aspect ratio
16565 may be slightly modified.
16567 This option can be handy if you need to have a video fit within or exceed
16568 a defined resolution using @option{force_original_aspect_ratio} but also have
16569 encoder restrictions on width or height divisibility.
16573 The values of the @option{w} and @option{h} options are expressions
16574 containing the following constants:
16579 The input width and height
16583 These are the same as @var{in_w} and @var{in_h}.
16587 The output (scaled) width and height
16591 These are the same as @var{out_w} and @var{out_h}
16594 The same as @var{iw} / @var{ih}
16597 input sample aspect ratio
16600 The input display aspect ratio. Calculated from @code{(iw / ih) * sar}.
16604 horizontal and vertical input chroma subsample values. For example for the
16605 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
16609 horizontal and vertical output chroma subsample values. For example for the
16610 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
16613 The (sequential) number of the input frame, starting from 0.
16614 Only available with @code{eval=frame}.
16617 The presentation timestamp of the input frame, expressed as a number of
16618 seconds. Only available with @code{eval=frame}.
16621 The position (byte offset) of the frame in the input stream, or NaN if
16622 this information is unavailable and/or meaningless (for example in case of synthetic video).
16623 Only available with @code{eval=frame}.
16626 @subsection Examples
16630 Scale the input video to a size of 200x100
16635 This is equivalent to:
16646 Specify a size abbreviation for the output size:
16651 which can also be written as:
16657 Scale the input to 2x:
16659 scale=w=2*iw:h=2*ih
16663 The above is the same as:
16665 scale=2*in_w:2*in_h
16669 Scale the input to 2x with forced interlaced scaling:
16671 scale=2*iw:2*ih:interl=1
16675 Scale the input to half size:
16677 scale=w=iw/2:h=ih/2
16681 Increase the width, and set the height to the same size:
16687 Seek Greek harmony:
16694 Increase the height, and set the width to 3/2 of the height:
16696 scale=w=3/2*oh:h=3/5*ih
16700 Increase the size, making the size a multiple of the chroma
16703 scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub"
16707 Increase the width to a maximum of 500 pixels,
16708 keeping the same aspect ratio as the input:
16710 scale=w='min(500\, iw*3/2):h=-1'
16714 Make pixels square by combining scale and setsar:
16716 scale='trunc(ih*dar):ih',setsar=1/1
16720 Make pixels square by combining scale and setsar,
16721 making sure the resulting resolution is even (required by some codecs):
16723 scale='trunc(ih*dar/2)*2:trunc(ih/2)*2',setsar=1/1
16727 @subsection Commands
16729 This filter supports the following commands:
16733 Set the output video dimension expression.
16734 The command accepts the same syntax of the corresponding option.
16736 If the specified expression is not valid, it is kept at its current
16742 Use the NVIDIA Performance Primitives (libnpp) to perform scaling and/or pixel
16743 format conversion on CUDA video frames. Setting the output width and height
16744 works in the same way as for the @var{scale} filter.
16746 The following additional options are accepted:
16749 The pixel format of the output CUDA frames. If set to the string "same" (the
16750 default), the input format will be kept. Note that automatic format negotiation
16751 and conversion is not yet supported for hardware frames
16754 The interpolation algorithm used for resizing. One of the following:
16761 @item cubic2p_bspline
16762 2-parameter cubic (B=1, C=0)
16764 @item cubic2p_catmullrom
16765 2-parameter cubic (B=0, C=1/2)
16767 @item cubic2p_b05c03
16768 2-parameter cubic (B=1/2, C=3/10)
16776 @item force_original_aspect_ratio
16777 Enable decreasing or increasing output video width or height if necessary to
16778 keep the original aspect ratio. Possible values:
16782 Scale the video as specified and disable this feature.
16785 The output video dimensions will automatically be decreased if needed.
16788 The output video dimensions will automatically be increased if needed.
16792 One useful instance of this option is that when you know a specific device's
16793 maximum allowed resolution, you can use this to limit the output video to
16794 that, while retaining the aspect ratio. For example, device A allows
16795 1280x720 playback, and your video is 1920x800. Using this option (set it to
16796 decrease) and specifying 1280x720 to the command line makes the output
16799 Please note that this is a different thing than specifying -1 for @option{w}
16800 or @option{h}, you still need to specify the output resolution for this option
16803 @item force_divisible_by
16804 Ensures that both the output dimensions, width and height, are divisible by the
16805 given integer when used together with @option{force_original_aspect_ratio}. This
16806 works similar to using @code{-n} in the @option{w} and @option{h} options.
16808 This option respects the value set for @option{force_original_aspect_ratio},
16809 increasing or decreasing the resolution accordingly. The video's aspect ratio
16810 may be slightly modified.
16812 This option can be handy if you need to have a video fit within or exceed
16813 a defined resolution using @option{force_original_aspect_ratio} but also have
16814 encoder restrictions on width or height divisibility.
16820 Scale (resize) the input video, based on a reference video.
16822 See the scale filter for available options, scale2ref supports the same but
16823 uses the reference video instead of the main input as basis. scale2ref also
16824 supports the following additional constants for the @option{w} and
16825 @option{h} options:
16830 The main input video's width and height
16833 The same as @var{main_w} / @var{main_h}
16836 The main input video's sample aspect ratio
16838 @item main_dar, mdar
16839 The main input video's display aspect ratio. Calculated from
16840 @code{(main_w / main_h) * main_sar}.
16844 The main input video's horizontal and vertical chroma subsample values.
16845 For example for the pixel format "yuv422p" @var{hsub} is 2 and @var{vsub}
16849 The (sequential) number of the main input frame, starting from 0.
16850 Only available with @code{eval=frame}.
16853 The presentation timestamp of the main input frame, expressed as a number of
16854 seconds. Only available with @code{eval=frame}.
16857 The position (byte offset) of the frame in the main input stream, or NaN if
16858 this information is unavailable and/or meaningless (for example in case of synthetic video).
16859 Only available with @code{eval=frame}.
16862 @subsection Examples
16866 Scale a subtitle stream (b) to match the main video (a) in size before overlaying
16868 'scale2ref[b][a];[a][b]overlay'
16872 Scale a logo to 1/10th the height of a video, while preserving its display aspect ratio.
16874 [logo-in][video-in]scale2ref=w=oh*mdar:h=ih/10[logo-out][video-out]
16878 @subsection Commands
16880 This filter supports the following commands:
16884 Set the output video dimension expression.
16885 The command accepts the same syntax of the corresponding option.
16887 If the specified expression is not valid, it is kept at its current
16892 Scroll input video horizontally and/or vertically by constant speed.
16894 The filter accepts the following options:
16896 @item horizontal, h
16897 Set the horizontal scrolling speed. Default is 0. Allowed range is from -1 to 1.
16898 Negative values changes scrolling direction.
16901 Set the vertical scrolling speed. Default is 0. Allowed range is from -1 to 1.
16902 Negative values changes scrolling direction.
16905 Set the initial horizontal scrolling position. Default is 0. Allowed range is from 0 to 1.
16908 Set the initial vertical scrolling position. Default is 0. Allowed range is from 0 to 1.
16911 @subsection Commands
16913 This filter supports the following @ref{commands}:
16915 @item horizontal, h
16916 Set the horizontal scrolling speed.
16918 Set the vertical scrolling speed.
16924 Detect video scene change.
16926 This filter sets frame metadata with mafd between frame, the scene score, and
16927 forward the frame to the next filter, so they can use these metadata to detect
16928 scene change or others.
16930 In addition, this filter logs a message and sets frame metadata when it detects
16931 a scene change by @option{threshold}.
16933 @code{lavfi.scd.mafd} metadata keys are set with mafd for every frame.
16935 @code{lavfi.scd.score} metadata keys are set with scene change score for every frame
16936 to detect scene change.
16938 @code{lavfi.scd.time} metadata keys are set with current filtered frame time which
16939 detect scene change with @option{threshold}.
16941 The filter accepts the following options:
16945 Set the scene change detection threshold as a percentage of maximum change. Good
16946 values are in the @code{[8.0, 14.0]} range. The range for @option{threshold} is
16949 Default value is @code{10.}.
16952 Set the flag to pass scene change frames to the next filter. Default value is @code{0}
16953 You can enable it if you want to get snapshot of scene change frames only.
16956 @anchor{selectivecolor}
16957 @section selectivecolor
16959 Adjust cyan, magenta, yellow and black (CMYK) to certain ranges of colors (such
16960 as "reds", "yellows", "greens", "cyans", ...). The adjustment range is defined
16961 by the "purity" of the color (that is, how saturated it already is).
16963 This filter is similar to the Adobe Photoshop Selective Color tool.
16965 The filter accepts the following options:
16968 @item correction_method
16969 Select color correction method.
16971 Available values are:
16974 Specified adjustments are applied "as-is" (added/subtracted to original pixel
16977 Specified adjustments are relative to the original component value.
16979 Default is @code{absolute}.
16981 Adjustments for red pixels (pixels where the red component is the maximum)
16983 Adjustments for yellow pixels (pixels where the blue component is the minimum)
16985 Adjustments for green pixels (pixels where the green component is the maximum)
16987 Adjustments for cyan pixels (pixels where the red component is the minimum)
16989 Adjustments for blue pixels (pixels where the blue component is the maximum)
16991 Adjustments for magenta pixels (pixels where the green component is the minimum)
16993 Adjustments for white pixels (pixels where all components are greater than 128)
16995 Adjustments for all pixels except pure black and pure white
16997 Adjustments for black pixels (pixels where all components are lesser than 128)
16999 Specify a Photoshop selective color file (@code{.asv}) to import the settings from.
17002 All the adjustment settings (@option{reds}, @option{yellows}, ...) accept up to
17003 4 space separated floating point adjustment values in the [-1,1] range,
17004 respectively to adjust the amount of cyan, magenta, yellow and black for the
17005 pixels of its range.
17007 @subsection Examples
17011 Increase cyan by 50% and reduce yellow by 33% in every green areas, and
17012 increase magenta by 27% in blue areas:
17014 selectivecolor=greens=.5 0 -.33 0:blues=0 .27
17018 Use a Photoshop selective color preset:
17020 selectivecolor=psfile=MySelectiveColorPresets/Misty.asv
17024 @anchor{separatefields}
17025 @section separatefields
17027 The @code{separatefields} takes a frame-based video input and splits
17028 each frame into its components fields, producing a new half height clip
17029 with twice the frame rate and twice the frame count.
17031 This filter use field-dominance information in frame to decide which
17032 of each pair of fields to place first in the output.
17033 If it gets it wrong use @ref{setfield} filter before @code{separatefields} filter.
17035 @section setdar, setsar
17037 The @code{setdar} filter sets the Display Aspect Ratio for the filter
17040 This is done by changing the specified Sample (aka Pixel) Aspect
17041 Ratio, according to the following equation:
17043 @var{DAR} = @var{HORIZONTAL_RESOLUTION} / @var{VERTICAL_RESOLUTION} * @var{SAR}
17046 Keep in mind that the @code{setdar} filter does not modify the pixel
17047 dimensions of the video frame. Also, the display aspect ratio set by
17048 this filter may be changed by later filters in the filterchain,
17049 e.g. in case of scaling or if another "setdar" or a "setsar" filter is
17052 The @code{setsar} filter sets the Sample (aka Pixel) Aspect Ratio for
17053 the filter output video.
17055 Note that as a consequence of the application of this filter, the
17056 output display aspect ratio will change according to the equation
17059 Keep in mind that the sample aspect ratio set by the @code{setsar}
17060 filter may be changed by later filters in the filterchain, e.g. if
17061 another "setsar" or a "setdar" filter is applied.
17063 It accepts the following parameters:
17066 @item r, ratio, dar (@code{setdar} only), sar (@code{setsar} only)
17067 Set the aspect ratio used by the filter.
17069 The parameter can be a floating point number string, an expression, or
17070 a string of the form @var{num}:@var{den}, where @var{num} and
17071 @var{den} are the numerator and denominator of the aspect ratio. If
17072 the parameter is not specified, it is assumed the value "0".
17073 In case the form "@var{num}:@var{den}" is used, the @code{:} character
17077 Set the maximum integer value to use for expressing numerator and
17078 denominator when reducing the expressed aspect ratio to a rational.
17079 Default value is @code{100}.
17083 The parameter @var{sar} is an expression containing
17084 the following constants:
17088 These are approximated values for the mathematical constants e
17089 (Euler's number), pi (Greek pi), and phi (the golden ratio).
17092 The input width and height.
17095 These are the same as @var{w} / @var{h}.
17098 The input sample aspect ratio.
17101 The input display aspect ratio. It is the same as
17102 (@var{w} / @var{h}) * @var{sar}.
17105 Horizontal and vertical chroma subsample values. For example, for the
17106 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
17109 @subsection Examples
17114 To change the display aspect ratio to 16:9, specify one of the following:
17121 To change the sample aspect ratio to 10:11, specify:
17127 To set a display aspect ratio of 16:9, and specify a maximum integer value of
17128 1000 in the aspect ratio reduction, use the command:
17130 setdar=ratio=16/9:max=1000
17138 Force field for the output video frame.
17140 The @code{setfield} filter marks the interlace type field for the
17141 output frames. It does not change the input frame, but only sets the
17142 corresponding property, which affects how the frame is treated by
17143 following filters (e.g. @code{fieldorder} or @code{yadif}).
17145 The filter accepts the following options:
17150 Available values are:
17154 Keep the same field property.
17157 Mark the frame as bottom-field-first.
17160 Mark the frame as top-field-first.
17163 Mark the frame as progressive.
17170 Force frame parameter for the output video frame.
17172 The @code{setparams} filter marks interlace and color range for the
17173 output frames. It does not change the input frame, but only sets the
17174 corresponding property, which affects how the frame is treated by
17179 Available values are:
17183 Keep the same field property (default).
17186 Mark the frame as bottom-field-first.
17189 Mark the frame as top-field-first.
17192 Mark the frame as progressive.
17196 Available values are:
17200 Keep the same color range property (default).
17202 @item unspecified, unknown
17203 Mark the frame as unspecified color range.
17205 @item limited, tv, mpeg
17206 Mark the frame as limited range.
17208 @item full, pc, jpeg
17209 Mark the frame as full range.
17212 @item color_primaries
17213 Set the color primaries.
17214 Available values are:
17218 Keep the same color primaries property (default).
17235 Set the color transfer.
17236 Available values are:
17240 Keep the same color trc property (default).
17262 Set the colorspace.
17263 Available values are:
17267 Keep the same colorspace property (default).
17280 @item chroma-derived-nc
17281 @item chroma-derived-c
17288 Show a line containing various information for each input video frame.
17289 The input video is not modified.
17291 This filter supports the following options:
17295 Calculate checksums of each plane. By default enabled.
17298 The shown line contains a sequence of key/value pairs of the form
17299 @var{key}:@var{value}.
17301 The following values are shown in the output:
17305 The (sequential) number of the input frame, starting from 0.
17308 The Presentation TimeStamp of the input frame, expressed as a number of
17309 time base units. The time base unit depends on the filter input pad.
17312 The Presentation TimeStamp of the input frame, expressed as a number of
17316 The position of the frame in the input stream, or -1 if this information is
17317 unavailable and/or meaningless (for example in case of synthetic video).
17320 The pixel format name.
17323 The sample aspect ratio of the input frame, expressed in the form
17324 @var{num}/@var{den}.
17327 The size of the input frame. For the syntax of this option, check the
17328 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
17331 The type of interlaced mode ("P" for "progressive", "T" for top field first, "B"
17332 for bottom field first).
17335 This is 1 if the frame is a key frame, 0 otherwise.
17338 The picture type of the input frame ("I" for an I-frame, "P" for a
17339 P-frame, "B" for a B-frame, or "?" for an unknown type).
17340 Also refer to the documentation of the @code{AVPictureType} enum and of
17341 the @code{av_get_picture_type_char} function defined in
17342 @file{libavutil/avutil.h}.
17345 The Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame.
17347 @item plane_checksum
17348 The Adler-32 checksum (printed in hexadecimal) of each plane of the input frame,
17349 expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3}]".
17352 The mean value of pixels in each plane of the input frame, expressed in the form
17353 "[@var{mean0} @var{mean1} @var{mean2} @var{mean3}]".
17356 The standard deviation of pixel values in each plane of the input frame, expressed
17357 in the form "[@var{stdev0} @var{stdev1} @var{stdev2} @var{stdev3}]".
17361 @section showpalette
17363 Displays the 256 colors palette of each frame. This filter is only relevant for
17364 @var{pal8} pixel format frames.
17366 It accepts the following option:
17370 Set the size of the box used to represent one palette color entry. Default is
17371 @code{30} (for a @code{30x30} pixel box).
17374 @section shuffleframes
17376 Reorder and/or duplicate and/or drop video frames.
17378 It accepts the following parameters:
17382 Set the destination indexes of input frames.
17383 This is space or '|' separated list of indexes that maps input frames to output
17384 frames. Number of indexes also sets maximal value that each index may have.
17385 '-1' index have special meaning and that is to drop frame.
17388 The first frame has the index 0. The default is to keep the input unchanged.
17390 @subsection Examples
17394 Swap second and third frame of every three frames of the input:
17396 ffmpeg -i INPUT -vf "shuffleframes=0 2 1" OUTPUT
17400 Swap 10th and 1st frame of every ten frames of the input:
17402 ffmpeg -i INPUT -vf "shuffleframes=9 1 2 3 4 5 6 7 8 0" OUTPUT
17406 @section shuffleplanes
17408 Reorder and/or duplicate video planes.
17410 It accepts the following parameters:
17415 The index of the input plane to be used as the first output plane.
17418 The index of the input plane to be used as the second output plane.
17421 The index of the input plane to be used as the third output plane.
17424 The index of the input plane to be used as the fourth output plane.
17428 The first plane has the index 0. The default is to keep the input unchanged.
17430 @subsection Examples
17434 Swap the second and third planes of the input:
17436 ffmpeg -i INPUT -vf shuffleplanes=0:2:1:3 OUTPUT
17440 @anchor{signalstats}
17441 @section signalstats
17442 Evaluate various visual metrics that assist in determining issues associated
17443 with the digitization of analog video media.
17445 By default the filter will log these metadata values:
17449 Display the minimal Y value contained within the input frame. Expressed in
17453 Display the Y value at the 10% percentile within the input frame. Expressed in
17457 Display the average Y value within the input frame. Expressed in range of
17461 Display the Y value at the 90% percentile within the input frame. Expressed in
17465 Display the maximum Y value contained within the input frame. Expressed in
17469 Display the minimal U value contained within the input frame. Expressed in
17473 Display the U value at the 10% percentile within the input frame. Expressed in
17477 Display the average U value within the input frame. Expressed in range of
17481 Display the U value at the 90% percentile within the input frame. Expressed in
17485 Display the maximum U value contained within the input frame. Expressed in
17489 Display the minimal V value contained within the input frame. Expressed in
17493 Display the V value at the 10% percentile within the input frame. Expressed in
17497 Display the average V value within the input frame. Expressed in range of
17501 Display the V value at the 90% percentile within the input frame. Expressed in
17505 Display the maximum V value contained within the input frame. Expressed in
17509 Display the minimal saturation value contained within the input frame.
17510 Expressed in range of [0-~181.02].
17513 Display the saturation value at the 10% percentile within the input frame.
17514 Expressed in range of [0-~181.02].
17517 Display the average saturation value within the input frame. Expressed in range
17521 Display the saturation value at the 90% percentile within the input frame.
17522 Expressed in range of [0-~181.02].
17525 Display the maximum saturation value contained within the input frame.
17526 Expressed in range of [0-~181.02].
17529 Display the median value for hue within the input frame. Expressed in range of
17533 Display the average value for hue within the input frame. Expressed in range of
17537 Display the average of sample value difference between all values of the Y
17538 plane in the current frame and corresponding values of the previous input frame.
17539 Expressed in range of [0-255].
17542 Display the average of sample value difference between all values of the U
17543 plane in the current frame and corresponding values of the previous input frame.
17544 Expressed in range of [0-255].
17547 Display the average of sample value difference between all values of the V
17548 plane in the current frame and corresponding values of the previous input frame.
17549 Expressed in range of [0-255].
17552 Display bit depth of Y plane in current frame.
17553 Expressed in range of [0-16].
17556 Display bit depth of U plane in current frame.
17557 Expressed in range of [0-16].
17560 Display bit depth of V plane in current frame.
17561 Expressed in range of [0-16].
17564 The filter accepts the following options:
17570 @option{stat} specify an additional form of image analysis.
17571 @option{out} output video with the specified type of pixel highlighted.
17573 Both options accept the following values:
17577 Identify @var{temporal outliers} pixels. A @var{temporal outlier} is a pixel
17578 unlike the neighboring pixels of the same field. Examples of temporal outliers
17579 include the results of video dropouts, head clogs, or tape tracking issues.
17582 Identify @var{vertical line repetition}. Vertical line repetition includes
17583 similar rows of pixels within a frame. In born-digital video vertical line
17584 repetition is common, but this pattern is uncommon in video digitized from an
17585 analog source. When it occurs in video that results from the digitization of an
17586 analog source it can indicate concealment from a dropout compensator.
17589 Identify pixels that fall outside of legal broadcast range.
17593 Set the highlight color for the @option{out} option. The default color is
17597 @subsection Examples
17601 Output data of various video metrics:
17603 ffprobe -f lavfi movie=example.mov,signalstats="stat=tout+vrep+brng" -show_frames
17607 Output specific data about the minimum and maximum values of the Y plane per frame:
17609 ffprobe -f lavfi movie=example.mov,signalstats -show_entries frame_tags=lavfi.signalstats.YMAX,lavfi.signalstats.YMIN
17613 Playback video while highlighting pixels that are outside of broadcast range in red.
17615 ffplay example.mov -vf signalstats="out=brng:color=red"
17619 Playback video with signalstats metadata drawn over the frame.
17621 ffplay example.mov -vf signalstats=stat=brng+vrep+tout,drawtext=fontfile=FreeSerif.ttf:textfile=signalstat_drawtext.txt
17624 The contents of signalstat_drawtext.txt used in the command are:
17627 Y (%@{metadata:lavfi.signalstats.YMIN@}-%@{metadata:lavfi.signalstats.YMAX@})
17628 U (%@{metadata:lavfi.signalstats.UMIN@}-%@{metadata:lavfi.signalstats.UMAX@})
17629 V (%@{metadata:lavfi.signalstats.VMIN@}-%@{metadata:lavfi.signalstats.VMAX@})
17630 saturation maximum: %@{metadata:lavfi.signalstats.SATMAX@}
17638 Calculates the MPEG-7 Video Signature. The filter can handle more than one
17639 input. In this case the matching between the inputs can be calculated additionally.
17640 The filter always passes through the first input. The signature of each stream can
17641 be written into a file.
17643 It accepts the following options:
17647 Enable or disable the matching process.
17649 Available values are:
17653 Disable the calculation of a matching (default).
17655 Calculate the matching for the whole video and output whether the whole video
17656 matches or only parts.
17658 Calculate only until a matching is found or the video ends. Should be faster in
17663 Set the number of inputs. The option value must be a non negative integer.
17664 Default value is 1.
17667 Set the path to which the output is written. If there is more than one input,
17668 the path must be a prototype, i.e. must contain %d or %0nd (where n is a positive
17669 integer), that will be replaced with the input number. If no filename is
17670 specified, no output will be written. This is the default.
17673 Choose the output format.
17675 Available values are:
17679 Use the specified binary representation (default).
17681 Use the specified xml representation.
17685 Set threshold to detect one word as similar. The option value must be an integer
17686 greater than zero. The default value is 9000.
17689 Set threshold to detect all words as similar. The option value must be an integer
17690 greater than zero. The default value is 60000.
17693 Set threshold to detect frames as similar. The option value must be an integer
17694 greater than zero. The default value is 116.
17697 Set the minimum length of a sequence in frames to recognize it as matching
17698 sequence. The option value must be a non negative integer value.
17699 The default value is 0.
17702 Set the minimum relation, that matching frames to all frames must have.
17703 The option value must be a double value between 0 and 1. The default value is 0.5.
17706 @subsection Examples
17710 To calculate the signature of an input video and store it in signature.bin:
17712 ffmpeg -i input.mkv -vf signature=filename=signature.bin -map 0:v -f null -
17716 To detect whether two videos match and store the signatures in XML format in
17717 signature0.xml and signature1.xml:
17719 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 -
17727 Blur the input video without impacting the outlines.
17729 It accepts the following options:
17732 @item luma_radius, lr
17733 Set the luma radius. The option value must be a float number in
17734 the range [0.1,5.0] that specifies the variance of the gaussian filter
17735 used to blur the image (slower if larger). Default value is 1.0.
17737 @item luma_strength, ls
17738 Set the luma strength. The option value must be a float number
17739 in the range [-1.0,1.0] that configures the blurring. A value included
17740 in [0.0,1.0] will blur the image whereas a value included in
17741 [-1.0,0.0] will sharpen the image. Default value is 1.0.
17743 @item luma_threshold, lt
17744 Set the luma threshold used as a coefficient to determine
17745 whether a pixel should be blurred or not. The option value must be an
17746 integer in the range [-30,30]. A value of 0 will filter all the image,
17747 a value included in [0,30] will filter flat areas and a value included
17748 in [-30,0] will filter edges. Default value is 0.
17750 @item chroma_radius, cr
17751 Set the chroma radius. The option value must be a float number in
17752 the range [0.1,5.0] that specifies the variance of the gaussian filter
17753 used to blur the image (slower if larger). Default value is @option{luma_radius}.
17755 @item chroma_strength, cs
17756 Set the chroma strength. The option value must be a float number
17757 in the range [-1.0,1.0] that configures the blurring. A value included
17758 in [0.0,1.0] will blur the image whereas a value included in
17759 [-1.0,0.0] will sharpen the image. Default value is @option{luma_strength}.
17761 @item chroma_threshold, ct
17762 Set the chroma threshold used as a coefficient to determine
17763 whether a pixel should be blurred or not. The option value must be an
17764 integer in the range [-30,30]. A value of 0 will filter all the image,
17765 a value included in [0,30] will filter flat areas and a value included
17766 in [-30,0] will filter edges. Default value is @option{luma_threshold}.
17769 If a chroma option is not explicitly set, the corresponding luma value
17773 Apply sobel operator to input video stream.
17775 The filter accepts the following option:
17779 Set which planes will be processed, unprocessed planes will be copied.
17780 By default value 0xf, all planes will be processed.
17783 Set value which will be multiplied with filtered result.
17786 Set value which will be added to filtered result.
17792 Apply a simple postprocessing filter that compresses and decompresses the image
17793 at several (or - in the case of @option{quality} level @code{6} - all) shifts
17794 and average the results.
17796 The filter accepts the following options:
17800 Set quality. This option defines the number of levels for averaging. It accepts
17801 an integer in the range 0-6. If set to @code{0}, the filter will have no
17802 effect. A value of @code{6} means the higher quality. For each increment of
17803 that value the speed drops by a factor of approximately 2. Default value is
17807 Force a constant quantization parameter. If not set, the filter will use the QP
17808 from the video stream (if available).
17811 Set thresholding mode. Available modes are:
17815 Set hard thresholding (default).
17817 Set soft thresholding (better de-ringing effect, but likely blurrier).
17820 @item use_bframe_qp
17821 Enable the use of the QP from the B-Frames if set to @code{1}. Using this
17822 option may cause flicker since the B-Frames have often larger QP. Default is
17823 @code{0} (not enabled).
17826 @subsection Commands
17828 This filter supports the following commands:
17830 @item quality, level
17831 Set quality level. The value @code{max} can be used to set the maximum level,
17832 currently @code{6}.
17838 Scale the input by applying one of the super-resolution methods based on
17839 convolutional neural networks. Supported models:
17843 Super-Resolution Convolutional Neural Network model (SRCNN).
17844 See @url{https://arxiv.org/abs/1501.00092}.
17847 Efficient Sub-Pixel Convolutional Neural Network model (ESPCN).
17848 See @url{https://arxiv.org/abs/1609.05158}.
17851 Training scripts as well as scripts for model file (.pb) saving can be found at
17852 @url{https://github.com/XueweiMeng/sr/tree/sr_dnn_native}. Original repository
17853 is at @url{https://github.com/HighVoltageRocknRoll/sr.git}.
17855 Native model files (.model) can be generated from TensorFlow model
17856 files (.pb) by using tools/python/convert.py
17858 The filter accepts the following options:
17862 Specify which DNN backend to use for model loading and execution. This option accepts
17863 the following values:
17867 Native implementation of DNN loading and execution.
17870 TensorFlow backend. To enable this backend you
17871 need to install the TensorFlow for C library (see
17872 @url{https://www.tensorflow.org/install/install_c}) and configure FFmpeg with
17873 @code{--enable-libtensorflow}
17876 Default value is @samp{native}.
17879 Set path to model file specifying network architecture and its parameters.
17880 Note that different backends use different file formats. TensorFlow backend
17881 can load files for both formats, while native backend can load files for only
17885 Set scale factor for SRCNN model. Allowed values are @code{2}, @code{3} and @code{4}.
17886 Default value is @code{2}. Scale factor is necessary for SRCNN model, because it accepts
17887 input upscaled using bicubic upscaling with proper scale factor.
17890 This feature can also be finished with @ref{dnn_processing} filter.
17894 Obtain the SSIM (Structural SImilarity Metric) between two input videos.
17896 This filter takes in input two input videos, the first input is
17897 considered the "main" source and is passed unchanged to the
17898 output. The second input is used as a "reference" video for computing
17901 Both video inputs must have the same resolution and pixel format for
17902 this filter to work correctly. Also it assumes that both inputs
17903 have the same number of frames, which are compared one by one.
17905 The filter stores the calculated SSIM of each frame.
17907 The description of the accepted parameters follows.
17910 @item stats_file, f
17911 If specified the filter will use the named file to save the SSIM of
17912 each individual frame. When filename equals "-" the data is sent to
17916 The file printed if @var{stats_file} is selected, contains a sequence of
17917 key/value pairs of the form @var{key}:@var{value} for each compared
17920 A description of each shown parameter follows:
17924 sequential number of the input frame, starting from 1
17926 @item Y, U, V, R, G, B
17927 SSIM of the compared frames for the component specified by the suffix.
17930 SSIM of the compared frames for the whole frame.
17933 Same as above but in dB representation.
17936 This filter also supports the @ref{framesync} options.
17938 @subsection Examples
17943 movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
17944 [main][ref] ssim="stats_file=stats.log" [out]
17947 On this example the input file being processed is compared with the
17948 reference file @file{ref_movie.mpg}. The SSIM of each individual frame
17949 is stored in @file{stats.log}.
17952 Another example with both psnr and ssim at same time:
17954 ffmpeg -i main.mpg -i ref.mpg -lavfi "ssim;[0:v][1:v]psnr" -f null -
17958 Another example with different containers:
17960 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 -
17966 Convert between different stereoscopic image formats.
17968 The filters accept the following options:
17972 Set stereoscopic image format of input.
17974 Available values for input image formats are:
17977 side by side parallel (left eye left, right eye right)
17980 side by side crosseye (right eye left, left eye right)
17983 side by side parallel with half width resolution
17984 (left eye left, right eye right)
17987 side by side crosseye with half width resolution
17988 (right eye left, left eye right)
17992 above-below (left eye above, right eye below)
17996 above-below (right eye above, left eye below)
18000 above-below with half height resolution
18001 (left eye above, right eye below)
18005 above-below with half height resolution
18006 (right eye above, left eye below)
18009 alternating frames (left eye first, right eye second)
18012 alternating frames (right eye first, left eye second)
18015 interleaved rows (left eye has top row, right eye starts on next row)
18018 interleaved rows (right eye has top row, left eye starts on next row)
18021 interleaved columns, left eye first
18024 interleaved columns, right eye first
18026 Default value is @samp{sbsl}.
18030 Set stereoscopic image format of output.
18034 side by side parallel (left eye left, right eye right)
18037 side by side crosseye (right eye left, left eye right)
18040 side by side parallel with half width resolution
18041 (left eye left, right eye right)
18044 side by side crosseye with half width resolution
18045 (right eye left, left eye right)
18049 above-below (left eye above, right eye below)
18053 above-below (right eye above, left eye below)
18057 above-below with half height resolution
18058 (left eye above, right eye below)
18062 above-below with half height resolution
18063 (right eye above, left eye below)
18066 alternating frames (left eye first, right eye second)
18069 alternating frames (right eye first, left eye second)
18072 interleaved rows (left eye has top row, right eye starts on next row)
18075 interleaved rows (right eye has top row, left eye starts on next row)
18078 anaglyph red/blue gray
18079 (red filter on left eye, blue filter on right eye)
18082 anaglyph red/green gray
18083 (red filter on left eye, green filter on right eye)
18086 anaglyph red/cyan gray
18087 (red filter on left eye, cyan filter on right eye)
18090 anaglyph red/cyan half colored
18091 (red filter on left eye, cyan filter on right eye)
18094 anaglyph red/cyan color
18095 (red filter on left eye, cyan filter on right eye)
18098 anaglyph red/cyan color optimized with the least squares projection of dubois
18099 (red filter on left eye, cyan filter on right eye)
18102 anaglyph green/magenta gray
18103 (green filter on left eye, magenta filter on right eye)
18106 anaglyph green/magenta half colored
18107 (green filter on left eye, magenta filter on right eye)
18110 anaglyph green/magenta colored
18111 (green filter on left eye, magenta filter on right eye)
18114 anaglyph green/magenta color optimized with the least squares projection of dubois
18115 (green filter on left eye, magenta filter on right eye)
18118 anaglyph yellow/blue gray
18119 (yellow filter on left eye, blue filter on right eye)
18122 anaglyph yellow/blue half colored
18123 (yellow filter on left eye, blue filter on right eye)
18126 anaglyph yellow/blue colored
18127 (yellow filter on left eye, blue filter on right eye)
18130 anaglyph yellow/blue color optimized with the least squares projection of dubois
18131 (yellow filter on left eye, blue filter on right eye)
18134 mono output (left eye only)
18137 mono output (right eye only)
18140 checkerboard, left eye first
18143 checkerboard, right eye first
18146 interleaved columns, left eye first
18149 interleaved columns, right eye first
18155 Default value is @samp{arcd}.
18158 @subsection Examples
18162 Convert input video from side by side parallel to anaglyph yellow/blue dubois:
18168 Convert input video from above below (left eye above, right eye below) to side by side crosseye.
18174 @section streamselect, astreamselect
18175 Select video or audio streams.
18177 The filter accepts the following options:
18181 Set number of inputs. Default is 2.
18184 Set input indexes to remap to outputs.
18187 @subsection Commands
18189 The @code{streamselect} and @code{astreamselect} filter supports the following
18194 Set input indexes to remap to outputs.
18197 @subsection Examples
18201 Select first 5 seconds 1st stream and rest of time 2nd stream:
18203 sendcmd='5.0 streamselect map 1',streamselect=inputs=2:map=0
18207 Same as above, but for audio:
18209 asendcmd='5.0 astreamselect map 1',astreamselect=inputs=2:map=0
18216 Draw subtitles on top of input video using the libass library.
18218 To enable compilation of this filter you need to configure FFmpeg with
18219 @code{--enable-libass}. This filter also requires a build with libavcodec and
18220 libavformat to convert the passed subtitles file to ASS (Advanced Substation
18221 Alpha) subtitles format.
18223 The filter accepts the following options:
18227 Set the filename of the subtitle file to read. It must be specified.
18229 @item original_size
18230 Specify the size of the original video, the video for which the ASS file
18231 was composed. For the syntax of this option, check the
18232 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
18233 Due to a misdesign in ASS aspect ratio arithmetic, this is necessary to
18234 correctly scale the fonts if the aspect ratio has been changed.
18237 Set a directory path containing fonts that can be used by the filter.
18238 These fonts will be used in addition to whatever the font provider uses.
18241 Process alpha channel, by default alpha channel is untouched.
18244 Set subtitles input character encoding. @code{subtitles} filter only. Only
18245 useful if not UTF-8.
18247 @item stream_index, si
18248 Set subtitles stream index. @code{subtitles} filter only.
18251 Override default style or script info parameters of the subtitles. It accepts a
18252 string containing ASS style format @code{KEY=VALUE} couples separated by ",".
18255 If the first key is not specified, it is assumed that the first value
18256 specifies the @option{filename}.
18258 For example, to render the file @file{sub.srt} on top of the input
18259 video, use the command:
18264 which is equivalent to:
18266 subtitles=filename=sub.srt
18269 To render the default subtitles stream from file @file{video.mkv}, use:
18271 subtitles=video.mkv
18274 To render the second subtitles stream from that file, use:
18276 subtitles=video.mkv:si=1
18279 To make the subtitles stream from @file{sub.srt} appear in 80% transparent blue
18280 @code{DejaVu Serif}, use:
18282 subtitles=sub.srt:force_style='Fontname=DejaVu Serif,PrimaryColour=&HCCFF0000'
18285 @section super2xsai
18287 Scale the input by 2x and smooth using the Super2xSaI (Scale and
18288 Interpolate) pixel art scaling algorithm.
18290 Useful for enlarging pixel art images without reducing sharpness.
18294 Swap two rectangular objects in video.
18296 This filter accepts the following options:
18306 Set 1st rect x coordinate.
18309 Set 1st rect y coordinate.
18312 Set 2nd rect x coordinate.
18315 Set 2nd rect y coordinate.
18317 All expressions are evaluated once for each frame.
18320 The all options are expressions containing the following constants:
18325 The input width and height.
18328 same as @var{w} / @var{h}
18331 input sample aspect ratio
18334 input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
18337 The number of the input frame, starting from 0.
18340 The timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
18343 the position in the file of the input frame, NAN if unknown
18350 Blend successive video frames.
18356 Apply telecine process to the video.
18358 This filter accepts the following options:
18367 The default value is @code{top}.
18371 A string of numbers representing the pulldown pattern you wish to apply.
18372 The default value is @code{23}.
18376 Some typical patterns:
18381 24p: 2332 (preferred)
18388 24p: 222222222223 ("Euro pulldown")
18393 @section thistogram
18395 Compute and draw a color distribution histogram for the input video across time.
18397 Unlike @ref{histogram} video filter which only shows histogram of single input frame
18398 at certain time, this filter shows also past histograms of number of frames defined
18399 by @code{width} option.
18401 The computed histogram is a representation of the color component
18402 distribution in an image.
18404 The filter accepts the following options:
18408 Set width of single color component output. Default value is @code{0}.
18409 Value of @code{0} means width will be picked from input video.
18410 This also set number of passed histograms to keep.
18411 Allowed range is [0, 8192].
18413 @item display_mode, d
18415 It accepts the following values:
18418 Per color component graphs are placed below each other.
18421 Per color component graphs are placed side by side.
18424 Presents information identical to that in the @code{parade}, except
18425 that the graphs representing color components are superimposed directly
18428 Default is @code{stack}.
18430 @item levels_mode, m
18431 Set mode. Can be either @code{linear}, or @code{logarithmic}.
18432 Default is @code{linear}.
18434 @item components, c
18435 Set what color components to display.
18436 Default is @code{7}.
18439 Set background opacity. Default is @code{0.9}.
18442 Show envelope. Default is disabled.
18445 Set envelope color. Default is @code{gold}.
18450 Available values for slide is:
18453 Draw new frame when right border is reached.
18456 Replace old columns with new ones.
18459 Scroll from right to left.
18462 Scroll from left to right.
18465 Draw single picture.
18468 Default is @code{replace}.
18473 Apply threshold effect to video stream.
18475 This filter needs four video streams to perform thresholding.
18476 First stream is stream we are filtering.
18477 Second stream is holding threshold values, third stream is holding min values,
18478 and last, fourth stream is holding max values.
18480 The filter accepts the following option:
18484 Set which planes will be processed, unprocessed planes will be copied.
18485 By default value 0xf, all planes will be processed.
18488 For example if first stream pixel's component value is less then threshold value
18489 of pixel component from 2nd threshold stream, third stream value will picked,
18490 otherwise fourth stream pixel component value will be picked.
18492 Using color source filter one can perform various types of thresholding:
18494 @subsection Examples
18498 Binary threshold, using gray color as threshold:
18500 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=black -f lavfi -i color=white -lavfi threshold output.avi
18504 Inverted binary threshold, using gray color as threshold:
18506 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -f lavfi -i color=black -lavfi threshold output.avi
18510 Truncate binary threshold, using gray color as threshold:
18512 ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=gray -lavfi threshold output.avi
18516 Threshold to zero, using gray color as threshold:
18518 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -i 320x240.avi -lavfi threshold output.avi
18522 Inverted threshold to zero, using gray color as threshold:
18524 ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=white -lavfi threshold output.avi
18529 Select the most representative frame in a given sequence of consecutive frames.
18531 The filter accepts the following options:
18535 Set the frames batch size to analyze; in a set of @var{n} frames, the filter
18536 will pick one of them, and then handle the next batch of @var{n} frames until
18537 the end. Default is @code{100}.
18540 Since the filter keeps track of the whole frames sequence, a bigger @var{n}
18541 value will result in a higher memory usage, so a high value is not recommended.
18543 @subsection Examples
18547 Extract one picture each 50 frames:
18553 Complete example of a thumbnail creation with @command{ffmpeg}:
18555 ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png
18562 Tile several successive frames together.
18564 The @ref{untile} filter can do the reverse.
18566 The filter accepts the following options:
18571 Set the grid size (i.e. the number of lines and columns). For the syntax of
18572 this option, check the
18573 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
18576 Set the maximum number of frames to render in the given area. It must be less
18577 than or equal to @var{w}x@var{h}. The default value is @code{0}, meaning all
18578 the area will be used.
18581 Set the outer border margin in pixels.
18584 Set the inner border thickness (i.e. the number of pixels between frames). For
18585 more advanced padding options (such as having different values for the edges),
18586 refer to the pad video filter.
18589 Specify the color of the unused area. For the syntax of this option, check the
18590 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
18591 The default value of @var{color} is "black".
18594 Set the number of frames to overlap when tiling several successive frames together.
18595 The value must be between @code{0} and @var{nb_frames - 1}.
18598 Set the number of frames to initially be empty before displaying first output frame.
18599 This controls how soon will one get first output frame.
18600 The value must be between @code{0} and @var{nb_frames - 1}.
18603 @subsection Examples
18607 Produce 8x8 PNG tiles of all keyframes (@option{-skip_frame nokey}) in a movie:
18609 ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -vsync 0 keyframes%03d.png
18611 The @option{-vsync 0} is necessary to prevent @command{ffmpeg} from
18612 duplicating each output frame to accommodate the originally detected frame
18616 Display @code{5} pictures in an area of @code{3x2} frames,
18617 with @code{7} pixels between them, and @code{2} pixels of initial margin, using
18618 mixed flat and named options:
18620 tile=3x2:nb_frames=5:padding=7:margin=2
18624 @section tinterlace
18626 Perform various types of temporal field interlacing.
18628 Frames are counted starting from 1, so the first input frame is
18631 The filter accepts the following options:
18636 Specify the mode of the interlacing. This option can also be specified
18637 as a value alone. See below for a list of values for this option.
18639 Available values are:
18643 Move odd frames into the upper field, even into the lower field,
18644 generating a double height frame at half frame rate.
18648 Frame 1 Frame 2 Frame 3 Frame 4
18650 11111 22222 33333 44444
18651 11111 22222 33333 44444
18652 11111 22222 33333 44444
18653 11111 22222 33333 44444
18667 Only output odd frames, even frames are dropped, generating a frame with
18668 unchanged height at half frame rate.
18673 Frame 1 Frame 2 Frame 3 Frame 4
18675 11111 22222 33333 44444
18676 11111 22222 33333 44444
18677 11111 22222 33333 44444
18678 11111 22222 33333 44444
18688 Only output even frames, odd frames are dropped, generating a frame with
18689 unchanged height at half frame rate.
18694 Frame 1 Frame 2 Frame 3 Frame 4
18696 11111 22222 33333 44444
18697 11111 22222 33333 44444
18698 11111 22222 33333 44444
18699 11111 22222 33333 44444
18709 Expand each frame to full height, but pad alternate lines with black,
18710 generating a frame with double height at the same input frame rate.
18715 Frame 1 Frame 2 Frame 3 Frame 4
18717 11111 22222 33333 44444
18718 11111 22222 33333 44444
18719 11111 22222 33333 44444
18720 11111 22222 33333 44444
18723 11111 ..... 33333 .....
18724 ..... 22222 ..... 44444
18725 11111 ..... 33333 .....
18726 ..... 22222 ..... 44444
18727 11111 ..... 33333 .....
18728 ..... 22222 ..... 44444
18729 11111 ..... 33333 .....
18730 ..... 22222 ..... 44444
18734 @item interleave_top, 4
18735 Interleave the upper field from odd frames with the lower field from
18736 even frames, generating a frame with unchanged height at half frame rate.
18741 Frame 1 Frame 2 Frame 3 Frame 4
18743 11111<- 22222 33333<- 44444
18744 11111 22222<- 33333 44444<-
18745 11111<- 22222 33333<- 44444
18746 11111 22222<- 33333 44444<-
18756 @item interleave_bottom, 5
18757 Interleave the lower field from odd frames with the upper field from
18758 even frames, generating a frame with unchanged height at half frame rate.
18763 Frame 1 Frame 2 Frame 3 Frame 4
18765 11111 22222<- 33333 44444<-
18766 11111<- 22222 33333<- 44444
18767 11111 22222<- 33333 44444<-
18768 11111<- 22222 33333<- 44444
18778 @item interlacex2, 6
18779 Double frame rate with unchanged height. Frames are inserted each
18780 containing the second temporal field from the previous input frame and
18781 the first temporal field from the next input frame. This mode relies on
18782 the top_field_first flag. Useful for interlaced video displays with no
18783 field synchronisation.
18788 Frame 1 Frame 2 Frame 3 Frame 4
18790 11111 22222 33333 44444
18791 11111 22222 33333 44444
18792 11111 22222 33333 44444
18793 11111 22222 33333 44444
18796 11111 22222 22222 33333 33333 44444 44444
18797 11111 11111 22222 22222 33333 33333 44444
18798 11111 22222 22222 33333 33333 44444 44444
18799 11111 11111 22222 22222 33333 33333 44444
18804 Move odd frames into the upper field, even into the lower field,
18805 generating a double height frame at same frame rate.
18810 Frame 1 Frame 2 Frame 3 Frame 4
18812 11111 22222 33333 44444
18813 11111 22222 33333 44444
18814 11111 22222 33333 44444
18815 11111 22222 33333 44444
18818 11111 33333 33333 55555
18819 22222 22222 44444 44444
18820 11111 33333 33333 55555
18821 22222 22222 44444 44444
18822 11111 33333 33333 55555
18823 22222 22222 44444 44444
18824 11111 33333 33333 55555
18825 22222 22222 44444 44444
18830 Numeric values are deprecated but are accepted for backward
18831 compatibility reasons.
18833 Default mode is @code{merge}.
18836 Specify flags influencing the filter process.
18838 Available value for @var{flags} is:
18841 @item low_pass_filter, vlpf
18842 Enable linear vertical low-pass filtering in the filter.
18843 Vertical low-pass filtering is required when creating an interlaced
18844 destination from a progressive source which contains high-frequency
18845 vertical detail. Filtering will reduce interlace 'twitter' and Moire
18848 @item complex_filter, cvlpf
18849 Enable complex vertical low-pass filtering.
18850 This will slightly less reduce interlace 'twitter' and Moire
18851 patterning but better retain detail and subjective sharpness impression.
18854 Bypass already interlaced frames, only adjust the frame rate.
18857 Vertical low-pass filtering and bypassing already interlaced frames can only be
18858 enabled for @option{mode} @var{interleave_top} and @var{interleave_bottom}.
18863 Pick median pixels from several successive input video frames.
18865 The filter accepts the following options:
18869 Set radius of median filter.
18870 Default is 1. Allowed range is from 1 to 127.
18873 Set which planes to filter. Default value is @code{15}, by which all planes are processed.
18876 Set median percentile. Default value is @code{0.5}.
18877 Default value of @code{0.5} will pick always median values, while @code{0} will pick
18878 minimum values, and @code{1} maximum values.
18883 Mix successive video frames.
18885 A description of the accepted options follows.
18889 The number of successive frames to mix. If unspecified, it defaults to 3.
18892 Specify weight of each input video frame.
18893 Each weight is separated by space. If number of weights is smaller than
18894 number of @var{frames} last specified weight will be used for all remaining
18898 Specify scale, if it is set it will be multiplied with sum
18899 of each weight multiplied with pixel values to give final destination
18900 pixel value. By default @var{scale} is auto scaled to sum of weights.
18903 @subsection Examples
18907 Average 7 successive frames:
18909 tmix=frames=7:weights="1 1 1 1 1 1 1"
18913 Apply simple temporal convolution:
18915 tmix=frames=3:weights="-1 3 -1"
18919 Similar as above but only showing temporal differences:
18921 tmix=frames=3:weights="-1 2 -1":scale=1
18927 Tone map colors from different dynamic ranges.
18929 This filter expects data in single precision floating point, as it needs to
18930 operate on (and can output) out-of-range values. Another filter, such as
18931 @ref{zscale}, is needed to convert the resulting frame to a usable format.
18933 The tonemapping algorithms implemented only work on linear light, so input
18934 data should be linearized beforehand (and possibly correctly tagged).
18937 ffmpeg -i INPUT -vf zscale=transfer=linear,tonemap=clip,zscale=transfer=bt709,format=yuv420p OUTPUT
18940 @subsection Options
18941 The filter accepts the following options.
18945 Set the tone map algorithm to use.
18947 Possible values are:
18950 Do not apply any tone map, only desaturate overbright pixels.
18953 Hard-clip any out-of-range values. Use it for perfect color accuracy for
18954 in-range values, while distorting out-of-range values.
18957 Stretch the entire reference gamut to a linear multiple of the display.
18960 Fit a logarithmic transfer between the tone curves.
18963 Preserve overall image brightness with a simple curve, using nonlinear
18964 contrast, which results in flattening details and degrading color accuracy.
18967 Preserve both dark and bright details better than @var{reinhard}, at the cost
18968 of slightly darkening everything. Use it when detail preservation is more
18969 important than color and brightness accuracy.
18972 Smoothly map out-of-range values, while retaining contrast and colors for
18973 in-range material as much as possible. Use it when color accuracy is more
18974 important than detail preservation.
18980 Tune the tone mapping algorithm.
18982 This affects the following algorithms:
18988 Specifies the scale factor to use while stretching.
18992 Specifies the exponent of the function.
18996 Specify an extra linear coefficient to multiply into the signal before clipping.
19000 Specify the local contrast coefficient at the display peak.
19001 Default to 0.5, which means that in-gamut values will be about half as bright
19008 Specify the transition point from linear to mobius transform. Every value
19009 below this point is guaranteed to be mapped 1:1. The higher the value, the
19010 more accurate the result will be, at the cost of losing bright details.
19011 Default to 0.3, which due to the steep initial slope still preserves in-range
19012 colors fairly accurately.
19016 Apply desaturation for highlights that exceed this level of brightness. The
19017 higher the parameter, the more color information will be preserved. This
19018 setting helps prevent unnaturally blown-out colors for super-highlights, by
19019 (smoothly) turning into white instead. This makes images feel more natural,
19020 at the cost of reducing information about out-of-range colors.
19022 The default of 2.0 is somewhat conservative and will mostly just apply to
19023 skies or directly sunlit surfaces. A setting of 0.0 disables this option.
19025 This option works only if the input frame has a supported color tag.
19028 Override signal/nominal/reference peak with this value. Useful when the
19029 embedded peak information in display metadata is not reliable or when tone
19030 mapping from a lower range to a higher range.
19035 Temporarily pad video frames.
19037 The filter accepts the following options:
19041 Specify number of delay frames before input video stream. Default is 0.
19044 Specify number of padding frames after input video stream.
19045 Set to -1 to pad indefinitely. Default is 0.
19048 Set kind of frames added to beginning of stream.
19049 Can be either @var{add} or @var{clone}.
19050 With @var{add} frames of solid-color are added.
19051 With @var{clone} frames are clones of first frame.
19052 Default is @var{add}.
19055 Set kind of frames added to end of stream.
19056 Can be either @var{add} or @var{clone}.
19057 With @var{add} frames of solid-color are added.
19058 With @var{clone} frames are clones of last frame.
19059 Default is @var{add}.
19061 @item start_duration, stop_duration
19062 Specify the duration of the start/stop delay. See
19063 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
19064 for the accepted syntax.
19065 These options override @var{start} and @var{stop}. Default is 0.
19068 Specify the color of the padded area. For the syntax of this option,
19069 check the @ref{color syntax,,"Color" section in the ffmpeg-utils
19070 manual,ffmpeg-utils}.
19072 The default value of @var{color} is "black".
19078 Transpose rows with columns in the input video and optionally flip it.
19080 It accepts the following parameters:
19085 Specify the transposition direction.
19087 Can assume the following values:
19089 @item 0, 4, cclock_flip
19090 Rotate by 90 degrees counterclockwise and vertically flip (default), that is:
19098 Rotate by 90 degrees clockwise, that is:
19106 Rotate by 90 degrees counterclockwise, that is:
19113 @item 3, 7, clock_flip
19114 Rotate by 90 degrees clockwise and vertically flip, that is:
19122 For values between 4-7, the transposition is only done if the input
19123 video geometry is portrait and not landscape. These values are
19124 deprecated, the @code{passthrough} option should be used instead.
19126 Numerical values are deprecated, and should be dropped in favor of
19127 symbolic constants.
19130 Do not apply the transposition if the input geometry matches the one
19131 specified by the specified value. It accepts the following values:
19134 Always apply transposition.
19136 Preserve portrait geometry (when @var{height} >= @var{width}).
19138 Preserve landscape geometry (when @var{width} >= @var{height}).
19141 Default value is @code{none}.
19144 For example to rotate by 90 degrees clockwise and preserve portrait
19147 transpose=dir=1:passthrough=portrait
19150 The command above can also be specified as:
19152 transpose=1:portrait
19155 @section transpose_npp
19157 Transpose rows with columns in the input video and optionally flip it.
19158 For more in depth examples see the @ref{transpose} video filter, which shares mostly the same options.
19160 It accepts the following parameters:
19165 Specify the transposition direction.
19167 Can assume the following values:
19170 Rotate by 90 degrees counterclockwise and vertically flip. (default)
19173 Rotate by 90 degrees clockwise.
19176 Rotate by 90 degrees counterclockwise.
19179 Rotate by 90 degrees clockwise and vertically flip.
19183 Do not apply the transposition if the input geometry matches the one
19184 specified by the specified value. It accepts the following values:
19187 Always apply transposition. (default)
19189 Preserve portrait geometry (when @var{height} >= @var{width}).
19191 Preserve landscape geometry (when @var{width} >= @var{height}).
19197 Trim the input so that the output contains one continuous subpart of the input.
19199 It accepts the following parameters:
19202 Specify the time of the start of the kept section, i.e. the frame with the
19203 timestamp @var{start} will be the first frame in the output.
19206 Specify the time of the first frame that will be dropped, i.e. the frame
19207 immediately preceding the one with the timestamp @var{end} will be the last
19208 frame in the output.
19211 This is the same as @var{start}, except this option sets the start timestamp
19212 in timebase units instead of seconds.
19215 This is the same as @var{end}, except this option sets the end timestamp
19216 in timebase units instead of seconds.
19219 The maximum duration of the output in seconds.
19222 The number of the first frame that should be passed to the output.
19225 The number of the first frame that should be dropped.
19228 @option{start}, @option{end}, and @option{duration} are expressed as time
19229 duration specifications; see
19230 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
19231 for the accepted syntax.
19233 Note that the first two sets of the start/end options and the @option{duration}
19234 option look at the frame timestamp, while the _frame variants simply count the
19235 frames that pass through the filter. Also note that this filter does not modify
19236 the timestamps. If you wish for the output timestamps to start at zero, insert a
19237 setpts filter after the trim filter.
19239 If multiple start or end options are set, this filter tries to be greedy and
19240 keep all the frames that match at least one of the specified constraints. To keep
19241 only the part that matches all the constraints at once, chain multiple trim
19244 The defaults are such that all the input is kept. So it is possible to set e.g.
19245 just the end values to keep everything before the specified time.
19250 Drop everything except the second minute of input:
19252 ffmpeg -i INPUT -vf trim=60:120
19256 Keep only the first second:
19258 ffmpeg -i INPUT -vf trim=duration=1
19263 @section unpremultiply
19264 Apply alpha unpremultiply effect to input video stream using first plane
19265 of second stream as alpha.
19267 Both streams must have same dimensions and same pixel format.
19269 The filter accepts the following option:
19273 Set which planes will be processed, unprocessed planes will be copied.
19274 By default value 0xf, all planes will be processed.
19276 If the format has 1 or 2 components, then luma is bit 0.
19277 If the format has 3 or 4 components:
19278 for RGB formats bit 0 is green, bit 1 is blue and bit 2 is red;
19279 for YUV formats bit 0 is luma, bit 1 is chroma-U and bit 2 is chroma-V.
19280 If present, the alpha channel is always the last bit.
19283 Do not require 2nd input for processing, instead use alpha plane from input stream.
19289 Sharpen or blur the input video.
19291 It accepts the following parameters:
19294 @item luma_msize_x, lx
19295 Set the luma matrix horizontal size. It must be an odd integer between
19296 3 and 23. The default value is 5.
19298 @item luma_msize_y, ly
19299 Set the luma matrix vertical size. It must be an odd integer between 3
19300 and 23. The default value is 5.
19302 @item luma_amount, la
19303 Set the luma effect strength. It must be a floating point number, reasonable
19304 values lay between -1.5 and 1.5.
19306 Negative values will blur the input video, while positive values will
19307 sharpen it, a value of zero will disable the effect.
19309 Default value is 1.0.
19311 @item chroma_msize_x, cx
19312 Set the chroma matrix horizontal size. It must be an odd integer
19313 between 3 and 23. The default value is 5.
19315 @item chroma_msize_y, cy
19316 Set the chroma matrix vertical size. It must be an odd integer
19317 between 3 and 23. The default value is 5.
19319 @item chroma_amount, ca
19320 Set the chroma effect strength. It must be a floating point number, reasonable
19321 values lay between -1.5 and 1.5.
19323 Negative values will blur the input video, while positive values will
19324 sharpen it, a value of zero will disable the effect.
19326 Default value is 0.0.
19330 All parameters are optional and default to the equivalent of the
19331 string '5:5:1.0:5:5:0.0'.
19333 @subsection Examples
19337 Apply strong luma sharpen effect:
19339 unsharp=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5
19343 Apply a strong blur of both luma and chroma parameters:
19345 unsharp=7:7:-2:7:7:-2
19352 Decompose a video made of tiled images into the individual images.
19354 The frame rate of the output video is the frame rate of the input video
19355 multiplied by the number of tiles.
19357 This filter does the reverse of @ref{tile}.
19359 The filter accepts the following options:
19364 Set the grid size (i.e. the number of lines and columns). For the syntax of
19365 this option, check the
19366 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
19369 @subsection Examples
19373 Produce a 1-second video from a still image file made of 25 frames stacked
19374 vertically, like an analogic film reel:
19376 ffmpeg -r 1 -i image.jpg -vf untile=1x25 movie.mkv
19382 Apply ultra slow/simple postprocessing filter that compresses and decompresses
19383 the image at several (or - in the case of @option{quality} level @code{8} - all)
19384 shifts and average the results.
19386 The way this differs from the behavior of spp is that uspp actually encodes &
19387 decodes each case with libavcodec Snow, whereas spp uses a simplified intra only 8x8
19388 DCT similar to MJPEG.
19390 The filter accepts the following options:
19394 Set quality. This option defines the number of levels for averaging. It accepts
19395 an integer in the range 0-8. If set to @code{0}, the filter will have no
19396 effect. A value of @code{8} means the higher quality. For each increment of
19397 that value the speed drops by a factor of approximately 2. Default value is
19401 Force a constant quantization parameter. If not set, the filter will use the QP
19402 from the video stream (if available).
19407 Convert 360 videos between various formats.
19409 The filter accepts the following options:
19415 Set format of the input/output video.
19423 Equirectangular projection.
19428 Cubemap with 3x2/6x1/1x6 layout.
19430 Format specific options:
19435 Set padding proportion for the input/output cubemap. Values in decimals.
19442 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)
19445 Default value is @b{@samp{0}}.
19446 Maximum value is @b{@samp{0.1}}.
19450 Set fixed padding for the input/output cubemap. Values in pixels.
19452 Default value is @b{@samp{0}}. If greater than zero it overrides other padding options.
19456 Set order of faces for the input/output cubemap. Choose one direction for each position.
19458 Designation of directions:
19474 Default value is @b{@samp{rludfb}}.
19478 Set rotation of faces for the input/output cubemap. Choose one angle for each position.
19480 Designation of angles:
19483 0 degrees clockwise
19485 90 degrees clockwise
19487 180 degrees clockwise
19489 270 degrees clockwise
19492 Default value is @b{@samp{000000}}.
19496 Equi-Angular Cubemap.
19503 Format specific options:
19508 Set output horizontal/vertical/diagonal field of view. Values in degrees.
19510 If diagonal field of view is set it overrides horizontal and vertical field of view.
19515 Set input horizontal/vertical/diagonal field of view. Values in degrees.
19517 If diagonal field of view is set it overrides horizontal and vertical field of view.
19523 Format specific options:
19528 Set output horizontal/vertical/diagonal field of view. Values in degrees.
19530 If diagonal field of view is set it overrides horizontal and vertical field of view.
19535 Set input horizontal/vertical/diagonal field of view. Values in degrees.
19537 If diagonal field of view is set it overrides horizontal and vertical field of view.
19543 Facebook's 360 formats.
19546 Stereographic format.
19548 Format specific options:
19553 Set output horizontal/vertical/diagonal field of view. Values in degrees.
19555 If diagonal field of view is set it overrides horizontal and vertical field of view.
19560 Set input horizontal/vertical/diagonal field of view. Values in degrees.
19562 If diagonal field of view is set it overrides horizontal and vertical field of view.
19569 Ball format, gives significant distortion toward the back.
19572 Hammer-Aitoff map projection format.
19575 Sinusoidal map projection format.
19578 Fisheye projection.
19580 Format specific options:
19585 Set output horizontal/vertical/diagonal field of view. Values in degrees.
19587 If diagonal field of view is set it overrides horizontal and vertical field of view.
19592 Set input horizontal/vertical/diagonal field of view. Values in degrees.
19594 If diagonal field of view is set it overrides horizontal and vertical field of view.
19598 Pannini projection.
19600 Format specific options:
19603 Set output pannini parameter.
19606 Set input pannini parameter.
19610 Cylindrical projection.
19612 Format specific options:
19617 Set output horizontal/vertical/diagonal field of view. Values in degrees.
19619 If diagonal field of view is set it overrides horizontal and vertical field of view.
19624 Set input horizontal/vertical/diagonal field of view. Values in degrees.
19626 If diagonal field of view is set it overrides horizontal and vertical field of view.
19630 Perspective projection. @i{(output only)}
19632 Format specific options:
19635 Set perspective parameter.
19639 Tetrahedron projection.
19642 Truncated square pyramid projection.
19646 Half equirectangular projection.
19651 Format specific options:
19656 Set output horizontal/vertical/diagonal field of view. Values in degrees.
19658 If diagonal field of view is set it overrides horizontal and vertical field of view.
19663 Set input horizontal/vertical/diagonal field of view. Values in degrees.
19665 If diagonal field of view is set it overrides horizontal and vertical field of view.
19669 Orthographic format.
19671 Format specific options:
19676 Set output horizontal/vertical/diagonal field of view. Values in degrees.
19678 If diagonal field of view is set it overrides horizontal and vertical field of view.
19683 Set input horizontal/vertical/diagonal field of view. Values in degrees.
19685 If diagonal field of view is set it overrides horizontal and vertical field of view.
19689 Octahedron projection.
19693 Set interpolation method.@*
19694 @i{Note: more complex interpolation methods require much more memory to run.}
19704 Bilinear interpolation.
19706 Lagrange9 interpolation.
19709 Bicubic interpolation.
19712 Lanczos interpolation.
19715 Spline16 interpolation.
19718 Gaussian interpolation.
19720 Mitchell interpolation.
19723 Default value is @b{@samp{line}}.
19727 Set the output video resolution.
19729 Default resolution depends on formats.
19733 Set the input/output stereo format.
19744 Default value is @b{@samp{2d}} for input and output format.
19749 Set rotation for the output video. Values in degrees.
19752 Set rotation order for the output video. Choose one item for each position.
19763 Default value is @b{@samp{ypr}}.
19768 Flip the output video horizontally(swaps left-right)/vertically(swaps up-down)/in-depth(swaps back-forward). Boolean values.
19772 Set if input video is flipped horizontally/vertically. Boolean values.
19775 Set if input video is transposed. Boolean value, by default disabled.
19778 Set if output video needs to be transposed. Boolean value, by default disabled.
19781 Build mask in alpha plane for all unmapped pixels by marking them fully transparent. Boolean value, by default disabled.
19784 @subsection Examples
19788 Convert equirectangular video to cubemap with 3x2 layout and 1% padding using bicubic interpolation:
19790 ffmpeg -i input.mkv -vf v360=e:c3x2:cubic:out_pad=0.01 output.mkv
19793 Extract back view of Equi-Angular Cubemap:
19795 ffmpeg -i input.mkv -vf v360=eac:flat:yaw=180 output.mkv
19798 Convert transposed and horizontally flipped Equi-Angular Cubemap in side-by-side stereo format to equirectangular top-bottom stereo format:
19800 v360=eac:equirect:in_stereo=sbs:in_trans=1:ih_flip=1:out_stereo=tb
19804 @subsection Commands
19806 This filter supports subset of above options as @ref{commands}.
19808 @section vaguedenoiser
19810 Apply a wavelet based denoiser.
19812 It transforms each frame from the video input into the wavelet domain,
19813 using Cohen-Daubechies-Feauveau 9/7. Then it applies some filtering to
19814 the obtained coefficients. It does an inverse wavelet transform after.
19815 Due to wavelet properties, it should give a nice smoothed result, and
19816 reduced noise, without blurring picture features.
19818 This filter accepts the following options:
19822 The filtering strength. The higher, the more filtered the video will be.
19823 Hard thresholding can use a higher threshold than soft thresholding
19824 before the video looks overfiltered. Default value is 2.
19827 The filtering method the filter will use.
19829 It accepts the following values:
19832 All values under the threshold will be zeroed.
19835 All values under the threshold will be zeroed. All values above will be
19836 reduced by the threshold.
19839 Scales or nullifies coefficients - intermediary between (more) soft and
19840 (less) hard thresholding.
19843 Default is garrote.
19846 Number of times, the wavelet will decompose the picture. Picture can't
19847 be decomposed beyond a particular point (typically, 8 for a 640x480
19848 frame - as 2^9 = 512 > 480). Valid values are integers between 1 and 32. Default value is 6.
19851 Partial of full denoising (limited coefficients shrinking), from 0 to 100. Default value is 85.
19854 A list of the planes to process. By default all planes are processed.
19857 The threshold type the filter will use.
19859 It accepts the following values:
19862 Threshold used is same for all decompositions.
19865 Threshold used depends also on each decomposition coefficients.
19868 Default is universal.
19871 @section vectorscope
19873 Display 2 color component values in the two dimensional graph (which is called
19876 This filter accepts the following options:
19880 Set vectorscope mode.
19882 It accepts the following values:
19886 Gray values are displayed on graph, higher brightness means more pixels have
19887 same component color value on location in graph. This is the default mode.
19890 Gray values are displayed on graph. Surrounding pixels values which are not
19891 present in video frame are drawn in gradient of 2 color components which are
19892 set by option @code{x} and @code{y}. The 3rd color component is static.
19895 Actual color components values present in video frame are displayed on graph.
19898 Similar as color2 but higher frequency of same values @code{x} and @code{y}
19899 on graph increases value of another color component, which is luminance by
19900 default values of @code{x} and @code{y}.
19903 Actual colors present in video frame are displayed on graph. If two different
19904 colors map to same position on graph then color with higher value of component
19905 not present in graph is picked.
19908 Gray values are displayed on graph. Similar to @code{color} but with 3rd color
19909 component picked from radial gradient.
19913 Set which color component will be represented on X-axis. Default is @code{1}.
19916 Set which color component will be represented on Y-axis. Default is @code{2}.
19919 Set intensity, used by modes: gray, color, color3 and color5 for increasing brightness
19920 of color component which represents frequency of (X, Y) location in graph.
19925 No envelope, this is default.
19928 Instant envelope, even darkest single pixel will be clearly highlighted.
19931 Hold maximum and minimum values presented in graph over time. This way you
19932 can still spot out of range values without constantly looking at vectorscope.
19935 Peak and instant envelope combined together.
19939 Set what kind of graticule to draw.
19948 Set graticule opacity.
19951 Set graticule flags.
19955 Draw graticule for white point.
19958 Draw graticule for black point.
19961 Draw color points short names.
19965 Set background opacity.
19967 @item lthreshold, l
19968 Set low threshold for color component not represented on X or Y axis.
19969 Values lower than this value will be ignored. Default is 0.
19970 Note this value is multiplied with actual max possible value one pixel component
19971 can have. So for 8-bit input and low threshold value of 0.1 actual threshold
19974 @item hthreshold, h
19975 Set high threshold for color component not represented on X or Y axis.
19976 Values higher than this value will be ignored. Default is 1.
19977 Note this value is multiplied with actual max possible value one pixel component
19978 can have. So for 8-bit input and high threshold value of 0.9 actual threshold
19979 is 0.9 * 255 = 230.
19981 @item colorspace, c
19982 Set what kind of colorspace to use when drawing graticule.
19992 Set color tint for gray/tint vectorscope mode. By default both options are zero.
19993 This means no tint, and output will remain gray.
19996 @anchor{vidstabdetect}
19997 @section vidstabdetect
19999 Analyze video stabilization/deshaking. Perform pass 1 of 2, see
20000 @ref{vidstabtransform} for pass 2.
20002 This filter generates a file with relative translation and rotation
20003 transform information about subsequent frames, which is then used by
20004 the @ref{vidstabtransform} filter.
20006 To enable compilation of this filter you need to configure FFmpeg with
20007 @code{--enable-libvidstab}.
20009 This filter accepts the following options:
20013 Set the path to the file used to write the transforms information.
20014 Default value is @file{transforms.trf}.
20017 Set how shaky the video is and how quick the camera is. It accepts an
20018 integer in the range 1-10, a value of 1 means little shakiness, a
20019 value of 10 means strong shakiness. Default value is 5.
20022 Set the accuracy of the detection process. It must be a value in the
20023 range 1-15. A value of 1 means low accuracy, a value of 15 means high
20024 accuracy. Default value is 15.
20027 Set stepsize of the search process. The region around minimum is
20028 scanned with 1 pixel resolution. Default value is 6.
20031 Set minimum contrast. Below this value a local measurement field is
20032 discarded. Must be a floating point value in the range 0-1. Default
20036 Set reference frame number for tripod mode.
20038 If enabled, the motion of the frames is compared to a reference frame
20039 in the filtered stream, identified by the specified number. The idea
20040 is to compensate all movements in a more-or-less static scene and keep
20041 the camera view absolutely still.
20043 If set to 0, it is disabled. The frames are counted starting from 1.
20046 Show fields and transforms in the resulting frames. It accepts an
20047 integer in the range 0-2. Default value is 0, which disables any
20051 @subsection Examples
20055 Use default values:
20061 Analyze strongly shaky movie and put the results in file
20062 @file{mytransforms.trf}:
20064 vidstabdetect=shakiness=10:accuracy=15:result="mytransforms.trf"
20068 Visualize the result of internal transformations in the resulting
20071 vidstabdetect=show=1
20075 Analyze a video with medium shakiness using @command{ffmpeg}:
20077 ffmpeg -i input -vf vidstabdetect=shakiness=5:show=1 dummy.avi
20081 @anchor{vidstabtransform}
20082 @section vidstabtransform
20084 Video stabilization/deshaking: pass 2 of 2,
20085 see @ref{vidstabdetect} for pass 1.
20087 Read a file with transform information for each frame and
20088 apply/compensate them. Together with the @ref{vidstabdetect}
20089 filter this can be used to deshake videos. See also
20090 @url{http://public.hronopik.de/vid.stab}. It is important to also use
20091 the @ref{unsharp} filter, see below.
20093 To enable compilation of this filter you need to configure FFmpeg with
20094 @code{--enable-libvidstab}.
20096 @subsection Options
20100 Set path to the file used to read the transforms. Default value is
20101 @file{transforms.trf}.
20104 Set the number of frames (value*2 + 1) used for lowpass filtering the
20105 camera movements. Default value is 10.
20107 For example a number of 10 means that 21 frames are used (10 in the
20108 past and 10 in the future) to smoothen the motion in the video. A
20109 larger value leads to a smoother video, but limits the acceleration of
20110 the camera (pan/tilt movements). 0 is a special case where a static
20111 camera is simulated.
20114 Set the camera path optimization algorithm.
20116 Accepted values are:
20119 gaussian kernel low-pass filter on camera motion (default)
20121 averaging on transformations
20125 Set maximal number of pixels to translate frames. Default value is -1,
20129 Set maximal angle in radians (degree*PI/180) to rotate frames. Default
20130 value is -1, meaning no limit.
20133 Specify how to deal with borders that may be visible due to movement
20136 Available values are:
20139 keep image information from previous frame (default)
20141 fill the border black
20145 Invert transforms if set to 1. Default value is 0.
20148 Consider transforms as relative to previous frame if set to 1,
20149 absolute if set to 0. Default value is 0.
20152 Set percentage to zoom. A positive value will result in a zoom-in
20153 effect, a negative value in a zoom-out effect. Default value is 0 (no
20157 Set optimal zooming to avoid borders.
20159 Accepted values are:
20164 optimal static zoom value is determined (only very strong movements
20165 will lead to visible borders) (default)
20167 optimal adaptive zoom value is determined (no borders will be
20168 visible), see @option{zoomspeed}
20171 Note that the value given at zoom is added to the one calculated here.
20174 Set percent to zoom maximally each frame (enabled when
20175 @option{optzoom} is set to 2). Range is from 0 to 5, default value is
20179 Specify type of interpolation.
20181 Available values are:
20186 linear only horizontal
20188 linear in both directions (default)
20190 cubic in both directions (slow)
20194 Enable virtual tripod mode if set to 1, which is equivalent to
20195 @code{relative=0:smoothing=0}. Default value is 0.
20197 Use also @code{tripod} option of @ref{vidstabdetect}.
20200 Increase log verbosity if set to 1. Also the detected global motions
20201 are written to the temporary file @file{global_motions.trf}. Default
20205 @subsection Examples
20209 Use @command{ffmpeg} for a typical stabilization with default values:
20211 ffmpeg -i inp.mpeg -vf vidstabtransform,unsharp=5:5:0.8:3:3:0.4 inp_stabilized.mpeg
20214 Note the use of the @ref{unsharp} filter which is always recommended.
20217 Zoom in a bit more and load transform data from a given file:
20219 vidstabtransform=zoom=5:input="mytransforms.trf"
20223 Smoothen the video even more:
20225 vidstabtransform=smoothing=30
20231 Flip the input video vertically.
20233 For example, to vertically flip a video with @command{ffmpeg}:
20235 ffmpeg -i in.avi -vf "vflip" out.avi
20240 Detect variable frame rate video.
20242 This filter tries to detect if the input is variable or constant frame rate.
20244 At end it will output number of frames detected as having variable delta pts,
20245 and ones with constant delta pts.
20246 If there was frames with variable delta, than it will also show min, max and
20247 average delta encountered.
20251 Boost or alter saturation.
20253 The filter accepts the following options:
20256 Set strength of boost if positive value or strength of alter if negative value.
20257 Default is 0. Allowed range is from -2 to 2.
20260 Set the red balance. Default is 1. Allowed range is from -10 to 10.
20263 Set the green balance. Default is 1. Allowed range is from -10 to 10.
20266 Set the blue balance. Default is 1. Allowed range is from -10 to 10.
20269 Set the red luma coefficient.
20272 Set the green luma coefficient.
20275 Set the blue luma coefficient.
20278 If @code{intensity} is negative and this is set to 1, colors will change,
20279 otherwise colors will be less saturated, more towards gray.
20282 @subsection Commands
20284 This filter supports the all above options as @ref{commands}.
20289 Make or reverse a natural vignetting effect.
20291 The filter accepts the following options:
20295 Set lens angle expression as a number of radians.
20297 The value is clipped in the @code{[0,PI/2]} range.
20299 Default value: @code{"PI/5"}
20303 Set center coordinates expressions. Respectively @code{"w/2"} and @code{"h/2"}
20307 Set forward/backward mode.
20309 Available modes are:
20312 The larger the distance from the central point, the darker the image becomes.
20315 The larger the distance from the central point, the brighter the image becomes.
20316 This can be used to reverse a vignette effect, though there is no automatic
20317 detection to extract the lens @option{angle} and other settings (yet). It can
20318 also be used to create a burning effect.
20321 Default value is @samp{forward}.
20324 Set evaluation mode for the expressions (@option{angle}, @option{x0}, @option{y0}).
20326 It accepts the following values:
20329 Evaluate expressions only once during the filter initialization.
20332 Evaluate expressions for each incoming frame. This is way slower than the
20333 @samp{init} mode since it requires all the scalers to be re-computed, but it
20334 allows advanced dynamic expressions.
20337 Default value is @samp{init}.
20340 Set dithering to reduce the circular banding effects. Default is @code{1}
20344 Set vignette aspect. This setting allows one to adjust the shape of the vignette.
20345 Setting this value to the SAR of the input will make a rectangular vignetting
20346 following the dimensions of the video.
20348 Default is @code{1/1}.
20351 @subsection Expressions
20353 The @option{alpha}, @option{x0} and @option{y0} expressions can contain the
20354 following parameters.
20359 input width and height
20362 the number of input frame, starting from 0
20365 the PTS (Presentation TimeStamp) time of the filtered video frame, expressed in
20366 @var{TB} units, NAN if undefined
20369 frame rate of the input video, NAN if the input frame rate is unknown
20372 the PTS (Presentation TimeStamp) of the filtered video frame,
20373 expressed in seconds, NAN if undefined
20376 time base of the input video
20380 @subsection Examples
20384 Apply simple strong vignetting effect:
20390 Make a flickering vignetting:
20392 vignette='PI/4+random(1)*PI/50':eval=frame
20397 @section vmafmotion
20399 Obtain the average VMAF motion score of a video.
20400 It is one of the component metrics of VMAF.
20402 The obtained average motion score is printed through the logging system.
20404 The filter accepts the following options:
20408 If specified, the filter will use the named file to save the motion score of
20409 each frame with respect to the previous frame.
20410 When filename equals "-" the data is sent to standard output.
20415 ffmpeg -i ref.mpg -vf vmafmotion -f null -
20419 Stack input videos vertically.
20421 All streams must be of same pixel format and of same width.
20423 Note that this filter is faster than using @ref{overlay} and @ref{pad} filter
20424 to create same output.
20426 The filter accepts the following options:
20430 Set number of input streams. Default is 2.
20433 If set to 1, force the output to terminate when the shortest input
20434 terminates. Default value is 0.
20439 Deinterlace the input video ("w3fdif" stands for "Weston 3 Field
20440 Deinterlacing Filter").
20442 Based on the process described by Martin Weston for BBC R&D, and
20443 implemented based on the de-interlace algorithm written by Jim
20444 Easterbrook for BBC R&D, the Weston 3 field deinterlacing filter
20445 uses filter coefficients calculated by BBC R&D.
20447 This filter uses field-dominance information in frame to decide which
20448 of each pair of fields to place first in the output.
20449 If it gets it wrong use @ref{setfield} filter before @code{w3fdif} filter.
20451 There are two sets of filter coefficients, so called "simple"
20452 and "complex". Which set of filter coefficients is used can
20453 be set by passing an optional parameter:
20457 Set the interlacing filter coefficients. Accepts one of the following values:
20461 Simple filter coefficient set.
20463 More-complex filter coefficient set.
20465 Default value is @samp{complex}.
20468 Specify which frames to deinterlace. Accepts one of the following values:
20472 Deinterlace all frames,
20474 Only deinterlace frames marked as interlaced.
20477 Default value is @samp{all}.
20481 Video waveform monitor.
20483 The waveform monitor plots color component intensity. By default luminance
20484 only. Each column of the waveform corresponds to a column of pixels in the
20487 It accepts the following options:
20491 Can be either @code{row}, or @code{column}. Default is @code{column}.
20492 In row mode, the graph on the left side represents color component value 0 and
20493 the right side represents value = 255. In column mode, the top side represents
20494 color component value = 0 and bottom side represents value = 255.
20497 Set intensity. Smaller values are useful to find out how many values of the same
20498 luminance are distributed across input rows/columns.
20499 Default value is @code{0.04}. Allowed range is [0, 1].
20502 Set mirroring mode. @code{0} means unmirrored, @code{1} means mirrored.
20503 In mirrored mode, higher values will be represented on the left
20504 side for @code{row} mode and at the top for @code{column} mode. Default is
20505 @code{1} (mirrored).
20509 It accepts the following values:
20512 Presents information identical to that in the @code{parade}, except
20513 that the graphs representing color components are superimposed directly
20516 This display mode makes it easier to spot relative differences or similarities
20517 in overlapping areas of the color components that are supposed to be identical,
20518 such as neutral whites, grays, or blacks.
20521 Display separate graph for the color components side by side in
20522 @code{row} mode or one below the other in @code{column} mode.
20525 Display separate graph for the color components side by side in
20526 @code{column} mode or one below the other in @code{row} mode.
20528 Using this display mode makes it easy to spot color casts in the highlights
20529 and shadows of an image, by comparing the contours of the top and the bottom
20530 graphs of each waveform. Since whites, grays, and blacks are characterized
20531 by exactly equal amounts of red, green, and blue, neutral areas of the picture
20532 should display three waveforms of roughly equal width/height. If not, the
20533 correction is easy to perform by making level adjustments the three waveforms.
20535 Default is @code{stack}.
20537 @item components, c
20538 Set which color components to display. Default is 1, which means only luminance
20539 or red color component if input is in RGB colorspace. If is set for example to
20540 7 it will display all 3 (if) available color components.
20545 No envelope, this is default.
20548 Instant envelope, minimum and maximum values presented in graph will be easily
20549 visible even with small @code{step} value.
20552 Hold minimum and maximum values presented in graph across time. This way you
20553 can still spot out of range values without constantly looking at waveforms.
20556 Peak and instant envelope combined together.
20562 No filtering, this is default.
20565 Luma and chroma combined together.
20568 Similar as above, but shows difference between blue and red chroma.
20571 Similar as above, but use different colors.
20574 Similar as above, but again with different colors.
20577 Displays only chroma.
20580 Displays actual color value on waveform.
20583 Similar as above, but with luma showing frequency of chroma values.
20587 Set which graticule to display.
20591 Do not display graticule.
20594 Display green graticule showing legal broadcast ranges.
20597 Display orange graticule showing legal broadcast ranges.
20600 Display invert graticule showing legal broadcast ranges.
20604 Set graticule opacity.
20607 Set graticule flags.
20611 Draw numbers above lines. By default enabled.
20614 Draw dots instead of lines.
20618 Set scale used for displaying graticule.
20625 Default is digital.
20628 Set background opacity.
20632 Set tint for output.
20633 Only used with lowpass filter and when display is not overlay and input
20634 pixel formats are not RGB.
20637 @section weave, doubleweave
20639 The @code{weave} takes a field-based video input and join
20640 each two sequential fields into single frame, producing a new double
20641 height clip with half the frame rate and half the frame count.
20643 The @code{doubleweave} works same as @code{weave} but without
20644 halving frame rate and frame count.
20646 It accepts the following option:
20650 Set first field. Available values are:
20654 Set the frame as top-field-first.
20657 Set the frame as bottom-field-first.
20661 @subsection Examples
20665 Interlace video using @ref{select} and @ref{separatefields} filter:
20667 separatefields,select=eq(mod(n,4),0)+eq(mod(n,4),3),weave
20672 Apply the xBR high-quality magnification filter which is designed for pixel
20673 art. It follows a set of edge-detection rules, see
20674 @url{https://forums.libretro.com/t/xbr-algorithm-tutorial/123}.
20676 It accepts the following option:
20680 Set the scaling dimension: @code{2} for @code{2xBR}, @code{3} for
20681 @code{3xBR} and @code{4} for @code{4xBR}.
20682 Default is @code{3}.
20687 Apply cross fade from one input video stream to another input video stream.
20688 The cross fade is applied for specified duration.
20690 The filter accepts the following options:
20694 Set one of available transition effects:
20742 Default transition effect is fade.
20745 Set cross fade duration in seconds.
20746 Default duration is 1 second.
20749 Set cross fade start relative to first input stream in seconds.
20750 Default offset is 0.
20753 Set expression for custom transition effect.
20755 The expressions can use the following variables and functions:
20760 The coordinates of the current sample.
20764 The width and height of the image.
20767 Progress of transition effect.
20770 Currently processed plane.
20773 Return value of first input at current location and plane.
20776 Return value of second input at current location and plane.
20782 Return the value of the pixel at location (@var{x},@var{y}) of the
20783 first/second/third/fourth component of first input.
20789 Return the value of the pixel at location (@var{x},@var{y}) of the
20790 first/second/third/fourth component of second input.
20794 @subsection Examples
20798 Cross fade from one input video to another input video, with fade transition and duration of transition
20799 of 2 seconds starting at offset of 5 seconds:
20801 ffmpeg -i first.mp4 -i second.mp4 -filter_complex xfade=transition=fade:duration=2:offset=5 output.mp4
20806 Pick median pixels from several input videos.
20808 The filter accepts the following options:
20812 Set number of inputs.
20813 Default is 3. Allowed range is from 3 to 255.
20814 If number of inputs is even number, than result will be mean value between two median values.
20817 Set which planes to filter. Default value is @code{15}, by which all planes are processed.
20820 Set median percentile. Default value is @code{0.5}.
20821 Default value of @code{0.5} will pick always median values, while @code{0} will pick
20822 minimum values, and @code{1} maximum values.
20826 Stack video inputs into custom layout.
20828 All streams must be of same pixel format.
20830 The filter accepts the following options:
20834 Set number of input streams. Default is 2.
20837 Specify layout of inputs.
20838 This option requires the desired layout configuration to be explicitly set by the user.
20839 This sets position of each video input in output. Each input
20840 is separated by '|'.
20841 The first number represents the column, and the second number represents the row.
20842 Numbers start at 0 and are separated by '_'. Optionally one can use wX and hX,
20843 where X is video input from which to take width or height.
20844 Multiple values can be used when separated by '+'. In such
20845 case values are summed together.
20847 Note that if inputs are of different sizes gaps may appear, as not all of
20848 the output video frame will be filled. Similarly, videos can overlap each
20849 other if their position doesn't leave enough space for the full frame of
20852 For 2 inputs, a default layout of @code{0_0|w0_0} is set. In all other cases,
20853 a layout must be set by the user.
20856 If set to 1, force the output to terminate when the shortest input
20857 terminates. Default value is 0.
20860 If set to valid color, all unused pixels will be filled with that color.
20861 By default fill is set to none, so it is disabled.
20864 @subsection Examples
20868 Display 4 inputs into 2x2 grid.
20872 input1(0, 0) | input3(w0, 0)
20873 input2(0, h0) | input4(w0, h0)
20877 xstack=inputs=4:layout=0_0|0_h0|w0_0|w0_h0
20880 Note that if inputs are of different sizes, gaps or overlaps may occur.
20883 Display 4 inputs into 1x4 grid.
20890 input4(0, h0+h1+h2)
20894 xstack=inputs=4:layout=0_0|0_h0|0_h0+h1|0_h0+h1+h2
20897 Note that if inputs are of different widths, unused space will appear.
20900 Display 9 inputs into 3x3 grid.
20904 input1(0, 0) | input4(w0, 0) | input7(w0+w3, 0)
20905 input2(0, h0) | input5(w0, h0) | input8(w0+w3, h0)
20906 input3(0, h0+h1) | input6(w0, h0+h1) | input9(w0+w3, h0+h1)
20910 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
20913 Note that if inputs are of different sizes, gaps or overlaps may occur.
20916 Display 16 inputs into 4x4 grid.
20920 input1(0, 0) | input5(w0, 0) | input9 (w0+w4, 0) | input13(w0+w4+w8, 0)
20921 input2(0, h0) | input6(w0, h0) | input10(w0+w4, h0) | input14(w0+w4+w8, h0)
20922 input3(0, h0+h1) | input7(w0, h0+h1) | input11(w0+w4, h0+h1) | input15(w0+w4+w8, h0+h1)
20923 input4(0, h0+h1+h2)| input8(w0, h0+h1+h2)| input12(w0+w4, h0+h1+h2)| input16(w0+w4+w8, h0+h1+h2)
20927 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|
20928 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
20931 Note that if inputs are of different sizes, gaps or overlaps may occur.
20938 Deinterlace the input video ("yadif" means "yet another deinterlacing
20941 It accepts the following parameters:
20947 The interlacing mode to adopt. It accepts one of the following values:
20950 @item 0, send_frame
20951 Output one frame for each frame.
20952 @item 1, send_field
20953 Output one frame for each field.
20954 @item 2, send_frame_nospatial
20955 Like @code{send_frame}, but it skips the spatial interlacing check.
20956 @item 3, send_field_nospatial
20957 Like @code{send_field}, but it skips the spatial interlacing check.
20960 The default value is @code{send_frame}.
20963 The picture field parity assumed for the input interlaced video. It accepts one
20964 of the following values:
20968 Assume the top field is first.
20970 Assume the bottom field is first.
20972 Enable automatic detection of field parity.
20975 The default value is @code{auto}.
20976 If the interlacing is unknown or the decoder does not export this information,
20977 top field first will be assumed.
20980 Specify which frames to deinterlace. Accepts one of the following
20985 Deinterlace all frames.
20986 @item 1, interlaced
20987 Only deinterlace frames marked as interlaced.
20990 The default value is @code{all}.
20993 @section yadif_cuda
20995 Deinterlace the input video using the @ref{yadif} algorithm, but implemented
20996 in CUDA so that it can work as part of a GPU accelerated pipeline with nvdec
20999 It accepts the following parameters:
21005 The interlacing mode to adopt. It accepts one of the following values:
21008 @item 0, send_frame
21009 Output one frame for each frame.
21010 @item 1, send_field
21011 Output one frame for each field.
21012 @item 2, send_frame_nospatial
21013 Like @code{send_frame}, but it skips the spatial interlacing check.
21014 @item 3, send_field_nospatial
21015 Like @code{send_field}, but it skips the spatial interlacing check.
21018 The default value is @code{send_frame}.
21021 The picture field parity assumed for the input interlaced video. It accepts one
21022 of the following values:
21026 Assume the top field is first.
21028 Assume the bottom field is first.
21030 Enable automatic detection of field parity.
21033 The default value is @code{auto}.
21034 If the interlacing is unknown or the decoder does not export this information,
21035 top field first will be assumed.
21038 Specify which frames to deinterlace. Accepts one of the following
21043 Deinterlace all frames.
21044 @item 1, interlaced
21045 Only deinterlace frames marked as interlaced.
21048 The default value is @code{all}.
21053 Apply blur filter while preserving edges ("yaepblur" means "yet another edge preserving blur filter").
21054 The algorithm is described in
21055 "J. S. Lee, Digital image enhancement and noise filtering by use of local statistics, IEEE Trans. Pattern Anal. Mach. Intell. PAMI-2, 1980."
21057 It accepts the following parameters:
21061 Set the window radius. Default value is 3.
21064 Set which planes to filter. Default is only the first plane.
21067 Set blur strength. Default value is 128.
21070 @subsection Commands
21071 This filter supports same @ref{commands} as options.
21075 Apply Zoom & Pan effect.
21077 This filter accepts the following options:
21081 Set the zoom expression. Range is 1-10. Default is 1.
21085 Set the x and y expression. Default is 0.
21088 Set the duration expression in number of frames.
21089 This sets for how many number of frames effect will last for
21090 single input image.
21093 Set the output image size, default is 'hd720'.
21096 Set the output frame rate, default is '25'.
21099 Each expression can contain the following constants:
21118 Output frame count.
21121 The input timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
21123 @item out_time, time, ot
21124 The output timestamp expressed in seconds.
21128 Last calculated 'x' and 'y' position from 'x' and 'y' expression
21129 for current input frame.
21133 'x' and 'y' of last output frame of previous input frame or 0 when there was
21134 not yet such frame (first input frame).
21137 Last calculated zoom from 'z' expression for current input frame.
21140 Last calculated zoom of last output frame of previous input frame.
21143 Number of output frames for current input frame. Calculated from 'd' expression
21144 for each input frame.
21147 number of output frames created for previous input frame
21150 Rational number: input width / input height
21153 sample aspect ratio
21156 display aspect ratio
21160 @subsection Examples
21164 Zoom in up to 1.5x and pan at same time to some spot near center of picture:
21166 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
21170 Zoom in up to 1.5x and pan always at center of picture:
21172 zoompan=z='min(zoom+0.0015,1.5)':d=700:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
21176 Same as above but without pausing:
21178 zoompan=z='min(max(zoom,pzoom)+0.0015,1.5)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
21182 Zoom in 2x into center of picture only for the first second of the input video:
21184 zoompan=z='if(between(in_time,0,1),2,1)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
21191 Scale (resize) the input video, using the z.lib library:
21192 @url{https://github.com/sekrit-twc/zimg}. To enable compilation of this
21193 filter, you need to configure FFmpeg with @code{--enable-libzimg}.
21195 The zscale filter forces the output display aspect ratio to be the same
21196 as the input, by changing the output sample aspect ratio.
21198 If the input image format is different from the format requested by
21199 the next filter, the zscale filter will convert the input to the
21202 @subsection Options
21203 The filter accepts the following options.
21208 Set the output video dimension expression. Default value is the input
21211 If the @var{width} or @var{w} value is 0, the input width is used for
21212 the output. If the @var{height} or @var{h} value is 0, the input height
21213 is used for the output.
21215 If one and only one of the values is -n with n >= 1, the zscale filter
21216 will use a value that maintains the aspect ratio of the input image,
21217 calculated from the other specified dimension. After that it will,
21218 however, make sure that the calculated dimension is divisible by n and
21219 adjust the value if necessary.
21221 If both values are -n with n >= 1, the behavior will be identical to
21222 both values being set to 0 as previously detailed.
21224 See below for the list of accepted constants for use in the dimension
21228 Set the video size. For the syntax of this option, check the
21229 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
21232 Set the dither type.
21234 Possible values are:
21239 @item error_diffusion
21245 Set the resize filter type.
21247 Possible values are:
21257 Default is bilinear.
21260 Set the color range.
21262 Possible values are:
21269 Default is same as input.
21272 Set the color primaries.
21274 Possible values are:
21284 Default is same as input.
21287 Set the transfer characteristics.
21289 Possible values are:
21303 Default is same as input.
21306 Set the colorspace matrix.
21308 Possible value are:
21319 Default is same as input.
21322 Set the input color range.
21324 Possible values are:
21331 Default is same as input.
21333 @item primariesin, pin
21334 Set the input color primaries.
21336 Possible values are:
21346 Default is same as input.
21348 @item transferin, tin
21349 Set the input transfer characteristics.
21351 Possible values are:
21362 Default is same as input.
21364 @item matrixin, min
21365 Set the input colorspace matrix.
21367 Possible value are:
21379 Set the output chroma location.
21381 Possible values are:
21392 @item chromalin, cin
21393 Set the input chroma location.
21395 Possible values are:
21407 Set the nominal peak luminance.
21410 The values of the @option{w} and @option{h} options are expressions
21411 containing the following constants:
21416 The input width and height
21420 These are the same as @var{in_w} and @var{in_h}.
21424 The output (scaled) width and height
21428 These are the same as @var{out_w} and @var{out_h}
21431 The same as @var{iw} / @var{ih}
21434 input sample aspect ratio
21437 The input display aspect ratio. Calculated from @code{(iw / ih) * sar}.
21441 horizontal and vertical input chroma subsample values. For example for the
21442 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
21446 horizontal and vertical output chroma subsample values. For example for the
21447 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
21450 @subsection Commands
21452 This filter supports the following commands:
21456 Set the output video dimension expression.
21457 The command accepts the same syntax of the corresponding option.
21459 If the specified expression is not valid, it is kept at its current
21463 @c man end VIDEO FILTERS
21465 @chapter OpenCL Video Filters
21466 @c man begin OPENCL VIDEO FILTERS
21468 Below is a description of the currently available OpenCL video filters.
21470 To enable compilation of these filters you need to configure FFmpeg with
21471 @code{--enable-opencl}.
21473 Running OpenCL filters requires you to initialize a hardware device and to pass that device to all filters in any filter graph.
21476 @item -init_hw_device opencl[=@var{name}][:@var{device}[,@var{key=value}...]]
21477 Initialise a new hardware device of type @var{opencl} called @var{name}, using the
21478 given device parameters.
21480 @item -filter_hw_device @var{name}
21481 Pass the hardware device called @var{name} to all filters in any filter graph.
21485 For more detailed information see @url{https://www.ffmpeg.org/ffmpeg.html#Advanced-Video-options}
21489 Example of choosing the first device on the second platform and running avgblur_opencl filter with default parameters on it.
21491 -init_hw_device opencl=gpu:1.0 -filter_hw_device gpu -i INPUT -vf "hwupload, avgblur_opencl, hwdownload" OUTPUT
21495 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.
21497 @section avgblur_opencl
21499 Apply average blur filter.
21501 The filter accepts the following options:
21505 Set horizontal radius size.
21506 Range is @code{[1, 1024]} and default value is @code{1}.
21509 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
21512 Set vertical radius size. Range is @code{[1, 1024]} and default value is @code{0}. If zero, @code{sizeX} value will be used.
21515 @subsection Example
21519 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.
21521 -i INPUT -vf "hwupload, avgblur_opencl=3, hwdownload" OUTPUT
21525 @section boxblur_opencl
21527 Apply a boxblur algorithm to the input video.
21529 It accepts the following parameters:
21533 @item luma_radius, lr
21534 @item luma_power, lp
21535 @item chroma_radius, cr
21536 @item chroma_power, cp
21537 @item alpha_radius, ar
21538 @item alpha_power, ap
21542 A description of the accepted options follows.
21545 @item luma_radius, lr
21546 @item chroma_radius, cr
21547 @item alpha_radius, ar
21548 Set an expression for the box radius in pixels used for blurring the
21549 corresponding input plane.
21551 The radius value must be a non-negative number, and must not be
21552 greater than the value of the expression @code{min(w,h)/2} for the
21553 luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma
21556 Default value for @option{luma_radius} is "2". If not specified,
21557 @option{chroma_radius} and @option{alpha_radius} default to the
21558 corresponding value set for @option{luma_radius}.
21560 The expressions can contain the following constants:
21564 The input width and height in pixels.
21568 The input chroma image width and height in pixels.
21572 The horizontal and vertical chroma subsample values. For example, for the
21573 pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1.
21576 @item luma_power, lp
21577 @item chroma_power, cp
21578 @item alpha_power, ap
21579 Specify how many times the boxblur filter is applied to the
21580 corresponding plane.
21582 Default value for @option{luma_power} is 2. If not specified,
21583 @option{chroma_power} and @option{alpha_power} default to the
21584 corresponding value set for @option{luma_power}.
21586 A value of 0 will disable the effect.
21589 @subsection Examples
21591 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.
21595 Apply a boxblur filter with the luma, chroma, and alpha radius
21596 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.
21598 -i INPUT -vf "hwupload, boxblur_opencl=luma_radius=2:luma_power=3, hwdownload" OUTPUT
21599 -i INPUT -vf "hwupload, boxblur_opencl=2:3, hwdownload" OUTPUT
21603 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.
21605 For the luma plane, a 2x2 box radius will be run once.
21607 For the chroma plane, a 4x4 box radius will be run 5 times.
21609 For the alpha plane, a 3x3 box radius will be run 7 times.
21611 -i INPUT -vf "hwupload, boxblur_opencl=2:1:4:5:3:7, hwdownload" OUTPUT
21615 @section colorkey_opencl
21616 RGB colorspace color keying.
21618 The filter accepts the following options:
21622 The color which will be replaced with transparency.
21625 Similarity percentage with the key color.
21627 0.01 matches only the exact key color, while 1.0 matches everything.
21632 0.0 makes pixels either fully transparent, or not transparent at all.
21634 Higher values result in semi-transparent pixels, with a higher transparency
21635 the more similar the pixels color is to the key color.
21638 @subsection Examples
21642 Make every semi-green pixel in the input transparent with some slight blending:
21644 -i INPUT -vf "hwupload, colorkey_opencl=green:0.3:0.1, hwdownload" OUTPUT
21648 @section convolution_opencl
21650 Apply convolution of 3x3, 5x5, 7x7 matrix.
21652 The filter accepts the following options:
21659 Set matrix for each plane.
21660 Matrix is sequence of 9, 25 or 49 signed numbers.
21661 Default value for each plane is @code{0 0 0 0 1 0 0 0 0}.
21667 Set multiplier for calculated value for each plane.
21668 If unset or 0, it will be sum of all matrix elements.
21669 The option value must be a float number greater or equal to @code{0.0}. Default value is @code{1.0}.
21675 Set bias for each plane. This value is added to the result of the multiplication.
21676 Useful for making the overall image brighter or darker.
21677 The option value must be a float number greater or equal to @code{0.0}. Default value is @code{0.0}.
21681 @subsection Examples
21687 -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
21693 -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
21697 Apply edge enhance:
21699 -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
21705 -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
21709 Apply laplacian edge detector which includes diagonals:
21711 -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
21717 -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
21721 @section erosion_opencl
21723 Apply erosion effect to the video.
21725 This filter replaces the pixel by the local(3x3) minimum.
21727 It accepts the following options:
21734 Limit the maximum change for each plane. Range is @code{[0, 65535]} and default value is @code{65535}.
21735 If @code{0}, plane will remain unchanged.
21738 Flag which specifies the pixel to refer to.
21739 Range is @code{[0, 255]} and default value is @code{255}, i.e. all eight pixels are used.
21741 Flags to local 3x3 coordinates region centered on @code{x}:
21750 @subsection Example
21754 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.
21756 -i INPUT -vf "hwupload, erosion_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT
21760 @section deshake_opencl
21761 Feature-point based video stabilization filter.
21763 The filter accepts the following options:
21767 Simulates a tripod by preventing any camera movement whatsoever from the original frame. Defaults to @code{0}.
21770 Whether or not additional debug info should be displayed, both in the processed output and in the console.
21772 Note that in order to see console debug output you will also need to pass @code{-v verbose} to ffmpeg.
21774 Viewing point matches in the output video is only supported for RGB input.
21776 Defaults to @code{0}.
21778 @item adaptive_crop
21779 Whether or not to do a tiny bit of cropping at the borders to cut down on the amount of mirrored pixels.
21781 Defaults to @code{1}.
21783 @item refine_features
21784 Whether or not feature points should be refined at a sub-pixel level.
21786 This can be turned off for a slight performance gain at the cost of precision.
21788 Defaults to @code{1}.
21790 @item smooth_strength
21791 The strength of the smoothing applied to the camera path from @code{0.0} to @code{1.0}.
21793 @code{1.0} is the maximum smoothing strength while values less than that result in less smoothing.
21795 @code{0.0} causes the filter to adaptively choose a smoothing strength on a per-frame basis.
21797 Defaults to @code{0.0}.
21799 @item smooth_window_multiplier
21800 Controls the size of the smoothing window (the number of frames buffered to determine motion information from).
21802 The size of the smoothing window is determined by multiplying the framerate of the video by this number.
21804 Acceptable values range from @code{0.1} to @code{10.0}.
21806 Larger values increase the amount of motion data available for determining how to smooth the camera path,
21807 potentially improving smoothness, but also increase latency and memory usage.
21809 Defaults to @code{2.0}.
21813 @subsection Examples
21817 Stabilize a video with a fixed, medium smoothing strength:
21819 -i INPUT -vf "hwupload, deshake_opencl=smooth_strength=0.5, hwdownload" OUTPUT
21823 Stabilize a video with debugging (both in console and in rendered video):
21825 -i INPUT -filter_complex "[0:v]format=rgba, hwupload, deshake_opencl=debug=1, hwdownload, format=rgba, format=yuv420p" -v verbose OUTPUT
21829 @section dilation_opencl
21831 Apply dilation effect to the video.
21833 This filter replaces the pixel by the local(3x3) maximum.
21835 It accepts the following options:
21842 Limit the maximum change for each plane. Range is @code{[0, 65535]} and default value is @code{65535}.
21843 If @code{0}, plane will remain unchanged.
21846 Flag which specifies the pixel to refer to.
21847 Range is @code{[0, 255]} and default value is @code{255}, i.e. all eight pixels are used.
21849 Flags to local 3x3 coordinates region centered on @code{x}:
21858 @subsection Example
21862 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.
21864 -i INPUT -vf "hwupload, dilation_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT
21868 @section nlmeans_opencl
21870 Non-local Means denoise filter through OpenCL, this filter accepts same options as @ref{nlmeans}.
21872 @section overlay_opencl
21874 Overlay one video on top of another.
21876 It takes two inputs and has one output. The first input is the "main" video on which the second input is overlaid.
21877 This filter requires same memory layout for all the inputs. So, format conversion may be needed.
21879 The filter accepts the following options:
21884 Set the x coordinate of the overlaid video on the main video.
21885 Default value is @code{0}.
21888 Set the y coordinate of the overlaid video on the main video.
21889 Default value is @code{0}.
21893 @subsection Examples
21897 Overlay an image LOGO at the top-left corner of the INPUT video. Both inputs are yuv420p format.
21899 -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuv420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT
21902 The inputs have same memory layout for color channels , the overlay has additional alpha plane, like INPUT is yuv420p, and the LOGO is yuva420p.
21904 -i INPUT -i LOGO -filter_complex "[0:v]hwupload[a], [1:v]format=yuva420p, hwupload[b], [a][b]overlay_opencl, hwdownload" OUTPUT
21909 @section pad_opencl
21911 Add paddings to the input image, and place the original input at the
21912 provided @var{x}, @var{y} coordinates.
21914 It accepts the following options:
21919 Specify an expression for the size of the output image with the
21920 paddings added. If the value for @var{width} or @var{height} is 0, the
21921 corresponding input size is used for the output.
21923 The @var{width} expression can reference the value set by the
21924 @var{height} expression, and vice versa.
21926 The default value of @var{width} and @var{height} is 0.
21930 Specify the offsets to place the input image at within the padded area,
21931 with respect to the top/left border of the output image.
21933 The @var{x} expression can reference the value set by the @var{y}
21934 expression, and vice versa.
21936 The default value of @var{x} and @var{y} is 0.
21938 If @var{x} or @var{y} evaluate to a negative number, they'll be changed
21939 so the input image is centered on the padded area.
21942 Specify the color of the padded area. For the syntax of this option,
21943 check the @ref{color syntax,,"Color" section in the ffmpeg-utils
21944 manual,ffmpeg-utils}.
21947 Pad to an aspect instead to a resolution.
21950 The value for the @var{width}, @var{height}, @var{x}, and @var{y}
21951 options are expressions containing the following constants:
21956 The input video width and height.
21960 These are the same as @var{in_w} and @var{in_h}.
21964 The output width and height (the size of the padded area), as
21965 specified by the @var{width} and @var{height} expressions.
21969 These are the same as @var{out_w} and @var{out_h}.
21973 The x and y offsets as specified by the @var{x} and @var{y}
21974 expressions, or NAN if not yet specified.
21977 same as @var{iw} / @var{ih}
21980 input sample aspect ratio
21983 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
21986 @section prewitt_opencl
21988 Apply the Prewitt operator (@url{https://en.wikipedia.org/wiki/Prewitt_operator}) to input video stream.
21990 The filter accepts the following option:
21994 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
21997 Set value which will be multiplied with filtered result.
21998 Range is @code{[0.0, 65535]} and default value is @code{1.0}.
22001 Set value which will be added to filtered result.
22002 Range is @code{[-65535, 65535]} and default value is @code{0.0}.
22005 @subsection Example
22009 Apply the Prewitt operator with scale set to 2 and delta set to 10.
22011 -i INPUT -vf "hwupload, prewitt_opencl=scale=2:delta=10, hwdownload" OUTPUT
22015 @anchor{program_opencl}
22016 @section program_opencl
22018 Filter video using an OpenCL program.
22023 OpenCL program source file.
22026 Kernel name in program.
22029 Number of inputs to the filter. Defaults to 1.
22032 Size of output frames. Defaults to the same as the first input.
22036 The @code{program_opencl} filter also supports the @ref{framesync} options.
22038 The program source file must contain a kernel function with the given name,
22039 which will be run once for each plane of the output. Each run on a plane
22040 gets enqueued as a separate 2D global NDRange with one work-item for each
22041 pixel to be generated. The global ID offset for each work-item is therefore
22042 the coordinates of a pixel in the destination image.
22044 The kernel function needs to take the following arguments:
22047 Destination image, @var{__write_only image2d_t}.
22049 This image will become the output; the kernel should write all of it.
22051 Frame index, @var{unsigned int}.
22053 This is a counter starting from zero and increasing by one for each frame.
22055 Source images, @var{__read_only image2d_t}.
22057 These are the most recent images on each input. The kernel may read from
22058 them to generate the output, but they can't be written to.
22065 Copy the input to the output (output must be the same size as the input).
22067 __kernel void copy(__write_only image2d_t destination,
22068 unsigned int index,
22069 __read_only image2d_t source)
22071 const sampler_t sampler = CLK_NORMALIZED_COORDS_FALSE;
22073 int2 location = (int2)(get_global_id(0), get_global_id(1));
22075 float4 value = read_imagef(source, sampler, location);
22077 write_imagef(destination, location, value);
22082 Apply a simple transformation, rotating the input by an amount increasing
22083 with the index counter. Pixel values are linearly interpolated by the
22084 sampler, and the output need not have the same dimensions as the input.
22086 __kernel void rotate_image(__write_only image2d_t dst,
22087 unsigned int index,
22088 __read_only image2d_t src)
22090 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
22091 CLK_FILTER_LINEAR);
22093 float angle = (float)index / 100.0f;
22095 float2 dst_dim = convert_float2(get_image_dim(dst));
22096 float2 src_dim = convert_float2(get_image_dim(src));
22098 float2 dst_cen = dst_dim / 2.0f;
22099 float2 src_cen = src_dim / 2.0f;
22101 int2 dst_loc = (int2)(get_global_id(0), get_global_id(1));
22103 float2 dst_pos = convert_float2(dst_loc) - dst_cen;
22105 cos(angle) * dst_pos.x - sin(angle) * dst_pos.y,
22106 sin(angle) * dst_pos.x + cos(angle) * dst_pos.y
22108 src_pos = src_pos * src_dim / dst_dim;
22110 float2 src_loc = src_pos + src_cen;
22112 if (src_loc.x < 0.0f || src_loc.y < 0.0f ||
22113 src_loc.x > src_dim.x || src_loc.y > src_dim.y)
22114 write_imagef(dst, dst_loc, 0.5f);
22116 write_imagef(dst, dst_loc, read_imagef(src, sampler, src_loc));
22121 Blend two inputs together, with the amount of each input used varying
22122 with the index counter.
22124 __kernel void blend_images(__write_only image2d_t dst,
22125 unsigned int index,
22126 __read_only image2d_t src1,
22127 __read_only image2d_t src2)
22129 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
22130 CLK_FILTER_LINEAR);
22132 float blend = (cos((float)index / 50.0f) + 1.0f) / 2.0f;
22134 int2 dst_loc = (int2)(get_global_id(0), get_global_id(1));
22135 int2 src1_loc = dst_loc * get_image_dim(src1) / get_image_dim(dst);
22136 int2 src2_loc = dst_loc * get_image_dim(src2) / get_image_dim(dst);
22138 float4 val1 = read_imagef(src1, sampler, src1_loc);
22139 float4 val2 = read_imagef(src2, sampler, src2_loc);
22141 write_imagef(dst, dst_loc, val1 * blend + val2 * (1.0f - blend));
22147 @section roberts_opencl
22148 Apply the Roberts cross operator (@url{https://en.wikipedia.org/wiki/Roberts_cross}) to input video stream.
22150 The filter accepts the following option:
22154 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
22157 Set value which will be multiplied with filtered result.
22158 Range is @code{[0.0, 65535]} and default value is @code{1.0}.
22161 Set value which will be added to filtered result.
22162 Range is @code{[-65535, 65535]} and default value is @code{0.0}.
22165 @subsection Example
22169 Apply the Roberts cross operator with scale set to 2 and delta set to 10
22171 -i INPUT -vf "hwupload, roberts_opencl=scale=2:delta=10, hwdownload" OUTPUT
22175 @section sobel_opencl
22177 Apply the Sobel operator (@url{https://en.wikipedia.org/wiki/Sobel_operator}) to input video stream.
22179 The filter accepts the following option:
22183 Set which planes to filter. Default value is @code{0xf}, by which all planes are processed.
22186 Set value which will be multiplied with filtered result.
22187 Range is @code{[0.0, 65535]} and default value is @code{1.0}.
22190 Set value which will be added to filtered result.
22191 Range is @code{[-65535, 65535]} and default value is @code{0.0}.
22194 @subsection Example
22198 Apply sobel operator with scale set to 2 and delta set to 10
22200 -i INPUT -vf "hwupload, sobel_opencl=scale=2:delta=10, hwdownload" OUTPUT
22204 @section tonemap_opencl
22206 Perform HDR(PQ/HLG) to SDR conversion with tone-mapping.
22208 It accepts the following parameters:
22212 Specify the tone-mapping operator to be used. Same as tonemap option in @ref{tonemap}.
22215 Tune the tone mapping algorithm. same as param option in @ref{tonemap}.
22218 Apply desaturation for highlights that exceed this level of brightness. The
22219 higher the parameter, the more color information will be preserved. This
22220 setting helps prevent unnaturally blown-out colors for super-highlights, by
22221 (smoothly) turning into white instead. This makes images feel more natural,
22222 at the cost of reducing information about out-of-range colors.
22224 The default value is 0.5, and the algorithm here is a little different from
22225 the cpu version tonemap currently. A setting of 0.0 disables this option.
22228 The tonemapping algorithm parameters is fine-tuned per each scene. And a threshold
22229 is used to detect whether the scene has changed or not. If the distance between
22230 the current frame average brightness and the current running average exceeds
22231 a threshold value, we would re-calculate scene average and peak brightness.
22232 The default value is 0.2.
22235 Specify the output pixel format.
22237 Currently supported formats are:
22244 Set the output color range.
22246 Possible values are:
22252 Default is same as input.
22255 Set the output color primaries.
22257 Possible values are:
22263 Default is same as input.
22266 Set the output transfer characteristics.
22268 Possible values are:
22277 Set the output colorspace matrix.
22279 Possible value are:
22285 Default is same as input.
22289 @subsection Example
22293 Convert HDR(PQ/HLG) video to bt2020-transfer-characteristic p010 format using linear operator.
22295 -i INPUT -vf "format=p010,hwupload,tonemap_opencl=t=bt2020:tonemap=linear:format=p010,hwdownload,format=p010" OUTPUT
22299 @section unsharp_opencl
22301 Sharpen or blur the input video.
22303 It accepts the following parameters:
22306 @item luma_msize_x, lx
22307 Set the luma matrix horizontal size.
22308 Range is @code{[1, 23]} and default value is @code{5}.
22310 @item luma_msize_y, ly
22311 Set the luma matrix vertical size.
22312 Range is @code{[1, 23]} and default value is @code{5}.
22314 @item luma_amount, la
22315 Set the luma effect strength.
22316 Range is @code{[-10, 10]} and default value is @code{1.0}.
22318 Negative values will blur the input video, while positive values will
22319 sharpen it, a value of zero will disable the effect.
22321 @item chroma_msize_x, cx
22322 Set the chroma matrix horizontal size.
22323 Range is @code{[1, 23]} and default value is @code{5}.
22325 @item chroma_msize_y, cy
22326 Set the chroma matrix vertical size.
22327 Range is @code{[1, 23]} and default value is @code{5}.
22329 @item chroma_amount, ca
22330 Set the chroma effect strength.
22331 Range is @code{[-10, 10]} and default value is @code{0.0}.
22333 Negative values will blur the input video, while positive values will
22334 sharpen it, a value of zero will disable the effect.
22338 All parameters are optional and default to the equivalent of the
22339 string '5:5:1.0:5:5:0.0'.
22341 @subsection Examples
22345 Apply strong luma sharpen effect:
22347 -i INPUT -vf "hwupload, unsharp_opencl=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5, hwdownload" OUTPUT
22351 Apply a strong blur of both luma and chroma parameters:
22353 -i INPUT -vf "hwupload, unsharp_opencl=7:7:-2:7:7:-2, hwdownload" OUTPUT
22357 @section xfade_opencl
22359 Cross fade two videos with custom transition effect by using OpenCL.
22361 It accepts the following options:
22365 Set one of possible transition effects.
22369 Select custom transition effect, the actual transition description
22370 will be picked from source and kernel options.
22382 Default transition is fade.
22386 OpenCL program source file for custom transition.
22389 Set name of kernel to use for custom transition from program source file.
22392 Set duration of video transition.
22395 Set time of start of transition relative to first video.
22398 The program source file must contain a kernel function with the given name,
22399 which will be run once for each plane of the output. Each run on a plane
22400 gets enqueued as a separate 2D global NDRange with one work-item for each
22401 pixel to be generated. The global ID offset for each work-item is therefore
22402 the coordinates of a pixel in the destination image.
22404 The kernel function needs to take the following arguments:
22407 Destination image, @var{__write_only image2d_t}.
22409 This image will become the output; the kernel should write all of it.
22412 First Source image, @var{__read_only image2d_t}.
22413 Second Source image, @var{__read_only image2d_t}.
22415 These are the most recent images on each input. The kernel may read from
22416 them to generate the output, but they can't be written to.
22419 Transition progress, @var{float}. This value is always between 0 and 1 inclusive.
22426 Apply dots curtain transition effect:
22428 __kernel void blend_images(__write_only image2d_t dst,
22429 __read_only image2d_t src1,
22430 __read_only image2d_t src2,
22433 const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
22434 CLK_FILTER_LINEAR);
22435 int2 p = (int2)(get_global_id(0), get_global_id(1));
22436 float2 rp = (float2)(get_global_id(0), get_global_id(1));
22437 float2 dim = (float2)(get_image_dim(src1).x, get_image_dim(src1).y);
22440 float2 dots = (float2)(20.0, 20.0);
22441 float2 center = (float2)(0,0);
22444 float4 val1 = read_imagef(src1, sampler, p);
22445 float4 val2 = read_imagef(src2, sampler, p);
22446 bool next = distance(fract(rp * dots, &unused), (float2)(0.5, 0.5)) < (progress / distance(rp, center));
22448 write_imagef(dst, p, next ? val1 : val2);
22454 @c man end OPENCL VIDEO FILTERS
22456 @chapter VAAPI Video Filters
22457 @c man begin VAAPI VIDEO FILTERS
22459 VAAPI Video filters are usually used with VAAPI decoder and VAAPI encoder. Below is a description of VAAPI video filters.
22461 To enable compilation of these filters you need to configure FFmpeg with
22462 @code{--enable-vaapi}.
22464 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}
22466 @section tonemap_vaapi
22468 Perform HDR(High Dynamic Range) to SDR(Standard Dynamic Range) conversion with tone-mapping.
22469 It maps the dynamic range of HDR10 content to the SDR content.
22470 It currently only accepts HDR10 as input.
22472 It accepts the following parameters:
22476 Specify the output pixel format.
22478 Currently supported formats are:
22487 Set the output color primaries.
22489 Default is same as input.
22492 Set the output transfer characteristics.
22497 Set the output colorspace matrix.
22499 Default is same as input.
22503 @subsection Example
22507 Convert HDR(HDR10) video to bt2020-transfer-characteristic p010 format
22509 tonemap_vaapi=format=p010:t=bt2020-10
22513 @c man end VAAPI VIDEO FILTERS
22515 @chapter Video Sources
22516 @c man begin VIDEO SOURCES
22518 Below is a description of the currently available video sources.
22522 Buffer video frames, and make them available to the filter chain.
22524 This source is mainly intended for a programmatic use, in particular
22525 through the interface defined in @file{libavfilter/buffersrc.h}.
22527 It accepts the following parameters:
22532 Specify the size (width and height) of the buffered video frames. For the
22533 syntax of this option, check the
22534 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
22537 The input video width.
22540 The input video height.
22543 A string representing the pixel format of the buffered video frames.
22544 It may be a number corresponding to a pixel format, or a pixel format
22548 Specify the timebase assumed by the timestamps of the buffered frames.
22551 Specify the frame rate expected for the video stream.
22553 @item pixel_aspect, sar
22554 The sample (pixel) aspect ratio of the input video.
22557 This option is deprecated and ignored. Prepend @code{sws_flags=@var{flags};}
22558 to the filtergraph description to specify swscale flags for automatically
22559 inserted scalers. See @ref{Filtergraph syntax}.
22561 @item hw_frames_ctx
22562 When using a hardware pixel format, this should be a reference to an
22563 AVHWFramesContext describing input frames.
22568 buffer=width=320:height=240:pix_fmt=yuv410p:time_base=1/24:sar=1
22571 will instruct the source to accept video frames with size 320x240 and
22572 with format "yuv410p", assuming 1/24 as the timestamps timebase and
22573 square pixels (1:1 sample aspect ratio).
22574 Since the pixel format with name "yuv410p" corresponds to the number 6
22575 (check the enum AVPixelFormat definition in @file{libavutil/pixfmt.h}),
22576 this example corresponds to:
22578 buffer=size=320x240:pixfmt=6:time_base=1/24:pixel_aspect=1/1
22581 Alternatively, the options can be specified as a flat string, but this
22582 syntax is deprecated:
22584 @var{width}:@var{height}:@var{pix_fmt}:@var{time_base.num}:@var{time_base.den}:@var{pixel_aspect.num}:@var{pixel_aspect.den}
22588 Create a pattern generated by an elementary cellular automaton.
22590 The initial state of the cellular automaton can be defined through the
22591 @option{filename} and @option{pattern} options. If such options are
22592 not specified an initial state is created randomly.
22594 At each new frame a new row in the video is filled with the result of
22595 the cellular automaton next generation. The behavior when the whole
22596 frame is filled is defined by the @option{scroll} option.
22598 This source accepts the following options:
22602 Read the initial cellular automaton state, i.e. the starting row, from
22603 the specified file.
22604 In the file, each non-whitespace character is considered an alive
22605 cell, a newline will terminate the row, and further characters in the
22606 file will be ignored.
22609 Read the initial cellular automaton state, i.e. the starting row, from
22610 the specified string.
22612 Each non-whitespace character in the string is considered an alive
22613 cell, a newline will terminate the row, and further characters in the
22614 string will be ignored.
22617 Set the video rate, that is the number of frames generated per second.
22620 @item random_fill_ratio, ratio
22621 Set the random fill ratio for the initial cellular automaton row. It
22622 is a floating point number value ranging from 0 to 1, defaults to
22625 This option is ignored when a file or a pattern is specified.
22627 @item random_seed, seed
22628 Set the seed for filling randomly the initial row, must be an integer
22629 included between 0 and UINT32_MAX. If not specified, or if explicitly
22630 set to -1, the filter will try to use a good random seed on a best
22634 Set the cellular automaton rule, it is a number ranging from 0 to 255.
22635 Default value is 110.
22638 Set the size of the output video. For the syntax of this option, check the
22639 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
22641 If @option{filename} or @option{pattern} is specified, the size is set
22642 by default to the width of the specified initial state row, and the
22643 height is set to @var{width} * PHI.
22645 If @option{size} is set, it must contain the width of the specified
22646 pattern string, and the specified pattern will be centered in the
22649 If a filename or a pattern string is not specified, the size value
22650 defaults to "320x518" (used for a randomly generated initial state).
22653 If set to 1, scroll the output upward when all the rows in the output
22654 have been already filled. If set to 0, the new generated row will be
22655 written over the top row just after the bottom row is filled.
22658 @item start_full, full
22659 If set to 1, completely fill the output with generated rows before
22660 outputting the first frame.
22661 This is the default behavior, for disabling set the value to 0.
22664 If set to 1, stitch the left and right row edges together.
22665 This is the default behavior, for disabling set the value to 0.
22668 @subsection Examples
22672 Read the initial state from @file{pattern}, and specify an output of
22675 cellauto=f=pattern:s=200x400
22679 Generate a random initial row with a width of 200 cells, with a fill
22682 cellauto=ratio=2/3:s=200x200
22686 Create a pattern generated by rule 18 starting by a single alive cell
22687 centered on an initial row with width 100:
22689 cellauto=p=@@:s=100x400:full=0:rule=18
22693 Specify a more elaborated initial pattern:
22695 cellauto=p='@@@@ @@ @@@@':s=100x400:full=0:rule=18
22700 @anchor{coreimagesrc}
22701 @section coreimagesrc
22702 Video source generated on GPU using Apple's CoreImage API on OSX.
22704 This video source is a specialized version of the @ref{coreimage} video filter.
22705 Use a core image generator at the beginning of the applied filterchain to
22706 generate the content.
22708 The coreimagesrc video source accepts the following options:
22710 @item list_generators
22711 List all available generators along with all their respective options as well as
22712 possible minimum and maximum values along with the default values.
22714 list_generators=true
22718 Specify the size of the sourced video. For the syntax of this option, check the
22719 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
22720 The default value is @code{320x240}.
22723 Specify the frame rate of the sourced video, as the number of frames
22724 generated per second. It has to be a string in the format
22725 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
22726 number or a valid video frame rate abbreviation. The default value is
22730 Set the sample aspect ratio of the sourced video.
22733 Set the duration of the sourced video. See
22734 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
22735 for the accepted syntax.
22737 If not specified, or the expressed duration is negative, the video is
22738 supposed to be generated forever.
22741 Additionally, all options of the @ref{coreimage} video filter are accepted.
22742 A complete filterchain can be used for further processing of the
22743 generated input without CPU-HOST transfer. See @ref{coreimage} documentation
22744 and examples for details.
22746 @subsection Examples
22751 Use CIQRCodeGenerator to create a QR code for the FFmpeg homepage,
22752 given as complete and escaped command-line for Apple's standard bash shell:
22754 ffmpeg -f lavfi -i coreimagesrc=s=100x100:filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png
22756 This example is equivalent to the QRCode example of @ref{coreimage} without the
22757 need for a nullsrc video source.
22762 Generate several gradients.
22766 Set frame size. For the syntax of this option, check the @ref{video size syntax,,"Video
22767 size" section in the ffmpeg-utils manual,ffmpeg-utils}. Default value is "640x480".
22770 Set frame rate, expressed as number of frames per second. Default
22773 @item c0, c1, c2, c3, c4, c5, c6, c7
22774 Set 8 colors. Default values for colors is to pick random one.
22776 @item x0, y0, y0, y1
22777 Set gradient line source and destination points. If negative or out of range, random ones
22781 Set number of colors to use at once. Allowed range is from 2 to 8. Default value is 2.
22784 Set seed for picking gradient line points.
22787 Set the duration of the sourced video. See
22788 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
22789 for the accepted syntax.
22791 If not specified, or the expressed duration is negative, the video is
22792 supposed to be generated forever.
22795 Set speed of gradients rotation.
22799 @section mandelbrot
22801 Generate a Mandelbrot set fractal, and progressively zoom towards the
22802 point specified with @var{start_x} and @var{start_y}.
22804 This source accepts the following options:
22809 Set the terminal pts value. Default value is 400.
22812 Set the terminal scale value.
22813 Must be a floating point value. Default value is 0.3.
22816 Set the inner coloring mode, that is the algorithm used to draw the
22817 Mandelbrot fractal internal region.
22819 It shall assume one of the following values:
22824 Show time until convergence.
22826 Set color based on point closest to the origin of the iterations.
22831 Default value is @var{mincol}.
22834 Set the bailout value. Default value is 10.0.
22837 Set the maximum of iterations performed by the rendering
22838 algorithm. Default value is 7189.
22841 Set outer coloring mode.
22842 It shall assume one of following values:
22844 @item iteration_count
22845 Set iteration count mode.
22846 @item normalized_iteration_count
22847 set normalized iteration count mode.
22849 Default value is @var{normalized_iteration_count}.
22852 Set frame rate, expressed as number of frames per second. Default
22856 Set frame size. For the syntax of this option, check the @ref{video size syntax,,"Video
22857 size" section in the ffmpeg-utils manual,ffmpeg-utils}. Default value is "640x480".
22860 Set the initial scale value. Default value is 3.0.
22863 Set the initial x position. Must be a floating point value between
22864 -100 and 100. Default value is -0.743643887037158704752191506114774.
22867 Set the initial y position. Must be a floating point value between
22868 -100 and 100. Default value is -0.131825904205311970493132056385139.
22873 Generate various test patterns, as generated by the MPlayer test filter.
22875 The size of the generated video is fixed, and is 256x256.
22876 This source is useful in particular for testing encoding features.
22878 This source accepts the following options:
22883 Specify the frame rate of the sourced video, as the number of frames
22884 generated per second. It has to be a string in the format
22885 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
22886 number or a valid video frame rate abbreviation. The default value is
22890 Set the duration of the sourced video. See
22891 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
22892 for the accepted syntax.
22894 If not specified, or the expressed duration is negative, the video is
22895 supposed to be generated forever.
22899 Set the number or the name of the test to perform. Supported tests are:
22913 @item max_frames, m
22914 Set the maximum number of frames generated for each test, default value is 30.
22918 Default value is "all", which will cycle through the list of all tests.
22923 mptestsrc=t=dc_luma
22926 will generate a "dc_luma" test pattern.
22928 @section frei0r_src
22930 Provide a frei0r source.
22932 To enable compilation of this filter you need to install the frei0r
22933 header and configure FFmpeg with @code{--enable-frei0r}.
22935 This source accepts the following parameters:
22940 The size of the video to generate. For the syntax of this option, check the
22941 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
22944 The framerate of the generated video. It may be a string of the form
22945 @var{num}/@var{den} or a frame rate abbreviation.
22948 The name to the frei0r source to load. For more information regarding frei0r and
22949 how to set the parameters, read the @ref{frei0r} section in the video filters
22952 @item filter_params
22953 A '|'-separated list of parameters to pass to the frei0r source.
22957 For example, to generate a frei0r partik0l source with size 200x200
22958 and frame rate 10 which is overlaid on the overlay filter main input:
22960 frei0r_src=size=200x200:framerate=10:filter_name=partik0l:filter_params=1234 [overlay]; [in][overlay] overlay
22965 Generate a life pattern.
22967 This source is based on a generalization of John Conway's life game.
22969 The sourced input represents a life grid, each pixel represents a cell
22970 which can be in one of two possible states, alive or dead. Every cell
22971 interacts with its eight neighbours, which are the cells that are
22972 horizontally, vertically, or diagonally adjacent.
22974 At each interaction the grid evolves according to the adopted rule,
22975 which specifies the number of neighbor alive cells which will make a
22976 cell stay alive or born. The @option{rule} option allows one to specify
22979 This source accepts the following options:
22983 Set the file from which to read the initial grid state. In the file,
22984 each non-whitespace character is considered an alive cell, and newline
22985 is used to delimit the end of each row.
22987 If this option is not specified, the initial grid is generated
22991 Set the video rate, that is the number of frames generated per second.
22994 @item random_fill_ratio, ratio
22995 Set the random fill ratio for the initial random grid. It is a
22996 floating point number value ranging from 0 to 1, defaults to 1/PHI.
22997 It is ignored when a file is specified.
22999 @item random_seed, seed
23000 Set the seed for filling the initial random grid, must be an integer
23001 included between 0 and UINT32_MAX. If not specified, or if explicitly
23002 set to -1, the filter will try to use a good random seed on a best
23008 A rule can be specified with a code of the kind "S@var{NS}/B@var{NB}",
23009 where @var{NS} and @var{NB} are sequences of numbers in the range 0-8,
23010 @var{NS} specifies the number of alive neighbor cells which make a
23011 live cell stay alive, and @var{NB} the number of alive neighbor cells
23012 which make a dead cell to become alive (i.e. to "born").
23013 "s" and "b" can be used in place of "S" and "B", respectively.
23015 Alternatively a rule can be specified by an 18-bits integer. The 9
23016 high order bits are used to encode the next cell state if it is alive
23017 for each number of neighbor alive cells, the low order bits specify
23018 the rule for "borning" new cells. Higher order bits encode for an
23019 higher number of neighbor cells.
23020 For example the number 6153 = @code{(12<<9)+9} specifies a stay alive
23021 rule of 12 and a born rule of 9, which corresponds to "S23/B03".
23023 Default value is "S23/B3", which is the original Conway's game of life
23024 rule, and will keep a cell alive if it has 2 or 3 neighbor alive
23025 cells, and will born a new cell if there are three alive cells around
23029 Set the size of the output video. For the syntax of this option, check the
23030 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23032 If @option{filename} is specified, the size is set by default to the
23033 same size of the input file. If @option{size} is set, it must contain
23034 the size specified in the input file, and the initial grid defined in
23035 that file is centered in the larger resulting area.
23037 If a filename is not specified, the size value defaults to "320x240"
23038 (used for a randomly generated initial grid).
23041 If set to 1, stitch the left and right grid edges together, and the
23042 top and bottom edges also. Defaults to 1.
23045 Set cell mold speed. If set, a dead cell will go from @option{death_color} to
23046 @option{mold_color} with a step of @option{mold}. @option{mold} can have a
23047 value from 0 to 255.
23050 Set the color of living (or new born) cells.
23053 Set the color of dead cells. If @option{mold} is set, this is the first color
23054 used to represent a dead cell.
23057 Set mold color, for definitely dead and moldy cells.
23059 For the syntax of these 3 color options, check the @ref{color syntax,,"Color" section in the
23060 ffmpeg-utils manual,ffmpeg-utils}.
23063 @subsection Examples
23067 Read a grid from @file{pattern}, and center it on a grid of size
23070 life=f=pattern:s=300x300
23074 Generate a random grid of size 200x200, with a fill ratio of 2/3:
23076 life=ratio=2/3:s=200x200
23080 Specify a custom rule for evolving a randomly generated grid:
23086 Full example with slow death effect (mold) using @command{ffplay}:
23088 ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16
23095 @anchor{haldclutsrc}
23098 @anchor{pal100bars}
23099 @anchor{rgbtestsrc}
23101 @anchor{smptehdbars}
23104 @anchor{yuvtestsrc}
23105 @section allrgb, allyuv, color, haldclutsrc, nullsrc, pal75bars, pal100bars, rgbtestsrc, smptebars, smptehdbars, testsrc, testsrc2, yuvtestsrc
23107 The @code{allrgb} source returns frames of size 4096x4096 of all rgb colors.
23109 The @code{allyuv} source returns frames of size 4096x4096 of all yuv colors.
23111 The @code{color} source provides an uniformly colored input.
23113 The @code{haldclutsrc} source provides an identity Hald CLUT. See also
23114 @ref{haldclut} filter.
23116 The @code{nullsrc} source returns unprocessed video frames. It is
23117 mainly useful to be employed in analysis / debugging tools, or as the
23118 source for filters which ignore the input data.
23120 The @code{pal75bars} source generates a color bars pattern, based on
23121 EBU PAL recommendations with 75% color levels.
23123 The @code{pal100bars} source generates a color bars pattern, based on
23124 EBU PAL recommendations with 100% color levels.
23126 The @code{rgbtestsrc} source generates an RGB test pattern useful for
23127 detecting RGB vs BGR issues. You should see a red, green and blue
23128 stripe from top to bottom.
23130 The @code{smptebars} source generates a color bars pattern, based on
23131 the SMPTE Engineering Guideline EG 1-1990.
23133 The @code{smptehdbars} source generates a color bars pattern, based on
23134 the SMPTE RP 219-2002.
23136 The @code{testsrc} source generates a test video pattern, showing a
23137 color pattern, a scrolling gradient and a timestamp. This is mainly
23138 intended for testing purposes.
23140 The @code{testsrc2} source is similar to testsrc, but supports more
23141 pixel formats instead of just @code{rgb24}. This allows using it as an
23142 input for other tests without requiring a format conversion.
23144 The @code{yuvtestsrc} source generates an YUV test pattern. You should
23145 see a y, cb and cr stripe from top to bottom.
23147 The sources accept the following parameters:
23152 Specify the level of the Hald CLUT, only available in the @code{haldclutsrc}
23153 source. A level of @code{N} generates a picture of @code{N*N*N} by @code{N*N*N}
23154 pixels to be used as identity matrix for 3D lookup tables. Each component is
23155 coded on a @code{1/(N*N)} scale.
23158 Specify the color of the source, only available in the @code{color}
23159 source. For the syntax of this option, check the
23160 @ref{color syntax,,"Color" section in the ffmpeg-utils manual,ffmpeg-utils}.
23163 Specify the size of the sourced video. For the syntax of this option, check the
23164 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23165 The default value is @code{320x240}.
23167 This option is not available with the @code{allrgb}, @code{allyuv}, and
23168 @code{haldclutsrc} filters.
23171 Specify the frame rate of the sourced video, as the number of frames
23172 generated per second. It has to be a string in the format
23173 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
23174 number or a valid video frame rate abbreviation. The default value is
23178 Set the duration of the sourced video. See
23179 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
23180 for the accepted syntax.
23182 If not specified, or the expressed duration is negative, the video is
23183 supposed to be generated forever.
23185 Since the frame rate is used as time base, all frames including the last one
23186 will have their full duration. If the specified duration is not a multiple
23187 of the frame duration, it will be rounded up.
23190 Set the sample aspect ratio of the sourced video.
23193 Specify the alpha (opacity) of the background, only available in the
23194 @code{testsrc2} source. The value must be between 0 (fully transparent) and
23195 255 (fully opaque, the default).
23198 Set the number of decimals to show in the timestamp, only available in the
23199 @code{testsrc} source.
23201 The displayed timestamp value will correspond to the original
23202 timestamp value multiplied by the power of 10 of the specified
23203 value. Default value is 0.
23206 @subsection Examples
23210 Generate a video with a duration of 5.3 seconds, with size
23211 176x144 and a frame rate of 10 frames per second:
23213 testsrc=duration=5.3:size=qcif:rate=10
23217 The following graph description will generate a red source
23218 with an opacity of 0.2, with size "qcif" and a frame rate of 10
23221 color=c=red@@0.2:s=qcif:r=10
23225 If the input content is to be ignored, @code{nullsrc} can be used. The
23226 following command generates noise in the luminance plane by employing
23227 the @code{geq} filter:
23229 nullsrc=s=256x256, geq=random(1)*255:128:128
23233 @subsection Commands
23235 The @code{color} source supports the following commands:
23239 Set the color of the created image. Accepts the same syntax of the
23240 corresponding @option{color} option.
23245 Generate video using an OpenCL program.
23250 OpenCL program source file.
23253 Kernel name in program.
23256 Size of frames to generate. This must be set.
23259 Pixel format to use for the generated frames. This must be set.
23262 Number of frames generated every second. Default value is '25'.
23266 For details of how the program loading works, see the @ref{program_opencl}
23273 Generate a colour ramp by setting pixel values from the position of the pixel
23274 in the output image. (Note that this will work with all pixel formats, but
23275 the generated output will not be the same.)
23277 __kernel void ramp(__write_only image2d_t dst,
23278 unsigned int index)
23280 int2 loc = (int2)(get_global_id(0), get_global_id(1));
23283 val.xy = val.zw = convert_float2(loc) / convert_float2(get_image_dim(dst));
23285 write_imagef(dst, loc, val);
23290 Generate a Sierpinski carpet pattern, panning by a single pixel each frame.
23292 __kernel void sierpinski_carpet(__write_only image2d_t dst,
23293 unsigned int index)
23295 int2 loc = (int2)(get_global_id(0), get_global_id(1));
23297 float4 value = 0.0f;
23298 int x = loc.x + index;
23299 int y = loc.y + index;
23300 while (x > 0 || y > 0) {
23301 if (x % 3 == 1 && y % 3 == 1) {
23309 write_imagef(dst, loc, value);
23315 @section sierpinski
23317 Generate a Sierpinski carpet/triangle fractal, and randomly pan around.
23319 This source accepts the following options:
23323 Set frame size. For the syntax of this option, check the @ref{video size syntax,,"Video
23324 size" section in the ffmpeg-utils manual,ffmpeg-utils}. Default value is "640x480".
23327 Set frame rate, expressed as number of frames per second. Default
23331 Set seed which is used for random panning.
23334 Set max jump for single pan destination. Allowed range is from 1 to 10000.
23337 Set fractal type, can be default @code{carpet} or @code{triangle}.
23340 @c man end VIDEO SOURCES
23342 @chapter Video Sinks
23343 @c man begin VIDEO SINKS
23345 Below is a description of the currently available video sinks.
23347 @section buffersink
23349 Buffer video frames, and make them available to the end of the filter
23352 This sink is mainly intended for programmatic use, in particular
23353 through the interface defined in @file{libavfilter/buffersink.h}
23354 or the options system.
23356 It accepts a pointer to an AVBufferSinkContext structure, which
23357 defines the incoming buffers' formats, to be passed as the opaque
23358 parameter to @code{avfilter_init_filter} for initialization.
23362 Null video sink: do absolutely nothing with the input video. It is
23363 mainly useful as a template and for use in analysis / debugging
23366 @c man end VIDEO SINKS
23368 @chapter Multimedia Filters
23369 @c man begin MULTIMEDIA FILTERS
23371 Below is a description of the currently available multimedia filters.
23375 Convert input audio to a video output, displaying the audio bit scope.
23377 The filter accepts the following options:
23381 Set frame rate, expressed as number of frames per second. Default
23385 Specify the video size for the output. For the syntax of this option, check the
23386 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23387 Default value is @code{1024x256}.
23390 Specify list of colors separated by space or by '|' which will be used to
23391 draw channels. Unrecognized or missing colors will be replaced
23395 @section adrawgraph
23396 Draw a graph using input audio metadata.
23398 See @ref{drawgraph}
23400 @section agraphmonitor
23402 See @ref{graphmonitor}.
23404 @section ahistogram
23406 Convert input audio to a video output, displaying the volume histogram.
23408 The filter accepts the following options:
23412 Specify how histogram is calculated.
23414 It accepts the following values:
23417 Use single histogram for all channels.
23419 Use separate histogram for each channel.
23421 Default is @code{single}.
23424 Set frame rate, expressed as number of frames per second. Default
23428 Specify the video size for the output. For the syntax of this option, check the
23429 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23430 Default value is @code{hd720}.
23435 It accepts the following values:
23446 reverse logarithmic
23448 Default is @code{log}.
23451 Set amplitude scale.
23453 It accepts the following values:
23460 Default is @code{log}.
23463 Set how much frames to accumulate in histogram.
23464 Default is 1. Setting this to -1 accumulates all frames.
23467 Set histogram ratio of window height.
23470 Set sonogram sliding.
23472 It accepts the following values:
23475 replace old rows with new ones.
23477 scroll from top to bottom.
23479 Default is @code{replace}.
23482 @section aphasemeter
23484 Measures phase of input audio, which is exported as metadata @code{lavfi.aphasemeter.phase},
23485 representing mean phase of current audio frame. A video output can also be produced and is
23486 enabled by default. The audio is passed through as first output.
23488 Audio will be rematrixed to stereo if it has a different channel layout. Phase value is in
23489 range @code{[-1, 1]} where @code{-1} means left and right channels are completely out of phase
23490 and @code{1} means channels are in phase.
23492 The filter accepts the following options, all related to its video output:
23496 Set the output frame rate. Default value is @code{25}.
23499 Set the video size for the output. For the syntax of this option, check the
23500 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23501 Default value is @code{800x400}.
23506 Specify the red, green, blue contrast. Default values are @code{2},
23507 @code{7} and @code{1}.
23508 Allowed range is @code{[0, 255]}.
23511 Set color which will be used for drawing median phase. If color is
23512 @code{none} which is default, no median phase value will be drawn.
23515 Enable video output. Default is enabled.
23518 @subsection phasing detection
23520 The filter also detects out of phase and mono sequences in stereo streams.
23521 It logs the sequence start, end and duration when it lasts longer or as long as the minimum set.
23523 The filter accepts the following options for this detection:
23527 Enable mono and out of phase detection. Default is disabled.
23530 Set phase tolerance for mono detection, in amplitude ratio. Default is @code{0}.
23531 Allowed range is @code{[0, 1]}.
23534 Set angle threshold for out of phase detection, in degree. Default is @code{170}.
23535 Allowed range is @code{[90, 180]}.
23538 Set mono or out of phase duration until notification, expressed in seconds. Default is @code{2}.
23541 @subsection Examples
23545 Complete example with @command{ffmpeg} to detect 1 second of mono with 0.001 phase tolerance:
23547 ffmpeg -i stereo.wav -af aphasemeter=video=0:phasing=1:duration=1:tolerance=0.001 -f null -
23551 @section avectorscope
23553 Convert input audio to a video output, representing the audio vector
23556 The filter is used to measure the difference between channels of stereo
23557 audio stream. A monaural signal, consisting of identical left and right
23558 signal, results in straight vertical line. Any stereo separation is visible
23559 as a deviation from this line, creating a Lissajous figure.
23560 If the straight (or deviation from it) but horizontal line appears this
23561 indicates that the left and right channels are out of phase.
23563 The filter accepts the following options:
23567 Set the vectorscope mode.
23569 Available values are:
23572 Lissajous rotated by 45 degrees.
23575 Same as above but not rotated.
23578 Shape resembling half of circle.
23581 Default value is @samp{lissajous}.
23584 Set the video size for the output. For the syntax of this option, check the
23585 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23586 Default value is @code{400x400}.
23589 Set the output frame rate. Default value is @code{25}.
23595 Specify the red, green, blue and alpha contrast. Default values are @code{40},
23596 @code{160}, @code{80} and @code{255}.
23597 Allowed range is @code{[0, 255]}.
23603 Specify the red, green, blue and alpha fade. Default values are @code{15},
23604 @code{10}, @code{5} and @code{5}.
23605 Allowed range is @code{[0, 255]}.
23608 Set the zoom factor. Default value is @code{1}. Allowed range is @code{[0, 10]}.
23609 Values lower than @var{1} will auto adjust zoom factor to maximal possible value.
23612 Set the vectorscope drawing mode.
23614 Available values are:
23617 Draw dot for each sample.
23620 Draw line between previous and current sample.
23623 Default value is @samp{dot}.
23626 Specify amplitude scale of audio samples.
23628 Available values are:
23644 Swap left channel axis with right channel axis.
23654 Mirror only x axis.
23657 Mirror only y axis.
23665 @subsection Examples
23669 Complete example using @command{ffplay}:
23671 ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
23672 [a] avectorscope=zoom=1.3:rc=2:gc=200:bc=10:rf=1:gf=8:bf=7 [out0]'
23676 @section bench, abench
23678 Benchmark part of a filtergraph.
23680 The filter accepts the following options:
23684 Start or stop a timer.
23686 Available values are:
23689 Get the current time, set it as frame metadata (using the key
23690 @code{lavfi.bench.start_time}), and forward the frame to the next filter.
23693 Get the current time and fetch the @code{lavfi.bench.start_time} metadata from
23694 the input frame metadata to get the time difference. Time difference, average,
23695 maximum and minimum time (respectively @code{t}, @code{avg}, @code{max} and
23696 @code{min}) are then printed. The timestamps are expressed in seconds.
23700 @subsection Examples
23704 Benchmark @ref{selectivecolor} filter:
23706 bench=start,selectivecolor=reds=-.2 .12 -.49,bench=stop
23712 Concatenate audio and video streams, joining them together one after the
23715 The filter works on segments of synchronized video and audio streams. All
23716 segments must have the same number of streams of each type, and that will
23717 also be the number of streams at output.
23719 The filter accepts the following options:
23724 Set the number of segments. Default is 2.
23727 Set the number of output video streams, that is also the number of video
23728 streams in each segment. Default is 1.
23731 Set the number of output audio streams, that is also the number of audio
23732 streams in each segment. Default is 0.
23735 Activate unsafe mode: do not fail if segments have a different format.
23739 The filter has @var{v}+@var{a} outputs: first @var{v} video outputs, then
23740 @var{a} audio outputs.
23742 There are @var{n}x(@var{v}+@var{a}) inputs: first the inputs for the first
23743 segment, in the same order as the outputs, then the inputs for the second
23746 Related streams do not always have exactly the same duration, for various
23747 reasons including codec frame size or sloppy authoring. For that reason,
23748 related synchronized streams (e.g. a video and its audio track) should be
23749 concatenated at once. The concat filter will use the duration of the longest
23750 stream in each segment (except the last one), and if necessary pad shorter
23751 audio streams with silence.
23753 For this filter to work correctly, all segments must start at timestamp 0.
23755 All corresponding streams must have the same parameters in all segments; the
23756 filtering system will automatically select a common pixel format for video
23757 streams, and a common sample format, sample rate and channel layout for
23758 audio streams, but other settings, such as resolution, must be converted
23759 explicitly by the user.
23761 Different frame rates are acceptable but will result in variable frame rate
23762 at output; be sure to configure the output file to handle it.
23764 @subsection Examples
23768 Concatenate an opening, an episode and an ending, all in bilingual version
23769 (video in stream 0, audio in streams 1 and 2):
23771 ffmpeg -i opening.mkv -i episode.mkv -i ending.mkv -filter_complex \
23772 '[0:0] [0:1] [0:2] [1:0] [1:1] [1:2] [2:0] [2:1] [2:2]
23773 concat=n=3:v=1:a=2 [v] [a1] [a2]' \
23774 -map '[v]' -map '[a1]' -map '[a2]' output.mkv
23778 Concatenate two parts, handling audio and video separately, using the
23779 (a)movie sources, and adjusting the resolution:
23781 movie=part1.mp4, scale=512:288 [v1] ; amovie=part1.mp4 [a1] ;
23782 movie=part2.mp4, scale=512:288 [v2] ; amovie=part2.mp4 [a2] ;
23783 [v1] [v2] concat [outv] ; [a1] [a2] concat=v=0:a=1 [outa]
23785 Note that a desync will happen at the stitch if the audio and video streams
23786 do not have exactly the same duration in the first file.
23790 @subsection Commands
23792 This filter supports the following commands:
23795 Close the current segment and step to the next one
23801 EBU R128 scanner filter. This filter takes an audio stream and analyzes its loudness
23802 level. By default, it logs a message at a frequency of 10Hz with the
23803 Momentary loudness (identified by @code{M}), Short-term loudness (@code{S}),
23804 Integrated loudness (@code{I}) and Loudness Range (@code{LRA}).
23806 The filter can only analyze streams which have a sampling rate of 48000 Hz and whose
23807 sample format is double-precision floating point. The input stream will be converted to
23808 this specification, if needed. Users may need to insert aformat and/or aresample filters
23809 after this filter to obtain the original parameters.
23811 The filter also has a video output (see the @var{video} option) with a real
23812 time graph to observe the loudness evolution. The graphic contains the logged
23813 message mentioned above, so it is not printed anymore when this option is set,
23814 unless the verbose logging is set. The main graphing area contains the
23815 short-term loudness (3 seconds of analysis), and the gauge on the right is for
23816 the momentary loudness (400 milliseconds), but can optionally be configured
23817 to instead display short-term loudness (see @var{gauge}).
23819 The green area marks a +/- 1LU target range around the target loudness
23820 (-23LUFS by default, unless modified through @var{target}).
23822 More information about the Loudness Recommendation EBU R128 on
23823 @url{http://tech.ebu.ch/loudness}.
23825 The filter accepts the following options:
23830 Activate the video output. The audio stream is passed unchanged whether this
23831 option is set or no. The video stream will be the first output stream if
23832 activated. Default is @code{0}.
23835 Set the video size. This option is for video only. For the syntax of this
23837 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
23838 Default and minimum resolution is @code{640x480}.
23841 Set the EBU scale meter. Default is @code{9}. Common values are @code{9} and
23842 @code{18}, respectively for EBU scale meter +9 and EBU scale meter +18. Any
23843 other integer value between this range is allowed.
23846 Set metadata injection. If set to @code{1}, the audio input will be segmented
23847 into 100ms output frames, each of them containing various loudness information
23848 in metadata. All the metadata keys are prefixed with @code{lavfi.r128.}.
23850 Default is @code{0}.
23853 Force the frame logging level.
23855 Available values are:
23858 information logging level
23860 verbose logging level
23863 By default, the logging level is set to @var{info}. If the @option{video} or
23864 the @option{metadata} options are set, it switches to @var{verbose}.
23869 Available modes can be cumulated (the option is a @code{flag} type). Possible
23873 Disable any peak mode (default).
23875 Enable sample-peak mode.
23877 Simple peak mode looking for the higher sample value. It logs a message
23878 for sample-peak (identified by @code{SPK}).
23880 Enable true-peak mode.
23882 If enabled, the peak lookup is done on an over-sampled version of the input
23883 stream for better peak accuracy. It logs a message for true-peak.
23884 (identified by @code{TPK}) and true-peak per frame (identified by @code{FTPK}).
23885 This mode requires a build with @code{libswresample}.
23889 Treat mono input files as "dual mono". If a mono file is intended for playback
23890 on a stereo system, its EBU R128 measurement will be perceptually incorrect.
23891 If set to @code{true}, this option will compensate for this effect.
23892 Multi-channel input files are not affected by this option.
23895 Set a specific pan law to be used for the measurement of dual mono files.
23896 This parameter is optional, and has a default value of -3.01dB.
23899 Set a specific target level (in LUFS) used as relative zero in the visualization.
23900 This parameter is optional and has a default value of -23LUFS as specified
23901 by EBU R128. However, material published online may prefer a level of -16LUFS
23902 (e.g. for use with podcasts or video platforms).
23905 Set the value displayed by the gauge. Valid values are @code{momentary} and s
23906 @code{shortterm}. By default the momentary value will be used, but in certain
23907 scenarios it may be more useful to observe the short term value instead (e.g.
23911 Sets the display scale for the loudness. Valid parameters are @code{absolute}
23912 (in LUFS) or @code{relative} (LU) relative to the target. This only affects the
23913 video output, not the summary or continuous log output.
23916 @subsection Examples
23920 Real-time graph using @command{ffplay}, with a EBU scale meter +18:
23922 ffplay -f lavfi -i "amovie=input.mp3,ebur128=video=1:meter=18 [out0][out1]"
23926 Run an analysis with @command{ffmpeg}:
23928 ffmpeg -nostats -i input.mp3 -filter_complex ebur128 -f null -
23932 @section interleave, ainterleave
23934 Temporally interleave frames from several inputs.
23936 @code{interleave} works with video inputs, @code{ainterleave} with audio.
23938 These filters read frames from several inputs and send the oldest
23939 queued frame to the output.
23941 Input streams must have well defined, monotonically increasing frame
23944 In order to submit one frame to output, these filters need to enqueue
23945 at least one frame for each input, so they cannot work in case one
23946 input is not yet terminated and will not receive incoming frames.
23948 For example consider the case when one input is a @code{select} filter
23949 which always drops input frames. The @code{interleave} filter will keep
23950 reading from that input, but it will never be able to send new frames
23951 to output until the input sends an end-of-stream signal.
23953 Also, depending on inputs synchronization, the filters will drop
23954 frames in case one input receives more frames than the other ones, and
23955 the queue is already filled.
23957 These filters accept the following options:
23961 Set the number of different inputs, it is 2 by default.
23964 How to determine the end-of-stream.
23968 The duration of the longest input. (default)
23971 The duration of the shortest input.
23974 The duration of the first input.
23979 @subsection Examples
23983 Interleave frames belonging to different streams using @command{ffmpeg}:
23985 ffmpeg -i bambi.avi -i pr0n.mkv -filter_complex "[0:v][1:v] interleave" out.avi
23989 Add flickering blur effect:
23991 select='if(gt(random(0), 0.2), 1, 2)':n=2 [tmp], boxblur=2:2, [tmp] interleave
23995 @section metadata, ametadata
23997 Manipulate frame metadata.
23999 This filter accepts the following options:
24003 Set mode of operation of the filter.
24005 Can be one of the following:
24009 If both @code{value} and @code{key} is set, select frames
24010 which have such metadata. If only @code{key} is set, select
24011 every frame that has such key in metadata.
24014 Add new metadata @code{key} and @code{value}. If key is already available
24018 Modify value of already present key.
24021 If @code{value} is set, delete only keys that have such value.
24022 Otherwise, delete key. If @code{key} is not set, delete all metadata values in
24026 Print key and its value if metadata was found. If @code{key} is not set print all
24027 metadata values available in frame.
24031 Set key used with all modes. Must be set for all modes except @code{print} and @code{delete}.
24034 Set metadata value which will be used. This option is mandatory for
24035 @code{modify} and @code{add} mode.
24038 Which function to use when comparing metadata value and @code{value}.
24040 Can be one of following:
24044 Values are interpreted as strings, returns true if metadata value is same as @code{value}.
24047 Values are interpreted as strings, returns true if metadata value starts with
24048 the @code{value} option string.
24051 Values are interpreted as floats, returns true if metadata value is less than @code{value}.
24054 Values are interpreted as floats, returns true if @code{value} is equal with metadata value.
24057 Values are interpreted as floats, returns true if metadata value is greater than @code{value}.
24060 Values are interpreted as floats, returns true if expression from option @code{expr}
24064 Values are interpreted as strings, returns true if metadata value ends with
24065 the @code{value} option string.
24069 Set expression which is used when @code{function} is set to @code{expr}.
24070 The expression is evaluated through the eval API and can contain the following
24075 Float representation of @code{value} from metadata key.
24078 Float representation of @code{value} as supplied by user in @code{value} option.
24082 If specified in @code{print} mode, output is written to the named file. Instead of
24083 plain filename any writable url can be specified. Filename ``-'' is a shorthand
24084 for standard output. If @code{file} option is not set, output is written to the log
24085 with AV_LOG_INFO loglevel.
24088 Reduces buffering in print mode when output is written to a URL set using @var{file}.
24092 @subsection Examples
24096 Print all metadata values for frames with key @code{lavfi.signalstats.YDIF} with values
24099 signalstats,metadata=print:key=lavfi.signalstats.YDIF:value=0:function=expr:expr='between(VALUE1,0,1)'
24102 Print silencedetect output to file @file{metadata.txt}.
24104 silencedetect,ametadata=mode=print:file=metadata.txt
24107 Direct all metadata to a pipe with file descriptor 4.
24109 metadata=mode=print:file='pipe\:4'
24113 @section perms, aperms
24115 Set read/write permissions for the output frames.
24117 These filters are mainly aimed at developers to test direct path in the
24118 following filter in the filtergraph.
24120 The filters accept the following options:
24124 Select the permissions mode.
24126 It accepts the following values:
24129 Do nothing. This is the default.
24131 Set all the output frames read-only.
24133 Set all the output frames directly writable.
24135 Make the frame read-only if writable, and writable if read-only.
24137 Set each output frame read-only or writable randomly.
24141 Set the seed for the @var{random} mode, must be an integer included between
24142 @code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to
24143 @code{-1}, the filter will try to use a good random seed on a best effort
24147 Note: in case of auto-inserted filter between the permission filter and the
24148 following one, the permission might not be received as expected in that
24149 following filter. Inserting a @ref{format} or @ref{aformat} filter before the
24150 perms/aperms filter can avoid this problem.
24152 @section realtime, arealtime
24154 Slow down filtering to match real time approximately.
24156 These filters will pause the filtering for a variable amount of time to
24157 match the output rate with the input timestamps.
24158 They are similar to the @option{re} option to @code{ffmpeg}.
24160 They accept the following options:
24164 Time limit for the pauses. Any pause longer than that will be considered
24165 a timestamp discontinuity and reset the timer. Default is 2 seconds.
24167 Speed factor for processing. The value must be a float larger than zero.
24168 Values larger than 1.0 will result in faster than realtime processing,
24169 smaller will slow processing down. The @var{limit} is automatically adapted
24170 accordingly. Default is 1.0.
24172 A processing speed faster than what is possible without these filters cannot
24177 @section select, aselect
24179 Select frames to pass in output.
24181 This filter accepts the following options:
24186 Set expression, which is evaluated for each input frame.
24188 If the expression is evaluated to zero, the frame is discarded.
24190 If the evaluation result is negative or NaN, the frame is sent to the
24191 first output; otherwise it is sent to the output with index
24192 @code{ceil(val)-1}, assuming that the input index starts from 0.
24194 For example a value of @code{1.2} corresponds to the output with index
24195 @code{ceil(1.2)-1 = 2-1 = 1}, that is the second output.
24198 Set the number of outputs. The output to which to send the selected
24199 frame is based on the result of the evaluation. Default value is 1.
24202 The expression can contain the following constants:
24206 The (sequential) number of the filtered frame, starting from 0.
24209 The (sequential) number of the selected frame, starting from 0.
24211 @item prev_selected_n
24212 The sequential number of the last selected frame. It's NAN if undefined.
24215 The timebase of the input timestamps.
24218 The PTS (Presentation TimeStamp) of the filtered video frame,
24219 expressed in @var{TB} units. It's NAN if undefined.
24222 The PTS of the filtered video frame,
24223 expressed in seconds. It's NAN if undefined.
24226 The PTS of the previously filtered video frame. It's NAN if undefined.
24228 @item prev_selected_pts
24229 The PTS of the last previously filtered video frame. It's NAN if undefined.
24231 @item prev_selected_t
24232 The PTS of the last previously selected video frame, expressed in seconds. It's NAN if undefined.
24235 The PTS of the first video frame in the video. It's NAN if undefined.
24238 The time of the first video frame in the video. It's NAN if undefined.
24240 @item pict_type @emph{(video only)}
24241 The type of the filtered frame. It can assume one of the following
24253 @item interlace_type @emph{(video only)}
24254 The frame interlace type. It can assume one of the following values:
24257 The frame is progressive (not interlaced).
24259 The frame is top-field-first.
24261 The frame is bottom-field-first.
24264 @item consumed_sample_n @emph{(audio only)}
24265 the number of selected samples before the current frame
24267 @item samples_n @emph{(audio only)}
24268 the number of samples in the current frame
24270 @item sample_rate @emph{(audio only)}
24271 the input sample rate
24274 This is 1 if the filtered frame is a key-frame, 0 otherwise.
24277 the position in the file of the filtered frame, -1 if the information
24278 is not available (e.g. for synthetic video)
24280 @item scene @emph{(video only)}
24281 value between 0 and 1 to indicate a new scene; a low value reflects a low
24282 probability for the current frame to introduce a new scene, while a higher
24283 value means the current frame is more likely to be one (see the example below)
24285 @item concatdec_select
24286 The concat demuxer can select only part of a concat input file by setting an
24287 inpoint and an outpoint, but the output packets may not be entirely contained
24288 in the selected interval. By using this variable, it is possible to skip frames
24289 generated by the concat demuxer which are not exactly contained in the selected
24292 This works by comparing the frame pts against the @var{lavf.concat.start_time}
24293 and the @var{lavf.concat.duration} packet metadata values which are also
24294 present in the decoded frames.
24296 The @var{concatdec_select} variable is -1 if the frame pts is at least
24297 start_time and either the duration metadata is missing or the frame pts is less
24298 than start_time + duration, 0 otherwise, and NaN if the start_time metadata is
24301 That basically means that an input frame is selected if its pts is within the
24302 interval set by the concat demuxer.
24306 The default value of the select expression is "1".
24308 @subsection Examples
24312 Select all frames in input:
24317 The example above is the same as:
24329 Select only I-frames:
24331 select='eq(pict_type\,I)'
24335 Select one frame every 100:
24337 select='not(mod(n\,100))'
24341 Select only frames contained in the 10-20 time interval:
24343 select=between(t\,10\,20)
24347 Select only I-frames contained in the 10-20 time interval:
24349 select=between(t\,10\,20)*eq(pict_type\,I)
24353 Select frames with a minimum distance of 10 seconds:
24355 select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)'
24359 Use aselect to select only audio frames with samples number > 100:
24361 aselect='gt(samples_n\,100)'
24365 Create a mosaic of the first scenes:
24367 ffmpeg -i video.avi -vf select='gt(scene\,0.4)',scale=160:120,tile -frames:v 1 preview.png
24370 Comparing @var{scene} against a value between 0.3 and 0.5 is generally a sane
24374 Send even and odd frames to separate outputs, and compose them:
24376 select=n=2:e='mod(n, 2)+1' [odd][even]; [odd] pad=h=2*ih [tmp]; [tmp][even] overlay=y=h
24380 Select useful frames from an ffconcat file which is using inpoints and
24381 outpoints but where the source files are not intra frame only.
24383 ffmpeg -copyts -vsync 0 -segment_time_metadata 1 -i input.ffconcat -vf select=concatdec_select -af aselect=concatdec_select output.avi
24387 @section sendcmd, asendcmd
24389 Send commands to filters in the filtergraph.
24391 These filters read commands to be sent to other filters in the
24394 @code{sendcmd} must be inserted between two video filters,
24395 @code{asendcmd} must be inserted between two audio filters, but apart
24396 from that they act the same way.
24398 The specification of commands can be provided in the filter arguments
24399 with the @var{commands} option, or in a file specified by the
24400 @var{filename} option.
24402 These filters accept the following options:
24405 Set the commands to be read and sent to the other filters.
24407 Set the filename of the commands to be read and sent to the other
24411 @subsection Commands syntax
24413 A commands description consists of a sequence of interval
24414 specifications, comprising a list of commands to be executed when a
24415 particular event related to that interval occurs. The occurring event
24416 is typically the current frame time entering or leaving a given time
24419 An interval is specified by the following syntax:
24421 @var{START}[-@var{END}] @var{COMMANDS};
24424 The time interval is specified by the @var{START} and @var{END} times.
24425 @var{END} is optional and defaults to the maximum time.
24427 The current frame time is considered within the specified interval if
24428 it is included in the interval [@var{START}, @var{END}), that is when
24429 the time is greater or equal to @var{START} and is lesser than
24432 @var{COMMANDS} consists of a sequence of one or more command
24433 specifications, separated by ",", relating to that interval. The
24434 syntax of a command specification is given by:
24436 [@var{FLAGS}] @var{TARGET} @var{COMMAND} @var{ARG}
24439 @var{FLAGS} is optional and specifies the type of events relating to
24440 the time interval which enable sending the specified command, and must
24441 be a non-null sequence of identifier flags separated by "+" or "|" and
24442 enclosed between "[" and "]".
24444 The following flags are recognized:
24447 The command is sent when the current frame timestamp enters the
24448 specified interval. In other words, the command is sent when the
24449 previous frame timestamp was not in the given interval, and the
24453 The command is sent when the current frame timestamp leaves the
24454 specified interval. In other words, the command is sent when the
24455 previous frame timestamp was in the given interval, and the
24459 The command @var{ARG} is interpreted as expression and result of
24460 expression is passed as @var{ARG}.
24462 The expression is evaluated through the eval API and can contain the following
24467 Original position in the file of the frame, or undefined if undefined
24468 for the current frame.
24471 The presentation timestamp in input.
24474 The count of the input frame for video or audio, starting from 0.
24477 The time in seconds of the current frame.
24480 The start time in seconds of the current command interval.
24483 The end time in seconds of the current command interval.
24486 The interpolated time of the current command interval, TI = (T - TS) / (TE - TS).
24491 If @var{FLAGS} is not specified, a default value of @code{[enter]} is
24494 @var{TARGET} specifies the target of the command, usually the name of
24495 the filter class or a specific filter instance name.
24497 @var{COMMAND} specifies the name of the command for the target filter.
24499 @var{ARG} is optional and specifies the optional list of argument for
24500 the given @var{COMMAND}.
24502 Between one interval specification and another, whitespaces, or
24503 sequences of characters starting with @code{#} until the end of line,
24504 are ignored and can be used to annotate comments.
24506 A simplified BNF description of the commands specification syntax
24509 @var{COMMAND_FLAG} ::= "enter" | "leave"
24510 @var{COMMAND_FLAGS} ::= @var{COMMAND_FLAG} [(+|"|")@var{COMMAND_FLAG}]
24511 @var{COMMAND} ::= ["[" @var{COMMAND_FLAGS} "]"] @var{TARGET} @var{COMMAND} [@var{ARG}]
24512 @var{COMMANDS} ::= @var{COMMAND} [,@var{COMMANDS}]
24513 @var{INTERVAL} ::= @var{START}[-@var{END}] @var{COMMANDS}
24514 @var{INTERVALS} ::= @var{INTERVAL}[;@var{INTERVALS}]
24517 @subsection Examples
24521 Specify audio tempo change at second 4:
24523 asendcmd=c='4.0 atempo tempo 1.5',atempo
24527 Target a specific filter instance:
24529 asendcmd=c='4.0 atempo@@my tempo 1.5',atempo@@my
24533 Specify a list of drawtext and hue commands in a file.
24535 # show text in the interval 5-10
24536 5.0-10.0 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=hello world',
24537 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=';
24539 # desaturate the image in the interval 15-20
24540 15.0-20.0 [enter] hue s 0,
24541 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=nocolor',
24543 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=color';
24545 # apply an exponential saturation fade-out effect, starting from time 25
24546 25 [enter] hue s exp(25-t)
24549 A filtergraph allowing to read and process the above command list
24550 stored in a file @file{test.cmd}, can be specified with:
24552 sendcmd=f=test.cmd,drawtext=fontfile=FreeSerif.ttf:text='',hue
24557 @section setpts, asetpts
24559 Change the PTS (presentation timestamp) of the input frames.
24561 @code{setpts} works on video frames, @code{asetpts} on audio frames.
24563 This filter accepts the following options:
24568 The expression which is evaluated for each frame to construct its timestamp.
24572 The expression is evaluated through the eval API and can contain the following
24576 @item FRAME_RATE, FR
24577 frame rate, only defined for constant frame-rate video
24580 The presentation timestamp in input
24583 The count of the input frame for video or the number of consumed samples,
24584 not including the current frame for audio, starting from 0.
24586 @item NB_CONSUMED_SAMPLES
24587 The number of consumed samples, not including the current frame (only
24590 @item NB_SAMPLES, S
24591 The number of samples in the current frame (only audio)
24593 @item SAMPLE_RATE, SR
24594 The audio sample rate.
24597 The PTS of the first frame.
24600 the time in seconds of the first frame
24603 State whether the current frame is interlaced.
24606 the time in seconds of the current frame
24609 original position in the file of the frame, or undefined if undefined
24610 for the current frame
24613 The previous input PTS.
24616 previous input time in seconds
24619 The previous output PTS.
24622 previous output time in seconds
24625 The wallclock (RTC) time in microseconds. This is deprecated, use time(0)
24629 The wallclock (RTC) time at the start of the movie in microseconds.
24632 The timebase of the input timestamps.
24636 @subsection Examples
24640 Start counting PTS from zero
24642 setpts=PTS-STARTPTS
24646 Apply fast motion effect:
24652 Apply slow motion effect:
24658 Set fixed rate of 25 frames per second:
24664 Set fixed rate 25 fps with some jitter:
24666 setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
24670 Apply an offset of 10 seconds to the input PTS:
24676 Generate timestamps from a "live source" and rebase onto the current timebase:
24678 setpts='(RTCTIME - RTCSTART) / (TB * 1000000)'
24682 Generate timestamps by counting samples:
24691 Force color range for the output video frame.
24693 The @code{setrange} filter marks the color range property for the
24694 output frames. It does not change the input frame, but only sets the
24695 corresponding property, which affects how the frame is treated by
24698 The filter accepts the following options:
24703 Available values are:
24707 Keep the same color range property.
24709 @item unspecified, unknown
24710 Set the color range as unspecified.
24712 @item limited, tv, mpeg
24713 Set the color range as limited.
24715 @item full, pc, jpeg
24716 Set the color range as full.
24720 @section settb, asettb
24722 Set the timebase to use for the output frames timestamps.
24723 It is mainly useful for testing timebase configuration.
24725 It accepts the following parameters:
24730 The expression which is evaluated into the output timebase.
24734 The value for @option{tb} is an arithmetic expression representing a
24735 rational. The expression can contain the constants "AVTB" (the default
24736 timebase), "intb" (the input timebase) and "sr" (the sample rate,
24737 audio only). Default value is "intb".
24739 @subsection Examples
24743 Set the timebase to 1/25:
24749 Set the timebase to 1/10:
24755 Set the timebase to 1001/1000:
24761 Set the timebase to 2*intb:
24767 Set the default timebase value:
24774 Convert input audio to a video output representing frequency spectrum
24775 logarithmically using Brown-Puckette constant Q transform algorithm with
24776 direct frequency domain coefficient calculation (but the transform itself
24777 is not really constant Q, instead the Q factor is actually variable/clamped),
24778 with musical tone scale, from E0 to D#10.
24780 The filter accepts the following options:
24784 Specify the video size for the output. It must be even. For the syntax of this option,
24785 check the @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
24786 Default value is @code{1920x1080}.
24789 Set the output frame rate. Default value is @code{25}.
24792 Set the bargraph height. It must be even. Default value is @code{-1} which
24793 computes the bargraph height automatically.
24796 Set the axis height. It must be even. Default value is @code{-1} which computes
24797 the axis height automatically.
24800 Set the sonogram height. It must be even. Default value is @code{-1} which
24801 computes the sonogram height automatically.
24804 Set the fullhd resolution. This option is deprecated, use @var{size}, @var{s}
24805 instead. Default value is @code{1}.
24807 @item sono_v, volume
24808 Specify the sonogram volume expression. It can contain variables:
24811 the @var{bar_v} evaluated expression
24812 @item frequency, freq, f
24813 the frequency where it is evaluated
24814 @item timeclamp, tc
24815 the value of @var{timeclamp} option
24819 @item a_weighting(f)
24820 A-weighting of equal loudness
24821 @item b_weighting(f)
24822 B-weighting of equal loudness
24823 @item c_weighting(f)
24824 C-weighting of equal loudness.
24826 Default value is @code{16}.
24828 @item bar_v, volume2
24829 Specify the bargraph volume expression. It can contain variables:
24832 the @var{sono_v} evaluated expression
24833 @item frequency, freq, f
24834 the frequency where it is evaluated
24835 @item timeclamp, tc
24836 the value of @var{timeclamp} option
24840 @item a_weighting(f)
24841 A-weighting of equal loudness
24842 @item b_weighting(f)
24843 B-weighting of equal loudness
24844 @item c_weighting(f)
24845 C-weighting of equal loudness.
24847 Default value is @code{sono_v}.
24849 @item sono_g, gamma
24850 Specify the sonogram gamma. Lower gamma makes the spectrum more contrast,
24851 higher gamma makes the spectrum having more range. Default value is @code{3}.
24852 Acceptable range is @code{[1, 7]}.
24854 @item bar_g, gamma2
24855 Specify the bargraph gamma. Default value is @code{1}. Acceptable range is
24859 Specify the bargraph transparency level. Lower value makes the bargraph sharper.
24860 Default value is @code{1}. Acceptable range is @code{[0, 1]}.
24862 @item timeclamp, tc
24863 Specify the transform timeclamp. At low frequency, there is trade-off between
24864 accuracy in time domain and frequency domain. If timeclamp is lower,
24865 event in time domain is represented more accurately (such as fast bass drum),
24866 otherwise event in frequency domain is represented more accurately
24867 (such as bass guitar). Acceptable range is @code{[0.002, 1]}. Default value is @code{0.17}.
24870 Set attack time in seconds. The default is @code{0} (disabled). Otherwise, it
24871 limits future samples by applying asymmetric windowing in time domain, useful
24872 when low latency is required. Accepted range is @code{[0, 1]}.
24875 Specify the transform base frequency. Default value is @code{20.01523126408007475},
24876 which is frequency 50 cents below E0. Acceptable range is @code{[10, 100000]}.
24879 Specify the transform end frequency. Default value is @code{20495.59681441799654},
24880 which is frequency 50 cents above D#10. Acceptable range is @code{[10, 100000]}.
24883 This option is deprecated and ignored.
24886 Specify the transform length in time domain. Use this option to control accuracy
24887 trade-off between time domain and frequency domain at every frequency sample.
24888 It can contain variables:
24890 @item frequency, freq, f
24891 the frequency where it is evaluated
24892 @item timeclamp, tc
24893 the value of @var{timeclamp} option.
24895 Default value is @code{384*tc/(384+tc*f)}.
24898 Specify the transform count for every video frame. Default value is @code{6}.
24899 Acceptable range is @code{[1, 30]}.
24902 Specify the transform count for every single pixel. Default value is @code{0},
24903 which makes it computed automatically. Acceptable range is @code{[0, 10]}.
24906 Specify font file for use with freetype to draw the axis. If not specified,
24907 use embedded font. Note that drawing with font file or embedded font is not
24908 implemented with custom @var{basefreq} and @var{endfreq}, use @var{axisfile}
24912 Specify fontconfig pattern. This has lower priority than @var{fontfile}. The
24913 @code{:} in the pattern may be replaced by @code{|} to avoid unnecessary
24917 Specify font color expression. This is arithmetic expression that should return
24918 integer value 0xRRGGBB. It can contain variables:
24920 @item frequency, freq, f
24921 the frequency where it is evaluated
24922 @item timeclamp, tc
24923 the value of @var{timeclamp} option
24928 midi number of frequency f, some midi numbers: E0(16), C1(24), C2(36), A4(69)
24929 @item r(x), g(x), b(x)
24930 red, green, and blue value of intensity x.
24932 Default value is @code{st(0, (midi(f)-59.5)/12);
24933 st(1, if(between(ld(0),0,1), 0.5-0.5*cos(2*PI*ld(0)), 0));
24934 r(1-ld(1)) + b(ld(1))}.
24937 Specify image file to draw the axis. This option override @var{fontfile} and
24938 @var{fontcolor} option.
24941 Enable/disable drawing text to the axis. If it is set to @code{0}, drawing to
24942 the axis is disabled, ignoring @var{fontfile} and @var{axisfile} option.
24943 Default value is @code{1}.
24946 Set colorspace. The accepted values are:
24949 Unspecified (default)
24958 BT.470BG or BT.601-6 625
24961 SMPTE-170M or BT.601-6 525
24967 BT.2020 with non-constant luminance
24972 Set spectrogram color scheme. This is list of floating point values with format
24973 @code{left_r|left_g|left_b|right_r|right_g|right_b}.
24974 The default is @code{1|0.5|0|0|0.5|1}.
24978 @subsection Examples
24982 Playing audio while showing the spectrum:
24984 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt [out0]'
24988 Same as above, but with frame rate 30 fps:
24990 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fps=30:count=5 [out0]'
24994 Playing at 1280x720:
24996 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=s=1280x720:count=4 [out0]'
25000 Disable sonogram display:
25006 A1 and its harmonics: A1, A2, (near)E3, A3:
25008 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),
25009 asplit[a][out1]; [a] showcqt [out0]'
25013 Same as above, but with more accuracy in frequency domain:
25015 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),
25016 asplit[a][out1]; [a] showcqt=timeclamp=0.5 [out0]'
25022 bar_v=10:sono_v=bar_v*a_weighting(f)
25026 Custom gamma, now spectrum is linear to the amplitude.
25032 Custom tlength equation:
25034 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)))'
25038 Custom fontcolor and fontfile, C-note is colored green, others are colored blue:
25040 fontcolor='if(mod(floor(midi(f)+0.5),12), 0x0000FF, g(1))':fontfile=myfont.ttf
25044 Custom font using fontconfig:
25046 font='Courier New,Monospace,mono|bold'
25050 Custom frequency range with custom axis using image file:
25052 axisfile=myaxis.png:basefreq=40:endfreq=10000
25058 Convert input audio to video output representing the audio power spectrum.
25059 Audio amplitude is on Y-axis while frequency is on X-axis.
25061 The filter accepts the following options:
25065 Specify size of video. For the syntax of this option, check the
25066 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
25067 Default is @code{1024x512}.
25071 This set how each frequency bin will be represented.
25073 It accepts the following values:
25079 Default is @code{bar}.
25082 Set amplitude scale.
25084 It accepts the following values:
25098 Default is @code{log}.
25101 Set frequency scale.
25103 It accepts the following values:
25112 Reverse logarithmic scale.
25114 Default is @code{lin}.
25117 Set window size. Allowed range is from 16 to 65536.
25119 Default is @code{2048}
25122 Set windowing function.
25124 It accepts the following values:
25147 Default is @code{hanning}.
25150 Set window overlap. In range @code{[0, 1]}. Default is @code{1},
25151 which means optimal overlap for selected window function will be picked.
25154 Set time averaging. Setting this to 0 will display current maximal peaks.
25155 Default is @code{1}, which means time averaging is disabled.
25158 Specify list of colors separated by space or by '|' which will be used to
25159 draw channel frequencies. Unrecognized or missing colors will be replaced
25163 Set channel display mode.
25165 It accepts the following values:
25170 Default is @code{combined}.
25173 Set minimum amplitude used in @code{log} amplitude scaler.
25177 @section showspatial
25179 Convert stereo input audio to a video output, representing the spatial relationship
25180 between two channels.
25182 The filter accepts the following options:
25186 Specify the video size for the output. For the syntax of this option, check the
25187 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
25188 Default value is @code{512x512}.
25191 Set window size. Allowed range is from @var{1024} to @var{65536}. Default size is @var{4096}.
25194 Set window function.
25196 It accepts the following values:
25221 Default value is @code{hann}.
25224 Set ratio of overlap window. Default value is @code{0.5}.
25225 When value is @code{1} overlap is set to recommended size for specific
25226 window function currently used.
25229 @anchor{showspectrum}
25230 @section showspectrum
25232 Convert input audio to a video output, representing the audio frequency
25235 The filter accepts the following options:
25239 Specify the video size for the output. For the syntax of this option, check the
25240 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
25241 Default value is @code{640x512}.
25244 Specify how the spectrum should slide along the window.
25246 It accepts the following values:
25249 the samples start again on the left when they reach the right
25251 the samples scroll from right to left
25253 frames are only produced when the samples reach the right
25255 the samples scroll from left to right
25258 Default value is @code{replace}.
25261 Specify display mode.
25263 It accepts the following values:
25266 all channels are displayed in the same row
25268 all channels are displayed in separate rows
25271 Default value is @samp{combined}.
25274 Specify display color mode.
25276 It accepts the following values:
25279 each channel is displayed in a separate color
25281 each channel is displayed using the same color scheme
25283 each channel is displayed using the rainbow color scheme
25285 each channel is displayed using the moreland color scheme
25287 each channel is displayed using the nebulae color scheme
25289 each channel is displayed using the fire color scheme
25291 each channel is displayed using the fiery color scheme
25293 each channel is displayed using the fruit color scheme
25295 each channel is displayed using the cool color scheme
25297 each channel is displayed using the magma color scheme
25299 each channel is displayed using the green color scheme
25301 each channel is displayed using the viridis color scheme
25303 each channel is displayed using the plasma color scheme
25305 each channel is displayed using the cividis color scheme
25307 each channel is displayed using the terrain color scheme
25310 Default value is @samp{channel}.
25313 Specify scale used for calculating intensity color values.
25315 It accepts the following values:
25320 square root, default
25331 Default value is @samp{sqrt}.
25334 Specify frequency scale.
25336 It accepts the following values:
25344 Default value is @samp{lin}.
25347 Set saturation modifier for displayed colors. Negative values provide
25348 alternative color scheme. @code{0} is no saturation at all.
25349 Saturation must be in [-10.0, 10.0] range.
25350 Default value is @code{1}.
25353 Set window function.
25355 It accepts the following values:
25380 Default value is @code{hann}.
25383 Set orientation of time vs frequency axis. Can be @code{vertical} or
25384 @code{horizontal}. Default is @code{vertical}.
25387 Set ratio of overlap window. Default value is @code{0}.
25388 When value is @code{1} overlap is set to recommended size for specific
25389 window function currently used.
25392 Set scale gain for calculating intensity color values.
25393 Default value is @code{1}.
25396 Set which data to display. Can be @code{magnitude}, default or @code{phase}.
25399 Set color rotation, must be in [-1.0, 1.0] range.
25400 Default value is @code{0}.
25403 Set start frequency from which to display spectrogram. Default is @code{0}.
25406 Set stop frequency to which to display spectrogram. Default is @code{0}.
25409 Set upper frame rate limit. Default is @code{auto}, unlimited.
25412 Draw time and frequency axes and legends. Default is disabled.
25415 The usage is very similar to the showwaves filter; see the examples in that
25418 @subsection Examples
25422 Large window with logarithmic color scaling:
25424 showspectrum=s=1280x480:scale=log
25428 Complete example for a colored and sliding spectrum per channel using @command{ffplay}:
25430 ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
25431 [a] showspectrum=mode=separate:color=intensity:slide=1:scale=cbrt [out0]'
25435 @section showspectrumpic
25437 Convert input audio to a single video frame, representing the audio frequency
25440 The filter accepts the following options:
25444 Specify the video size for the output. For the syntax of this option, check the
25445 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
25446 Default value is @code{4096x2048}.
25449 Specify display mode.
25451 It accepts the following values:
25454 all channels are displayed in the same row
25456 all channels are displayed in separate rows
25458 Default value is @samp{combined}.
25461 Specify display color mode.
25463 It accepts the following values:
25466 each channel is displayed in a separate color
25468 each channel is displayed using the same color scheme
25470 each channel is displayed using the rainbow color scheme
25472 each channel is displayed using the moreland color scheme
25474 each channel is displayed using the nebulae color scheme
25476 each channel is displayed using the fire color scheme
25478 each channel is displayed using the fiery color scheme
25480 each channel is displayed using the fruit color scheme
25482 each channel is displayed using the cool color scheme
25484 each channel is displayed using the magma color scheme
25486 each channel is displayed using the green color scheme
25488 each channel is displayed using the viridis color scheme
25490 each channel is displayed using the plasma color scheme
25492 each channel is displayed using the cividis color scheme
25494 each channel is displayed using the terrain color scheme
25496 Default value is @samp{intensity}.
25499 Specify scale used for calculating intensity color values.
25501 It accepts the following values:
25506 square root, default
25516 Default value is @samp{log}.
25519 Specify frequency scale.
25521 It accepts the following values:
25529 Default value is @samp{lin}.
25532 Set saturation modifier for displayed colors. Negative values provide
25533 alternative color scheme. @code{0} is no saturation at all.
25534 Saturation must be in [-10.0, 10.0] range.
25535 Default value is @code{1}.
25538 Set window function.
25540 It accepts the following values:
25564 Default value is @code{hann}.
25567 Set orientation of time vs frequency axis. Can be @code{vertical} or
25568 @code{horizontal}. Default is @code{vertical}.
25571 Set scale gain for calculating intensity color values.
25572 Default value is @code{1}.
25575 Draw time and frequency axes and legends. Default is enabled.
25578 Set color rotation, must be in [-1.0, 1.0] range.
25579 Default value is @code{0}.
25582 Set start frequency from which to display spectrogram. Default is @code{0}.
25585 Set stop frequency to which to display spectrogram. Default is @code{0}.
25588 @subsection Examples
25592 Extract an audio spectrogram of a whole audio track
25593 in a 1024x1024 picture using @command{ffmpeg}:
25595 ffmpeg -i audio.flac -lavfi showspectrumpic=s=1024x1024 spectrogram.png
25599 @section showvolume
25601 Convert input audio volume to a video output.
25603 The filter accepts the following options:
25610 Set border width, allowed range is [0, 5]. Default is 1.
25613 Set channel width, allowed range is [80, 8192]. Default is 400.
25616 Set channel height, allowed range is [1, 900]. Default is 20.
25619 Set fade, allowed range is [0, 1]. Default is 0.95.
25622 Set volume color expression.
25624 The expression can use the following variables:
25628 Current max volume of channel in dB.
25634 Current channel number, starting from 0.
25638 If set, displays channel names. Default is enabled.
25641 If set, displays volume values. Default is enabled.
25644 Set orientation, can be horizontal: @code{h} or vertical: @code{v},
25645 default is @code{h}.
25648 Set step size, allowed range is [0, 5]. Default is 0, which means
25652 Set background opacity, allowed range is [0, 1]. Default is 0.
25655 Set metering mode, can be peak: @code{p} or rms: @code{r},
25656 default is @code{p}.
25659 Set display scale, can be linear: @code{lin} or log: @code{log},
25660 default is @code{lin}.
25664 If set to > 0., display a line for the max level
25665 in the previous seconds.
25666 default is disabled: @code{0.}
25669 The color of the max line. Use when @code{dm} option is set to > 0.
25670 default is: @code{orange}
25675 Convert input audio to a video output, representing the samples waves.
25677 The filter accepts the following options:
25681 Specify the video size for the output. For the syntax of this option, check the
25682 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
25683 Default value is @code{600x240}.
25688 Available values are:
25691 Draw a point for each sample.
25694 Draw a vertical line for each sample.
25697 Draw a point for each sample and a line between them.
25700 Draw a centered vertical line for each sample.
25703 Default value is @code{point}.
25706 Set the number of samples which are printed on the same column. A
25707 larger value will decrease the frame rate. Must be a positive
25708 integer. This option can be set only if the value for @var{rate}
25709 is not explicitly specified.
25712 Set the (approximate) output frame rate. This is done by setting the
25713 option @var{n}. Default value is "25".
25715 @item split_channels
25716 Set if channels should be drawn separately or overlap. Default value is 0.
25719 Set colors separated by '|' which are going to be used for drawing of each channel.
25722 Set amplitude scale.
25724 Available values are:
25742 Set the draw mode. This is mostly useful to set for high @var{n}.
25744 Available values are:
25747 Scale pixel values for each drawn sample.
25750 Draw every sample directly.
25753 Default value is @code{scale}.
25756 @subsection Examples
25760 Output the input file audio and the corresponding video representation
25763 amovie=a.mp3,asplit[out0],showwaves[out1]
25767 Create a synthetic signal and show it with showwaves, forcing a
25768 frame rate of 30 frames per second:
25770 aevalsrc=sin(1*2*PI*t)*sin(880*2*PI*t):cos(2*PI*200*t),asplit[out0],showwaves=r=30[out1]
25774 @section showwavespic
25776 Convert input audio to a single video frame, representing the samples waves.
25778 The filter accepts the following options:
25782 Specify the video size for the output. For the syntax of this option, check the
25783 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
25784 Default value is @code{600x240}.
25786 @item split_channels
25787 Set if channels should be drawn separately or overlap. Default value is 0.
25790 Set colors separated by '|' which are going to be used for drawing of each channel.
25793 Set amplitude scale.
25795 Available values are:
25815 Available values are:
25818 Scale pixel values for each drawn sample.
25821 Draw every sample directly.
25824 Default value is @code{scale}.
25827 Set the filter mode.
25829 Available values are:
25832 Use average samples values for each drawn sample.
25835 Use peak samples values for each drawn sample.
25838 Default value is @code{average}.
25841 @subsection Examples
25845 Extract a channel split representation of the wave form of a whole audio track
25846 in a 1024x800 picture using @command{ffmpeg}:
25848 ffmpeg -i audio.flac -lavfi showwavespic=split_channels=1:s=1024x800 waveform.png
25852 @section sidedata, asidedata
25854 Delete frame side data, or select frames based on it.
25856 This filter accepts the following options:
25860 Set mode of operation of the filter.
25862 Can be one of the following:
25866 Select every frame with side data of @code{type}.
25869 Delete side data of @code{type}. If @code{type} is not set, delete all side
25875 Set side data type used with all modes. Must be set for @code{select} mode. For
25876 the list of frame side data types, refer to the @code{AVFrameSideDataType} enum
25877 in @file{libavutil/frame.h}. For example, to choose
25878 @code{AV_FRAME_DATA_PANSCAN} side data, you must specify @code{PANSCAN}.
25882 @section spectrumsynth
25884 Synthesize audio from 2 input video spectrums, first input stream represents
25885 magnitude across time and second represents phase across time.
25886 The filter will transform from frequency domain as displayed in videos back
25887 to time domain as presented in audio output.
25889 This filter is primarily created for reversing processed @ref{showspectrum}
25890 filter outputs, but can synthesize sound from other spectrograms too.
25891 But in such case results are going to be poor if the phase data is not
25892 available, because in such cases phase data need to be recreated, usually
25893 it's just recreated from random noise.
25894 For best results use gray only output (@code{channel} color mode in
25895 @ref{showspectrum} filter) and @code{log} scale for magnitude video and
25896 @code{lin} scale for phase video. To produce phase, for 2nd video, use
25897 @code{data} option. Inputs videos should generally use @code{fullframe}
25898 slide mode as that saves resources needed for decoding video.
25900 The filter accepts the following options:
25904 Specify sample rate of output audio, the sample rate of audio from which
25905 spectrum was generated may differ.
25908 Set number of channels represented in input video spectrums.
25911 Set scale which was used when generating magnitude input spectrum.
25912 Can be @code{lin} or @code{log}. Default is @code{log}.
25915 Set slide which was used when generating inputs spectrums.
25916 Can be @code{replace}, @code{scroll}, @code{fullframe} or @code{rscroll}.
25917 Default is @code{fullframe}.
25920 Set window function used for resynthesis.
25923 Set window overlap. In range @code{[0, 1]}. Default is @code{1},
25924 which means optimal overlap for selected window function will be picked.
25927 Set orientation of input videos. Can be @code{vertical} or @code{horizontal}.
25928 Default is @code{vertical}.
25931 @subsection Examples
25935 First create magnitude and phase videos from audio, assuming audio is stereo with 44100 sample rate,
25936 then resynthesize videos back to audio with spectrumsynth:
25938 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
25939 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
25940 ffmpeg -i magnitude.nut -i phase.nut -lavfi spectrumsynth=channels=2:sample_rate=44100:win_func=hann:overlap=0.875:slide=fullframe output.flac
25944 @section split, asplit
25946 Split input into several identical outputs.
25948 @code{asplit} works with audio input, @code{split} with video.
25950 The filter accepts a single parameter which specifies the number of outputs. If
25951 unspecified, it defaults to 2.
25953 @subsection Examples
25957 Create two separate outputs from the same input:
25959 [in] split [out0][out1]
25963 To create 3 or more outputs, you need to specify the number of
25966 [in] asplit=3 [out0][out1][out2]
25970 Create two separate outputs from the same input, one cropped and
25973 [in] split [splitout1][splitout2];
25974 [splitout1] crop=100:100:0:0 [cropout];
25975 [splitout2] pad=200:200:100:100 [padout];
25979 Create 5 copies of the input audio with @command{ffmpeg}:
25981 ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT
25987 Receive commands sent through a libzmq client, and forward them to
25988 filters in the filtergraph.
25990 @code{zmq} and @code{azmq} work as a pass-through filters. @code{zmq}
25991 must be inserted between two video filters, @code{azmq} between two
25992 audio filters. Both are capable to send messages to any filter type.
25994 To enable these filters you need to install the libzmq library and
25995 headers and configure FFmpeg with @code{--enable-libzmq}.
25997 For more information about libzmq see:
25998 @url{http://www.zeromq.org/}
26000 The @code{zmq} and @code{azmq} filters work as a libzmq server, which
26001 receives messages sent through a network interface defined by the
26002 @option{bind_address} (or the abbreviation "@option{b}") option.
26003 Default value of this option is @file{tcp://localhost:5555}. You may
26004 want to alter this value to your needs, but do not forget to escape any
26005 ':' signs (see @ref{filtergraph escaping}).
26007 The received message must be in the form:
26009 @var{TARGET} @var{COMMAND} [@var{ARG}]
26012 @var{TARGET} specifies the target of the command, usually the name of
26013 the filter class or a specific filter instance name. The default
26014 filter instance name uses the pattern @samp{Parsed_<filter_name>_<index>},
26015 but you can override this by using the @samp{filter_name@@id} syntax
26016 (see @ref{Filtergraph syntax}).
26018 @var{COMMAND} specifies the name of the command for the target filter.
26020 @var{ARG} is optional and specifies the optional argument list for the
26021 given @var{COMMAND}.
26023 Upon reception, the message is processed and the corresponding command
26024 is injected into the filtergraph. Depending on the result, the filter
26025 will send a reply to the client, adopting the format:
26027 @var{ERROR_CODE} @var{ERROR_REASON}
26031 @var{MESSAGE} is optional.
26033 @subsection Examples
26035 Look at @file{tools/zmqsend} for an example of a zmq client which can
26036 be used to send commands processed by these filters.
26038 Consider the following filtergraph generated by @command{ffplay}.
26039 In this example the last overlay filter has an instance name. All other
26040 filters will have default instance names.
26043 ffplay -dumpgraph 1 -f lavfi "
26044 color=s=100x100:c=red [l];
26045 color=s=100x100:c=blue [r];
26046 nullsrc=s=200x100, zmq [bg];
26047 [bg][l] overlay [bg+l];
26048 [bg+l][r] overlay@@my=x=100 "
26051 To change the color of the left side of the video, the following
26052 command can be used:
26054 echo Parsed_color_0 c yellow | tools/zmqsend
26057 To change the right side:
26059 echo Parsed_color_1 c pink | tools/zmqsend
26062 To change the position of the right side:
26064 echo overlay@@my x 150 | tools/zmqsend
26068 @c man end MULTIMEDIA FILTERS
26070 @chapter Multimedia Sources
26071 @c man begin MULTIMEDIA SOURCES
26073 Below is a description of the currently available multimedia sources.
26077 This is the same as @ref{movie} source, except it selects an audio
26083 Read audio and/or video stream(s) from a movie container.
26085 It accepts the following parameters:
26089 The name of the resource to read (not necessarily a file; it can also be a
26090 device or a stream accessed through some protocol).
26092 @item format_name, f
26093 Specifies the format assumed for the movie to read, and can be either
26094 the name of a container or an input device. If not specified, the
26095 format is guessed from @var{movie_name} or by probing.
26097 @item seek_point, sp
26098 Specifies the seek point in seconds. The frames will be output
26099 starting from this seek point. The parameter is evaluated with
26100 @code{av_strtod}, so the numerical value may be suffixed by an IS
26101 postfix. The default value is "0".
26104 Specifies the streams to read. Several streams can be specified,
26105 separated by "+". The source will then have as many outputs, in the
26106 same order. The syntax is explained in the @ref{Stream specifiers,,"Stream specifiers"
26107 section in the ffmpeg manual,ffmpeg}. Two special names, "dv" and "da" specify
26108 respectively the default (best suited) video and audio stream. Default
26109 is "dv", or "da" if the filter is called as "amovie".
26111 @item stream_index, si
26112 Specifies the index of the video stream to read. If the value is -1,
26113 the most suitable video stream will be automatically selected. The default
26114 value is "-1". Deprecated. If the filter is called "amovie", it will select
26115 audio instead of video.
26118 Specifies how many times to read the stream in sequence.
26119 If the value is 0, the stream will be looped infinitely.
26120 Default value is "1".
26122 Note that when the movie is looped the source timestamps are not
26123 changed, so it will generate non monotonically increasing timestamps.
26125 @item discontinuity
26126 Specifies the time difference between frames above which the point is
26127 considered a timestamp discontinuity which is removed by adjusting the later
26131 It allows overlaying a second video on top of the main input of
26132 a filtergraph, as shown in this graph:
26134 input -----------> deltapts0 --> overlay --> output
26137 movie --> scale--> deltapts1 -------+
26139 @subsection Examples
26143 Skip 3.2 seconds from the start of the AVI file in.avi, and overlay it
26144 on top of the input labelled "in":
26146 movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [over];
26147 [in] setpts=PTS-STARTPTS [main];
26148 [main][over] overlay=16:16 [out]
26152 Read from a video4linux2 device, and overlay it on top of the input
26155 movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [over];
26156 [in] setpts=PTS-STARTPTS [main];
26157 [main][over] overlay=16:16 [out]
26161 Read the first video stream and the audio stream with id 0x81 from
26162 dvd.vob; the video is connected to the pad named "video" and the audio is
26163 connected to the pad named "audio":
26165 movie=dvd.vob:s=v:0+#0x81 [video] [audio]
26169 @subsection Commands
26171 Both movie and amovie support the following commands:
26174 Perform seek using "av_seek_frame".
26175 The syntax is: seek @var{stream_index}|@var{timestamp}|@var{flags}
26178 @var{stream_index}: If stream_index is -1, a default
26179 stream is selected, and @var{timestamp} is automatically converted
26180 from AV_TIME_BASE units to the stream specific time_base.
26182 @var{timestamp}: Timestamp in AVStream.time_base units
26183 or, if no stream is specified, in AV_TIME_BASE units.
26185 @var{flags}: Flags which select direction and seeking mode.
26189 Get movie duration in AV_TIME_BASE units.
26193 @c man end MULTIMEDIA SOURCES