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{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.
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{LINKLABEL} ::= "[" @var{NAME} "]"
216 @var{LINKLABELS} ::= @var{LINKLABEL} [@var{LINKLABELS}]
217 @var{FILTER_ARGUMENTS} ::= sequence of chars (possibly quoted)
218 @var{FILTER} ::= [@var{LINKLABELS}] @var{NAME} ["=" @var{FILTER_ARGUMENTS}] [@var{LINKLABELS}]
219 @var{FILTERCHAIN} ::= @var{FILTER} [,@var{FILTERCHAIN}]
220 @var{FILTERGRAPH} ::= [sws_flags=@var{flags};] @var{FILTERCHAIN} [;@var{FILTERGRAPH}]
223 @section Notes on filtergraph escaping
225 Filtergraph description composition entails several levels of
226 escaping. See @ref{quoting_and_escaping,,the "Quoting and escaping"
227 section in the ffmpeg-utils(1) manual,ffmpeg-utils} for more
228 information about the employed escaping procedure.
230 A first level escaping affects the content of each filter option
231 value, which may contain the special character @code{:} used to
232 separate values, or one of the escaping characters @code{\'}.
234 A second level escaping affects the whole filter description, which
235 may contain the escaping characters @code{\'} or the special
236 characters @code{[],;} used by the filtergraph description.
238 Finally, when you specify a filtergraph on a shell commandline, you
239 need to perform a third level escaping for the shell special
240 characters contained within it.
242 For example, consider the following string to be embedded in
243 the @ref{drawtext} filter description @option{text} value:
245 this is a 'string': may contain one, or more, special characters
248 This string contains the @code{'} special escaping character, and the
249 @code{:} special character, so it needs to be escaped in this way:
251 text=this is a \'string\'\: may contain one, or more, special characters
254 A second level of escaping is required when embedding the filter
255 description in a filtergraph description, in order to escape all the
256 filtergraph special characters. Thus the example above becomes:
258 drawtext=text=this is a \\\'string\\\'\\: may contain one\, or more\, special characters
260 (note that in addition to the @code{\'} escaping special characters,
261 also @code{,} needs to be escaped).
263 Finally an additional level of escaping is needed when writing the
264 filtergraph description in a shell command, which depends on the
265 escaping rules of the adopted shell. For example, assuming that
266 @code{\} is special and needs to be escaped with another @code{\}, the
267 previous string will finally result in:
269 -vf "drawtext=text=this is a \\\\\\'string\\\\\\'\\\\: may contain one\\, or more\\, special characters"
272 @chapter Timeline editing
274 Some filters support a generic @option{enable} option. For the filters
275 supporting timeline editing, this option can be set to an expression which is
276 evaluated before sending a frame to the filter. If the evaluation is non-zero,
277 the filter will be enabled, otherwise the frame will be sent unchanged to the
278 next filter in the filtergraph.
280 The expression accepts the following values:
283 timestamp expressed in seconds, NAN if the input timestamp is unknown
286 sequential number of the input frame, starting from 0
289 the position in the file of the input frame, NAN if unknown
293 width and height of the input frame if video
296 Additionally, these filters support an @option{enable} command that can be used
297 to re-define the expression.
299 Like any other filtering option, the @option{enable} option follows the same
302 For example, to enable a blur filter (@ref{smartblur}) from 10 seconds to 3
303 minutes, and a @ref{curves} filter starting at 3 seconds:
305 smartblur = enable='between(t,10,3*60)',
306 curves = enable='gte(t,3)' : preset=cross_process
309 See @code{ffmpeg -filters} to view which filters have timeline support.
311 @c man end FILTERGRAPH DESCRIPTION
313 @chapter Audio Filters
314 @c man begin AUDIO FILTERS
316 When you configure your FFmpeg build, you can disable any of the
317 existing filters using @code{--disable-filters}.
318 The configure output will show the audio filters included in your
321 Below is a description of the currently available audio filters.
325 A compressor is mainly used to reduce the dynamic range of a signal.
326 Especially modern music is mostly compressed at a high ratio to
327 improve the overall loudness. It's done to get the highest attention
328 of a listener, "fatten" the sound and bring more "power" to the track.
329 If a signal is compressed too much it may sound dull or "dead"
330 afterwards or it may start to "pump" (which could be a powerful effect
331 but can also destroy a track completely).
332 The right compression is the key to reach a professional sound and is
333 the high art of mixing and mastering. Because of its complex settings
334 it may take a long time to get the right feeling for this kind of effect.
336 Compression is done by detecting the volume above a chosen level
337 @code{threshold} and dividing it by the factor set with @code{ratio}.
338 So if you set the threshold to -12dB and your signal reaches -6dB a ratio
339 of 2:1 will result in a signal at -9dB. Because an exact manipulation of
340 the signal would cause distortion of the waveform the reduction can be
341 levelled over the time. This is done by setting "Attack" and "Release".
342 @code{attack} determines how long the signal has to rise above the threshold
343 before any reduction will occur and @code{release} sets the time the signal
344 has to fall below the threshold to reduce the reduction again. Shorter signals
345 than the chosen attack time will be left untouched.
346 The overall reduction of the signal can be made up afterwards with the
347 @code{makeup} setting. So compressing the peaks of a signal about 6dB and
348 raising the makeup to this level results in a signal twice as loud than the
349 source. To gain a softer entry in the compression the @code{knee} flattens the
350 hard edge at the threshold in the range of the chosen decibels.
352 The filter accepts the following options:
356 Set input gain. Default is 1. Range is between 0.015625 and 64.
359 If a signal of second stream rises above this level it will affect the gain
360 reduction of the first stream.
361 By default it is 0.125. Range is between 0.00097563 and 1.
364 Set a ratio by which the signal is reduced. 1:2 means that if the level
365 rose 4dB above the threshold, it will be only 2dB above after the reduction.
366 Default is 2. Range is between 1 and 20.
369 Amount of milliseconds the signal has to rise above the threshold before gain
370 reduction starts. Default is 20. Range is between 0.01 and 2000.
373 Amount of milliseconds the signal has to fall below the threshold before
374 reduction is decreased again. Default is 250. Range is between 0.01 and 9000.
377 Set the amount by how much signal will be amplified after processing.
378 Default is 2. Range is from 1 and 64.
381 Curve the sharp knee around the threshold to enter gain reduction more softly.
382 Default is 2.82843. Range is between 1 and 8.
385 Choose if the @code{average} level between all channels of input stream
386 or the louder(@code{maximum}) channel of input stream affects the
387 reduction. Default is @code{average}.
390 Should the exact signal be taken in case of @code{peak} or an RMS one in case
391 of @code{rms}. Default is @code{rms} which is mostly smoother.
394 How much to use compressed signal in output. Default is 1.
395 Range is between 0 and 1.
400 Copy the input audio source unchanged to the output. This is mainly useful for
405 Apply cross fade from one input audio stream to another input audio stream.
406 The cross fade is applied for specified duration near the end of first stream.
408 The filter accepts the following options:
412 Specify the number of samples for which the cross fade effect has to last.
413 At the end of the cross fade effect the first input audio will be completely
414 silent. Default is 44100.
417 Specify the duration of the cross fade effect. See
418 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
419 for the accepted syntax.
420 By default the duration is determined by @var{nb_samples}.
421 If set this option is used instead of @var{nb_samples}.
424 Should first stream end overlap with second stream start. Default is enabled.
427 Set curve for cross fade transition for first stream.
430 Set curve for cross fade transition for second stream.
432 For description of available curve types see @ref{afade} filter description.
439 Cross fade from one input to another:
441 ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:c1=exp:c2=exp output.flac
445 Cross fade from one input to another but without overlapping:
447 ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:o=0:c1=exp:c2=exp output.flac
453 Reduce audio bit resolution.
455 This filter is bit crusher with enhanced functionality. A bit crusher
456 is used to audibly reduce number of bits an audio signal is sampled
457 with. This doesn't change the bit depth at all, it just produces the
458 effect. Material reduced in bit depth sounds more harsh and "digital".
459 This filter is able to even round to continuous values instead of discrete
461 Additionally it has a D/C offset which results in different crushing of
462 the lower and the upper half of the signal.
463 An Anti-Aliasing setting is able to produce "softer" crushing sounds.
465 Another feature of this filter is the logarithmic mode.
466 This setting switches from linear distances between bits to logarithmic ones.
467 The result is a much more "natural" sounding crusher which doesn't gate low
468 signals for example. The human ear has a logarithmic perception, too
469 so this kind of crushing is much more pleasant.
470 Logarithmic crushing is also able to get anti-aliased.
472 The filter accepts the following options:
488 Can be linear: @code{lin} or logarithmic: @code{log}.
497 Set sample reduction.
500 Enable LFO. By default disabled.
511 Delay one or more audio channels.
513 Samples in delayed channel are filled with silence.
515 The filter accepts the following option:
519 Set list of delays in milliseconds for each channel separated by '|'.
520 At least one delay greater than 0 should be provided.
521 Unused delays will be silently ignored. If number of given delays is
522 smaller than number of channels all remaining channels will not be delayed.
523 If you want to delay exact number of samples, append 'S' to number.
530 Delay first channel by 1.5 seconds, the third channel by 0.5 seconds and leave
531 the second channel (and any other channels that may be present) unchanged.
537 Delay second channel by 500 samples, the third channel by 700 samples and leave
538 the first channel (and any other channels that may be present) unchanged.
546 Apply echoing to the input audio.
548 Echoes are reflected sound and can occur naturally amongst mountains
549 (and sometimes large buildings) when talking or shouting; digital echo
550 effects emulate this behaviour and are often used to help fill out the
551 sound of a single instrument or vocal. The time difference between the
552 original signal and the reflection is the @code{delay}, and the
553 loudness of the reflected signal is the @code{decay}.
554 Multiple echoes can have different delays and decays.
556 A description of the accepted parameters follows.
560 Set input gain of reflected signal. Default is @code{0.6}.
563 Set output gain of reflected signal. Default is @code{0.3}.
566 Set list of time intervals in milliseconds between original signal and reflections
567 separated by '|'. Allowed range for each @code{delay} is @code{(0 - 90000.0]}.
568 Default is @code{1000}.
571 Set list of loudnesses of reflected signals separated by '|'.
572 Allowed range for each @code{decay} is @code{(0 - 1.0]}.
573 Default is @code{0.5}.
580 Make it sound as if there are twice as many instruments as are actually playing:
582 aecho=0.8:0.88:60:0.4
586 If delay is very short, then it sound like a (metallic) robot playing music:
592 A longer delay will sound like an open air concert in the mountains:
594 aecho=0.8:0.9:1000:0.3
598 Same as above but with one more mountain:
600 aecho=0.8:0.9:1000|1800:0.3|0.25
605 Audio emphasis filter creates or restores material directly taken from LPs or
606 emphased CDs with different filter curves. E.g. to store music on vinyl the
607 signal has to be altered by a filter first to even out the disadvantages of
608 this recording medium.
609 Once the material is played back the inverse filter has to be applied to
610 restore the distortion of the frequency response.
612 The filter accepts the following options:
622 Set filter mode. For restoring material use @code{reproduction} mode, otherwise
623 use @code{production} mode. Default is @code{reproduction} mode.
626 Set filter type. Selects medium. Can be one of the following:
638 select Compact Disc (CD).
644 select 50µs (FM-KF).
646 select 75µs (FM-KF).
652 Modify an audio signal according to the specified expressions.
654 This filter accepts one or more expressions (one for each channel),
655 which are evaluated and used to modify a corresponding audio signal.
657 It accepts the following parameters:
661 Set the '|'-separated expressions list for each separate channel. If
662 the number of input channels is greater than the number of
663 expressions, the last specified expression is used for the remaining
666 @item channel_layout, c
667 Set output channel layout. If not specified, the channel layout is
668 specified by the number of expressions. If set to @samp{same}, it will
669 use by default the same input channel layout.
672 Each expression in @var{exprs} can contain the following constants and functions:
676 channel number of the current expression
679 number of the evaluated sample, starting from 0
685 time of the evaluated sample expressed in seconds
688 @item nb_out_channels
689 input and output number of channels
692 the value of input channel with number @var{CH}
695 Note: this filter is slow. For faster processing you should use a
704 aeval=val(ch)/2:c=same
708 Invert phase of the second channel:
717 Apply fade-in/out effect to input audio.
719 A description of the accepted parameters follows.
723 Specify the effect type, can be either @code{in} for fade-in, or
724 @code{out} for a fade-out effect. Default is @code{in}.
726 @item start_sample, ss
727 Specify the number of the start sample for starting to apply the fade
728 effect. Default is 0.
731 Specify the number of samples for which the fade effect has to last. At
732 the end of the fade-in effect the output audio will have the same
733 volume as the input audio, at the end of the fade-out transition
734 the output audio will be silence. Default is 44100.
737 Specify the start time of the fade effect. Default is 0.
738 The value must be specified as a time duration; see
739 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
740 for the accepted syntax.
741 If set this option is used instead of @var{start_sample}.
744 Specify the duration of the fade effect. See
745 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
746 for the accepted syntax.
747 At the end of the fade-in effect the output audio will have the same
748 volume as the input audio, at the end of the fade-out transition
749 the output audio will be silence.
750 By default the duration is determined by @var{nb_samples}.
751 If set this option is used instead of @var{nb_samples}.
754 Set curve for fade transition.
756 It accepts the following values:
759 select triangular, linear slope (default)
761 select quarter of sine wave
763 select half of sine wave
765 select exponential sine wave
769 select inverted parabola
783 select inverted quarter of sine wave
785 select inverted half of sine wave
787 select double-exponential seat
789 select double-exponential sigmoid
797 Fade in first 15 seconds of audio:
803 Fade out last 25 seconds of a 900 seconds audio:
805 afade=t=out:st=875:d=25
810 Apply arbitrary expressions to samples in frequency domain.
814 Set frequency domain real expression for each separate channel separated
815 by '|'. Default is "1".
816 If the number of input channels is greater than the number of
817 expressions, the last specified expression is used for the remaining
821 Set frequency domain imaginary expression for each separate channel
822 separated by '|'. If not set, @var{real} option is used.
824 Each expression in @var{real} and @var{imag} can contain the following
832 current frequency bin number
835 number of available bins
838 channel number of the current expression
850 It accepts the following values:
866 Default is @code{w4096}
869 Set window function. Default is @code{hann}.
872 Set window overlap. If set to 1, the recommended overlap for selected
873 window function will be picked. Default is @code{0.75}.
880 Leave almost only low frequencies in audio:
882 afftfilt="1-clip((b/nb)*b,0,1)"
888 Apply an arbitrary Frequency Impulse Response filter.
890 This filter is designed for applying long FIR filters,
891 up to 30 seconds long.
893 It can be used as component for digital crossover filters,
894 room equalization, cross talk cancellation, wavefield synthesis,
895 auralization, ambiophonics and ambisonics.
897 This filter uses second stream as FIR coefficients.
898 If second stream holds single channel, it will be used
899 for all input channels in first stream, otherwise
900 number of channels in second stream must be same as
901 number of channels in first stream.
903 It accepts the following parameters:
907 Set dry gain. This sets input gain.
910 Set wet gain. This sets final output gain.
913 Set Impulse Response filter length. Default is 1, which means whole IR is processed.
916 Enable applying gain measured from power of IR.
923 Apply reverb to stream using mono IR file as second input, complete command using ffmpeg:
925 ffmpeg -i input.wav -i middle_tunnel_1way_mono.wav -lavfi afir output.wav
932 Set output format constraints for the input audio. The framework will
933 negotiate the most appropriate format to minimize conversions.
935 It accepts the following parameters:
939 A '|'-separated list of requested sample formats.
942 A '|'-separated list of requested sample rates.
944 @item channel_layouts
945 A '|'-separated list of requested channel layouts.
947 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
948 for the required syntax.
951 If a parameter is omitted, all values are allowed.
953 Force the output to either unsigned 8-bit or signed 16-bit stereo
955 aformat=sample_fmts=u8|s16:channel_layouts=stereo
960 A gate is mainly used to reduce lower parts of a signal. This kind of signal
961 processing reduces disturbing noise between useful signals.
963 Gating is done by detecting the volume below a chosen level @var{threshold}
964 and dividing it by the factor set with @var{ratio}. The bottom of the noise
965 floor is set via @var{range}. Because an exact manipulation of the signal
966 would cause distortion of the waveform the reduction can be levelled over
967 time. This is done by setting @var{attack} and @var{release}.
969 @var{attack} determines how long the signal has to fall below the threshold
970 before any reduction will occur and @var{release} sets the time the signal
971 has to rise above the threshold to reduce the reduction again.
972 Shorter signals than the chosen attack time will be left untouched.
976 Set input level before filtering.
977 Default is 1. Allowed range is from 0.015625 to 64.
980 Set the level of gain reduction when the signal is below the threshold.
981 Default is 0.06125. Allowed range is from 0 to 1.
984 If a signal rises above this level the gain reduction is released.
985 Default is 0.125. Allowed range is from 0 to 1.
988 Set a ratio by which the signal is reduced.
989 Default is 2. Allowed range is from 1 to 9000.
992 Amount of milliseconds the signal has to rise above the threshold before gain
994 Default is 20 milliseconds. Allowed range is from 0.01 to 9000.
997 Amount of milliseconds the signal has to fall below the threshold before the
998 reduction is increased again. Default is 250 milliseconds.
999 Allowed range is from 0.01 to 9000.
1002 Set amount of amplification of signal after processing.
1003 Default is 1. Allowed range is from 1 to 64.
1006 Curve the sharp knee around the threshold to enter gain reduction more softly.
1007 Default is 2.828427125. Allowed range is from 1 to 8.
1010 Choose if exact signal should be taken for detection or an RMS like one.
1011 Default is @code{rms}. Can be @code{peak} or @code{rms}.
1014 Choose if the average level between all channels or the louder channel affects
1016 Default is @code{average}. Can be @code{average} or @code{maximum}.
1021 The limiter prevents an input signal from rising over a desired threshold.
1022 This limiter uses lookahead technology to prevent your signal from distorting.
1023 It means that there is a small delay after the signal is processed. Keep in mind
1024 that the delay it produces is the attack time you set.
1026 The filter accepts the following options:
1030 Set input gain. Default is 1.
1033 Set output gain. Default is 1.
1036 Don't let signals above this level pass the limiter. Default is 1.
1039 The limiter will reach its attenuation level in this amount of time in
1040 milliseconds. Default is 5 milliseconds.
1043 Come back from limiting to attenuation 1.0 in this amount of milliseconds.
1044 Default is 50 milliseconds.
1047 When gain reduction is always needed ASC takes care of releasing to an
1048 average reduction level rather than reaching a reduction of 0 in the release
1052 Select how much the release time is affected by ASC, 0 means nearly no changes
1053 in release time while 1 produces higher release times.
1056 Auto level output signal. Default is enabled.
1057 This normalizes audio back to 0dB if enabled.
1060 Depending on picked setting it is recommended to upsample input 2x or 4x times
1061 with @ref{aresample} before applying this filter.
1065 Apply a two-pole all-pass filter with central frequency (in Hz)
1066 @var{frequency}, and filter-width @var{width}.
1067 An all-pass filter changes the audio's frequency to phase relationship
1068 without changing its frequency to amplitude relationship.
1070 The filter accepts the following options:
1074 Set frequency in Hz.
1077 Set method to specify band-width of filter.
1090 Specify the band-width of a filter in width_type units.
1093 Specify which channels to filter, by default all available are filtered.
1100 The filter accepts the following options:
1104 Set the number of loops.
1107 Set maximal number of samples.
1110 Set first sample of loop.
1116 Merge two or more audio streams into a single multi-channel stream.
1118 The filter accepts the following options:
1123 Set the number of inputs. Default is 2.
1127 If the channel layouts of the inputs are disjoint, and therefore compatible,
1128 the channel layout of the output will be set accordingly and the channels
1129 will be reordered as necessary. If the channel layouts of the inputs are not
1130 disjoint, the output will have all the channels of the first input then all
1131 the channels of the second input, in that order, and the channel layout of
1132 the output will be the default value corresponding to the total number of
1135 For example, if the first input is in 2.1 (FL+FR+LF) and the second input
1136 is FC+BL+BR, then the output will be in 5.1, with the channels in the
1137 following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the
1138 first input, b1 is the first channel of the second input).
1140 On the other hand, if both input are in stereo, the output channels will be
1141 in the default order: a1, a2, b1, b2, and the channel layout will be
1142 arbitrarily set to 4.0, which may or may not be the expected value.
1144 All inputs must have the same sample rate, and format.
1146 If inputs do not have the same duration, the output will stop with the
1149 @subsection Examples
1153 Merge two mono files into a stereo stream:
1155 amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge
1159 Multiple merges assuming 1 video stream and 6 audio streams in @file{input.mkv}:
1161 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
1167 Mixes multiple audio inputs into a single output.
1169 Note that this filter only supports float samples (the @var{amerge}
1170 and @var{pan} audio filters support many formats). If the @var{amix}
1171 input has integer samples then @ref{aresample} will be automatically
1172 inserted to perform the conversion to float samples.
1176 ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT
1178 will mix 3 input audio streams to a single output with the same duration as the
1179 first input and a dropout transition time of 3 seconds.
1181 It accepts the following parameters:
1185 The number of inputs. If unspecified, it defaults to 2.
1188 How to determine the end-of-stream.
1192 The duration of the longest input. (default)
1195 The duration of the shortest input.
1198 The duration of the first input.
1202 @item dropout_transition
1203 The transition time, in seconds, for volume renormalization when an input
1204 stream ends. The default value is 2 seconds.
1208 @section anequalizer
1210 High-order parametric multiband equalizer for each channel.
1212 It accepts the following parameters:
1216 This option string is in format:
1217 "c@var{chn} f=@var{cf} w=@var{w} g=@var{g} t=@var{f} | ..."
1218 Each equalizer band is separated by '|'.
1222 Set channel number to which equalization will be applied.
1223 If input doesn't have that channel the entry is ignored.
1226 Set central frequency for band.
1227 If input doesn't have that frequency the entry is ignored.
1230 Set band width in hertz.
1233 Set band gain in dB.
1236 Set filter type for band, optional, can be:
1240 Butterworth, this is default.
1251 With this option activated frequency response of anequalizer is displayed
1255 Set video stream size. Only useful if curves option is activated.
1258 Set max gain that will be displayed. Only useful if curves option is activated.
1259 Setting this to a reasonable value makes it possible to display gain which is derived from
1260 neighbour bands which are too close to each other and thus produce higher gain
1261 when both are activated.
1264 Set frequency scale used to draw frequency response in video output.
1265 Can be linear or logarithmic. Default is logarithmic.
1268 Set color for each channel curve which is going to be displayed in video stream.
1269 This is list of color names separated by space or by '|'.
1270 Unrecognised or missing colors will be replaced by white color.
1273 @subsection Examples
1277 Lower gain by 10 of central frequency 200Hz and width 100 Hz
1278 for first 2 channels using Chebyshev type 1 filter:
1280 anequalizer=c0 f=200 w=100 g=-10 t=1|c1 f=200 w=100 g=-10 t=1
1284 @subsection Commands
1286 This filter supports the following commands:
1289 Alter existing filter parameters.
1290 Syntax for the commands is : "@var{fN}|f=@var{freq}|w=@var{width}|g=@var{gain}"
1292 @var{fN} is existing filter number, starting from 0, if no such filter is available
1294 @var{freq} set new frequency parameter.
1295 @var{width} set new width parameter in herz.
1296 @var{gain} set new gain parameter in dB.
1298 Full filter invocation with asendcmd may look like this:
1299 asendcmd=c='4.0 anequalizer change 0|f=200|w=50|g=1',anequalizer=...
1304 Pass the audio source unchanged to the output.
1308 Pad the end of an audio stream with silence.
1310 This can be used together with @command{ffmpeg} @option{-shortest} to
1311 extend audio streams to the same length as the video stream.
1313 A description of the accepted options follows.
1317 Set silence packet size. Default value is 4096.
1320 Set the number of samples of silence to add to the end. After the
1321 value is reached, the stream is terminated. This option is mutually
1322 exclusive with @option{whole_len}.
1325 Set the minimum total number of samples in the output audio stream. If
1326 the value is longer than the input audio length, silence is added to
1327 the end, until the value is reached. This option is mutually exclusive
1328 with @option{pad_len}.
1331 If neither the @option{pad_len} nor the @option{whole_len} option is
1332 set, the filter will add silence to the end of the input stream
1335 @subsection Examples
1339 Add 1024 samples of silence to the end of the input:
1345 Make sure the audio output will contain at least 10000 samples, pad
1346 the input with silence if required:
1348 apad=whole_len=10000
1352 Use @command{ffmpeg} to pad the audio input with silence, so that the
1353 video stream will always result the shortest and will be converted
1354 until the end in the output file when using the @option{shortest}
1357 ffmpeg -i VIDEO -i AUDIO -filter_complex "[1:0]apad" -shortest OUTPUT
1362 Add a phasing effect to the input audio.
1364 A phaser filter creates series of peaks and troughs in the frequency spectrum.
1365 The position of the peaks and troughs are modulated so that they vary over time, creating a sweeping effect.
1367 A description of the accepted parameters follows.
1371 Set input gain. Default is 0.4.
1374 Set output gain. Default is 0.74
1377 Set delay in milliseconds. Default is 3.0.
1380 Set decay. Default is 0.4.
1383 Set modulation speed in Hz. Default is 0.5.
1386 Set modulation type. Default is triangular.
1388 It accepts the following values:
1397 Audio pulsator is something between an autopanner and a tremolo.
1398 But it can produce funny stereo effects as well. Pulsator changes the volume
1399 of the left and right channel based on a LFO (low frequency oscillator) with
1400 different waveforms and shifted phases.
1401 This filter have the ability to define an offset between left and right
1402 channel. An offset of 0 means that both LFO shapes match each other.
1403 The left and right channel are altered equally - a conventional tremolo.
1404 An offset of 50% means that the shape of the right channel is exactly shifted
1405 in phase (or moved backwards about half of the frequency) - pulsator acts as
1406 an autopanner. At 1 both curves match again. Every setting in between moves the
1407 phase shift gapless between all stages and produces some "bypassing" sounds with
1408 sine and triangle waveforms. The more you set the offset near 1 (starting from
1409 the 0.5) the faster the signal passes from the left to the right speaker.
1411 The filter accepts the following options:
1415 Set input gain. By default it is 1. Range is [0.015625 - 64].
1418 Set output gain. By default it is 1. Range is [0.015625 - 64].
1421 Set waveform shape the LFO will use. Can be one of: sine, triangle, square,
1422 sawup or sawdown. Default is sine.
1425 Set modulation. Define how much of original signal is affected by the LFO.
1428 Set left channel offset. Default is 0. Allowed range is [0 - 1].
1431 Set right channel offset. Default is 0.5. Allowed range is [0 - 1].
1434 Set pulse width. Default is 1. Allowed range is [0 - 2].
1437 Set possible timing mode. Can be one of: bpm, ms or hz. Default is hz.
1440 Set bpm. Default is 120. Allowed range is [30 - 300]. Only used if timing
1444 Set ms. Default is 500. Allowed range is [10 - 2000]. Only used if timing
1448 Set frequency in Hz. Default is 2. Allowed range is [0.01 - 100]. Only used
1449 if timing is set to hz.
1455 Resample the input audio to the specified parameters, using the
1456 libswresample library. If none are specified then the filter will
1457 automatically convert between its input and output.
1459 This filter is also able to stretch/squeeze the audio data to make it match
1460 the timestamps or to inject silence / cut out audio to make it match the
1461 timestamps, do a combination of both or do neither.
1463 The filter accepts the syntax
1464 [@var{sample_rate}:]@var{resampler_options}, where @var{sample_rate}
1465 expresses a sample rate and @var{resampler_options} is a list of
1466 @var{key}=@var{value} pairs, separated by ":". See the
1467 @ref{Resampler Options,,the "Resampler Options" section in the
1468 ffmpeg-resampler(1) manual,ffmpeg-resampler}
1469 for the complete list of supported options.
1471 @subsection Examples
1475 Resample the input audio to 44100Hz:
1481 Stretch/squeeze samples to the given timestamps, with a maximum of 1000
1482 samples per second compensation:
1484 aresample=async=1000
1490 Reverse an audio clip.
1492 Warning: This filter requires memory to buffer the entire clip, so trimming
1495 @subsection Examples
1499 Take the first 5 seconds of a clip, and reverse it.
1501 atrim=end=5,areverse
1505 @section asetnsamples
1507 Set the number of samples per each output audio frame.
1509 The last output packet may contain a different number of samples, as
1510 the filter will flush all the remaining samples when the input audio
1513 The filter accepts the following options:
1517 @item nb_out_samples, n
1518 Set the number of frames per each output audio frame. The number is
1519 intended as the number of samples @emph{per each channel}.
1520 Default value is 1024.
1523 If set to 1, the filter will pad the last audio frame with zeroes, so
1524 that the last frame will contain the same number of samples as the
1525 previous ones. Default value is 1.
1528 For example, to set the number of per-frame samples to 1234 and
1529 disable padding for the last frame, use:
1531 asetnsamples=n=1234:p=0
1536 Set the sample rate without altering the PCM data.
1537 This will result in a change of speed and pitch.
1539 The filter accepts the following options:
1542 @item sample_rate, r
1543 Set the output sample rate. Default is 44100 Hz.
1548 Show a line containing various information for each input audio frame.
1549 The input audio is not modified.
1551 The shown line contains a sequence of key/value pairs of the form
1552 @var{key}:@var{value}.
1554 The following values are shown in the output:
1558 The (sequential) number of the input frame, starting from 0.
1561 The presentation timestamp of the input frame, in time base units; the time base
1562 depends on the filter input pad, and is usually 1/@var{sample_rate}.
1565 The presentation timestamp of the input frame in seconds.
1568 position of the frame in the input stream, -1 if this information in
1569 unavailable and/or meaningless (for example in case of synthetic audio)
1578 The sample rate for the audio frame.
1581 The number of samples (per channel) in the frame.
1584 The Adler-32 checksum (printed in hexadecimal) of the audio data. For planar
1585 audio, the data is treated as if all the planes were concatenated.
1587 @item plane_checksums
1588 A list of Adler-32 checksums for each data plane.
1594 Display time domain statistical information about the audio channels.
1595 Statistics are calculated and displayed for each audio channel and,
1596 where applicable, an overall figure is also given.
1598 It accepts the following option:
1601 Short window length in seconds, used for peak and trough RMS measurement.
1602 Default is @code{0.05} (50 milliseconds). Allowed range is @code{[0.1 - 10]}.
1606 Set metadata injection. All the metadata keys are prefixed with @code{lavfi.astats.X},
1607 where @code{X} is channel number starting from 1 or string @code{Overall}. Default is
1610 Available keys for each channel are:
1643 For example full key look like this @code{lavfi.astats.1.DC_offset} or
1644 this @code{lavfi.astats.Overall.Peak_count}.
1646 For description what each key means read below.
1649 Set number of frame after which stats are going to be recalculated.
1650 Default is disabled.
1653 A description of each shown parameter follows:
1657 Mean amplitude displacement from zero.
1660 Minimal sample level.
1663 Maximal sample level.
1665 @item Min difference
1666 Minimal difference between two consecutive samples.
1668 @item Max difference
1669 Maximal difference between two consecutive samples.
1671 @item Mean difference
1672 Mean difference between two consecutive samples.
1673 The average of each difference between two consecutive samples.
1675 @item RMS difference
1676 Root Mean Square difference between two consecutive samples.
1680 Standard peak and RMS level measured in dBFS.
1684 Peak and trough values for RMS level measured over a short window.
1687 Standard ratio of peak to RMS level (note: not in dB).
1690 Flatness (i.e. consecutive samples with the same value) of the signal at its peak levels
1691 (i.e. either @var{Min level} or @var{Max level}).
1694 Number of occasions (not the number of samples) that the signal attained either
1695 @var{Min level} or @var{Max level}.
1698 Overall bit depth of audio. Number of bits used for each sample.
1705 The filter accepts exactly one parameter, the audio tempo. If not
1706 specified then the filter will assume nominal 1.0 tempo. Tempo must
1707 be in the [0.5, 2.0] range.
1709 @subsection Examples
1713 Slow down audio to 80% tempo:
1719 To speed up audio to 125% tempo:
1727 Trim the input so that the output contains one continuous subpart of the input.
1729 It accepts the following parameters:
1732 Timestamp (in seconds) of the start of the section to keep. I.e. the audio
1733 sample with the timestamp @var{start} will be the first sample in the output.
1736 Specify time of the first audio sample that will be dropped, i.e. the
1737 audio sample immediately preceding the one with the timestamp @var{end} will be
1738 the last sample in the output.
1741 Same as @var{start}, except this option sets the start timestamp in samples
1745 Same as @var{end}, except this option sets the end timestamp in samples instead
1749 The maximum duration of the output in seconds.
1752 The number of the first sample that should be output.
1755 The number of the first sample that should be dropped.
1758 @option{start}, @option{end}, and @option{duration} are expressed as time
1759 duration specifications; see
1760 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}.
1762 Note that the first two sets of the start/end options and the @option{duration}
1763 option look at the frame timestamp, while the _sample options simply count the
1764 samples that pass through the filter. So start/end_pts and start/end_sample will
1765 give different results when the timestamps are wrong, inexact or do not start at
1766 zero. Also note that this filter does not modify the timestamps. If you wish
1767 to have the output timestamps start at zero, insert the asetpts filter after the
1770 If multiple start or end options are set, this filter tries to be greedy and
1771 keep all samples that match at least one of the specified constraints. To keep
1772 only the part that matches all the constraints at once, chain multiple atrim
1775 The defaults are such that all the input is kept. So it is possible to set e.g.
1776 just the end values to keep everything before the specified time.
1781 Drop everything except the second minute of input:
1783 ffmpeg -i INPUT -af atrim=60:120
1787 Keep only the first 1000 samples:
1789 ffmpeg -i INPUT -af atrim=end_sample=1000
1796 Apply a two-pole Butterworth band-pass filter with central
1797 frequency @var{frequency}, and (3dB-point) band-width width.
1798 The @var{csg} option selects a constant skirt gain (peak gain = Q)
1799 instead of the default: constant 0dB peak gain.
1800 The filter roll off at 6dB per octave (20dB per decade).
1802 The filter accepts the following options:
1806 Set the filter's central frequency. Default is @code{3000}.
1809 Constant skirt gain if set to 1. Defaults to 0.
1812 Set method to specify band-width of filter.
1825 Specify the band-width of a filter in width_type units.
1828 Specify which channels to filter, by default all available are filtered.
1833 Apply a two-pole Butterworth band-reject filter with central
1834 frequency @var{frequency}, and (3dB-point) band-width @var{width}.
1835 The filter roll off at 6dB per octave (20dB per decade).
1837 The filter accepts the following options:
1841 Set the filter's central frequency. Default is @code{3000}.
1844 Set method to specify band-width of filter.
1857 Specify the band-width of a filter in width_type units.
1860 Specify which channels to filter, by default all available are filtered.
1865 Boost or cut the bass (lower) frequencies of the audio using a two-pole
1866 shelving filter with a response similar to that of a standard
1867 hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
1869 The filter accepts the following options:
1873 Give the gain at 0 Hz. Its useful range is about -20
1874 (for a large cut) to +20 (for a large boost).
1875 Beware of clipping when using a positive gain.
1878 Set the filter's central frequency and so can be used
1879 to extend or reduce the frequency range to be boosted or cut.
1880 The default value is @code{100} Hz.
1883 Set method to specify band-width of filter.
1896 Determine how steep is the filter's shelf transition.
1899 Specify which channels to filter, by default all available are filtered.
1904 Apply a biquad IIR filter with the given coefficients.
1905 Where @var{b0}, @var{b1}, @var{b2} and @var{a0}, @var{a1}, @var{a2}
1906 are the numerator and denominator coefficients respectively.
1907 and @var{channels}, @var{c} specify which channels to filter, by default all
1908 available are filtered.
1911 Bauer stereo to binaural transformation, which improves headphone listening of
1912 stereo audio records.
1914 To enable compilation of this filter you need to configure FFmpeg with
1915 @code{--enable-libbs2b}.
1917 It accepts the following parameters:
1921 Pre-defined crossfeed level.
1925 Default level (fcut=700, feed=50).
1928 Chu Moy circuit (fcut=700, feed=60).
1931 Jan Meier circuit (fcut=650, feed=95).
1936 Cut frequency (in Hz).
1945 Remap input channels to new locations.
1947 It accepts the following parameters:
1950 Map channels from input to output. The argument is a '|'-separated list of
1951 mappings, each in the @code{@var{in_channel}-@var{out_channel}} or
1952 @var{in_channel} form. @var{in_channel} can be either the name of the input
1953 channel (e.g. FL for front left) or its index in the input channel layout.
1954 @var{out_channel} is the name of the output channel or its index in the output
1955 channel layout. If @var{out_channel} is not given then it is implicitly an
1956 index, starting with zero and increasing by one for each mapping.
1958 @item channel_layout
1959 The channel layout of the output stream.
1962 If no mapping is present, the filter will implicitly map input channels to
1963 output channels, preserving indices.
1965 For example, assuming a 5.1+downmix input MOV file,
1967 ffmpeg -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav
1969 will create an output WAV file tagged as stereo from the downmix channels of
1972 To fix a 5.1 WAV improperly encoded in AAC's native channel order
1974 ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:5.1' out.wav
1977 @section channelsplit
1979 Split each channel from an input audio stream into a separate output stream.
1981 It accepts the following parameters:
1983 @item channel_layout
1984 The channel layout of the input stream. The default is "stereo".
1987 For example, assuming a stereo input MP3 file,
1989 ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv
1991 will create an output Matroska file with two audio streams, one containing only
1992 the left channel and the other the right channel.
1994 Split a 5.1 WAV file into per-channel files:
1996 ffmpeg -i in.wav -filter_complex
1997 'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]'
1998 -map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]'
1999 front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]'
2004 Add a chorus effect to the audio.
2006 Can make a single vocal sound like a chorus, but can also be applied to instrumentation.
2008 Chorus resembles an echo effect with a short delay, but whereas with echo the delay is
2009 constant, with chorus, it is varied using using sinusoidal or triangular modulation.
2010 The modulation depth defines the range the modulated delay is played before or after
2011 the delay. Hence the delayed sound will sound slower or faster, that is the delayed
2012 sound tuned around the original one, like in a chorus where some vocals are slightly
2015 It accepts the following parameters:
2018 Set input gain. Default is 0.4.
2021 Set output gain. Default is 0.4.
2024 Set delays. A typical delay is around 40ms to 60ms.
2036 @subsection Examples
2042 chorus=0.7:0.9:55:0.4:0.25:2
2048 chorus=0.6:0.9:50|60:0.4|0.32:0.25|0.4:2|1.3
2052 Fuller sounding chorus with three delays:
2054 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
2059 Compress or expand the audio's dynamic range.
2061 It accepts the following parameters:
2067 A list of times in seconds for each channel over which the instantaneous level
2068 of the input signal is averaged to determine its volume. @var{attacks} refers to
2069 increase of volume and @var{decays} refers to decrease of volume. For most
2070 situations, the attack time (response to the audio getting louder) should be
2071 shorter than the decay time, because the human ear is more sensitive to sudden
2072 loud audio than sudden soft audio. A typical value for attack is 0.3 seconds and
2073 a typical value for decay is 0.8 seconds.
2074 If specified number of attacks & decays is lower than number of channels, the last
2075 set attack/decay will be used for all remaining channels.
2078 A list of points for the transfer function, specified in dB relative to the
2079 maximum possible signal amplitude. Each key points list must be defined using
2080 the following syntax: @code{x0/y0|x1/y1|x2/y2|....} or
2081 @code{x0/y0 x1/y1 x2/y2 ....}
2083 The input values must be in strictly increasing order but the transfer function
2084 does not have to be monotonically rising. The point @code{0/0} is assumed but
2085 may be overridden (by @code{0/out-dBn}). Typical values for the transfer
2086 function are @code{-70/-70|-60/-20|1/0}.
2089 Set the curve radius in dB for all joints. It defaults to 0.01.
2092 Set the additional gain in dB to be applied at all points on the transfer
2093 function. This allows for easy adjustment of the overall gain.
2097 Set an initial volume, in dB, to be assumed for each channel when filtering
2098 starts. This permits the user to supply a nominal level initially, so that, for
2099 example, a very large gain is not applied to initial signal levels before the
2100 companding has begun to operate. A typical value for audio which is initially
2101 quiet is -90 dB. It defaults to 0.
2104 Set a delay, in seconds. The input audio is analyzed immediately, but audio is
2105 delayed before being fed to the volume adjuster. Specifying a delay
2106 approximately equal to the attack/decay times allows the filter to effectively
2107 operate in predictive rather than reactive mode. It defaults to 0.
2111 @subsection Examples
2115 Make music with both quiet and loud passages suitable for listening to in a
2118 compand=.3|.3:1|1:-90/-60|-60/-40|-40/-30|-20/-20:6:0:-90:0.2
2121 Another example for audio with whisper and explosion parts:
2123 compand=0|0:1|1:-90/-900|-70/-70|-30/-9|0/-3:6:0:0:0
2127 A noise gate for when the noise is at a lower level than the signal:
2129 compand=.1|.1:.2|.2:-900/-900|-50.1/-900|-50/-50:.01:0:-90:.1
2133 Here is another noise gate, this time for when the noise is at a higher level
2134 than the signal (making it, in some ways, similar to squelch):
2136 compand=.1|.1:.1|.1:-45.1/-45.1|-45/-900|0/-900:.01:45:-90:.1
2140 2:1 compression starting at -6dB:
2142 compand=points=-80/-80|-6/-6|0/-3.8|20/3.5
2146 2:1 compression starting at -9dB:
2148 compand=points=-80/-80|-9/-9|0/-5.3|20/2.9
2152 2:1 compression starting at -12dB:
2154 compand=points=-80/-80|-12/-12|0/-6.8|20/1.9
2158 2:1 compression starting at -18dB:
2160 compand=points=-80/-80|-18/-18|0/-9.8|20/0.7
2164 3:1 compression starting at -15dB:
2166 compand=points=-80/-80|-15/-15|0/-10.8|20/-5.2
2172 compand=points=-80/-105|-62/-80|-15.4/-15.4|0/-12|20/-7.6
2178 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
2182 Hard limiter at -6dB:
2184 compand=attacks=0:points=-80/-80|-6/-6|20/-6
2188 Hard limiter at -12dB:
2190 compand=attacks=0:points=-80/-80|-12/-12|20/-12
2194 Hard noise gate at -35 dB:
2196 compand=attacks=0:points=-80/-115|-35.1/-80|-35/-35|20/20
2202 compand=attacks=0:points=-80/-80|-12.4/-12.4|-6/-8|0/-6.8|20/-2.8
2206 @section compensationdelay
2208 Compensation Delay Line is a metric based delay to compensate differing
2209 positions of microphones or speakers.
2211 For example, you have recorded guitar with two microphones placed in
2212 different location. Because the front of sound wave has fixed speed in
2213 normal conditions, the phasing of microphones can vary and depends on
2214 their location and interposition. The best sound mix can be achieved when
2215 these microphones are in phase (synchronized). Note that distance of
2216 ~30 cm between microphones makes one microphone to capture signal in
2217 antiphase to another microphone. That makes the final mix sounding moody.
2218 This filter helps to solve phasing problems by adding different delays
2219 to each microphone track and make them synchronized.
2221 The best result can be reached when you take one track as base and
2222 synchronize other tracks one by one with it.
2223 Remember that synchronization/delay tolerance depends on sample rate, too.
2224 Higher sample rates will give more tolerance.
2226 It accepts the following parameters:
2230 Set millimeters distance. This is compensation distance for fine tuning.
2234 Set cm distance. This is compensation distance for tightening distance setup.
2238 Set meters distance. This is compensation distance for hard distance setup.
2242 Set dry amount. Amount of unprocessed (dry) signal.
2246 Set wet amount. Amount of processed (wet) signal.
2250 Set temperature degree in Celsius. This is the temperature of the environment.
2254 @section crystalizer
2255 Simple algorithm to expand audio dynamic range.
2257 The filter accepts the following options:
2261 Sets the intensity of effect (default: 2.0). Must be in range between 0.0
2262 (unchanged sound) to 10.0 (maximum effect).
2265 Enable clipping. By default is enabled.
2269 Apply a DC shift to the audio.
2271 This can be useful to remove a DC offset (caused perhaps by a hardware problem
2272 in the recording chain) from the audio. The effect of a DC offset is reduced
2273 headroom and hence volume. The @ref{astats} filter can be used to determine if
2274 a signal has a DC offset.
2278 Set the DC shift, allowed range is [-1, 1]. It indicates the amount to shift
2282 Optional. It should have a value much less than 1 (e.g. 0.05 or 0.02) and is
2283 used to prevent clipping.
2287 Dynamic Audio Normalizer.
2289 This filter applies a certain amount of gain to the input audio in order
2290 to bring its peak magnitude to a target level (e.g. 0 dBFS). However, in
2291 contrast to more "simple" normalization algorithms, the Dynamic Audio
2292 Normalizer *dynamically* re-adjusts the gain factor to the input audio.
2293 This allows for applying extra gain to the "quiet" sections of the audio
2294 while avoiding distortions or clipping the "loud" sections. In other words:
2295 The Dynamic Audio Normalizer will "even out" the volume of quiet and loud
2296 sections, in the sense that the volume of each section is brought to the
2297 same target level. Note, however, that the Dynamic Audio Normalizer achieves
2298 this goal *without* applying "dynamic range compressing". It will retain 100%
2299 of the dynamic range *within* each section of the audio file.
2303 Set the frame length in milliseconds. In range from 10 to 8000 milliseconds.
2304 Default is 500 milliseconds.
2305 The Dynamic Audio Normalizer processes the input audio in small chunks,
2306 referred to as frames. This is required, because a peak magnitude has no
2307 meaning for just a single sample value. Instead, we need to determine the
2308 peak magnitude for a contiguous sequence of sample values. While a "standard"
2309 normalizer would simply use the peak magnitude of the complete file, the
2310 Dynamic Audio Normalizer determines the peak magnitude individually for each
2311 frame. The length of a frame is specified in milliseconds. By default, the
2312 Dynamic Audio Normalizer uses a frame length of 500 milliseconds, which has
2313 been found to give good results with most files.
2314 Note that the exact frame length, in number of samples, will be determined
2315 automatically, based on the sampling rate of the individual input audio file.
2318 Set the Gaussian filter window size. In range from 3 to 301, must be odd
2319 number. Default is 31.
2320 Probably the most important parameter of the Dynamic Audio Normalizer is the
2321 @code{window size} of the Gaussian smoothing filter. The filter's window size
2322 is specified in frames, centered around the current frame. For the sake of
2323 simplicity, this must be an odd number. Consequently, the default value of 31
2324 takes into account the current frame, as well as the 15 preceding frames and
2325 the 15 subsequent frames. Using a larger window results in a stronger
2326 smoothing effect and thus in less gain variation, i.e. slower gain
2327 adaptation. Conversely, using a smaller window results in a weaker smoothing
2328 effect and thus in more gain variation, i.e. faster gain adaptation.
2329 In other words, the more you increase this value, the more the Dynamic Audio
2330 Normalizer will behave like a "traditional" normalization filter. On the
2331 contrary, the more you decrease this value, the more the Dynamic Audio
2332 Normalizer will behave like a dynamic range compressor.
2335 Set the target peak value. This specifies the highest permissible magnitude
2336 level for the normalized audio input. This filter will try to approach the
2337 target peak magnitude as closely as possible, but at the same time it also
2338 makes sure that the normalized signal will never exceed the peak magnitude.
2339 A frame's maximum local gain factor is imposed directly by the target peak
2340 magnitude. The default value is 0.95 and thus leaves a headroom of 5%*.
2341 It is not recommended to go above this value.
2344 Set the maximum gain factor. In range from 1.0 to 100.0. Default is 10.0.
2345 The Dynamic Audio Normalizer determines the maximum possible (local) gain
2346 factor for each input frame, i.e. the maximum gain factor that does not
2347 result in clipping or distortion. The maximum gain factor is determined by
2348 the frame's highest magnitude sample. However, the Dynamic Audio Normalizer
2349 additionally bounds the frame's maximum gain factor by a predetermined
2350 (global) maximum gain factor. This is done in order to avoid excessive gain
2351 factors in "silent" or almost silent frames. By default, the maximum gain
2352 factor is 10.0, For most inputs the default value should be sufficient and
2353 it usually is not recommended to increase this value. Though, for input
2354 with an extremely low overall volume level, it may be necessary to allow even
2355 higher gain factors. Note, however, that the Dynamic Audio Normalizer does
2356 not simply apply a "hard" threshold (i.e. cut off values above the threshold).
2357 Instead, a "sigmoid" threshold function will be applied. This way, the
2358 gain factors will smoothly approach the threshold value, but never exceed that
2362 Set the target RMS. In range from 0.0 to 1.0. Default is 0.0 - disabled.
2363 By default, the Dynamic Audio Normalizer performs "peak" normalization.
2364 This means that the maximum local gain factor for each frame is defined
2365 (only) by the frame's highest magnitude sample. This way, the samples can
2366 be amplified as much as possible without exceeding the maximum signal
2367 level, i.e. without clipping. Optionally, however, the Dynamic Audio
2368 Normalizer can also take into account the frame's root mean square,
2369 abbreviated RMS. In electrical engineering, the RMS is commonly used to
2370 determine the power of a time-varying signal. It is therefore considered
2371 that the RMS is a better approximation of the "perceived loudness" than
2372 just looking at the signal's peak magnitude. Consequently, by adjusting all
2373 frames to a constant RMS value, a uniform "perceived loudness" can be
2374 established. If a target RMS value has been specified, a frame's local gain
2375 factor is defined as the factor that would result in exactly that RMS value.
2376 Note, however, that the maximum local gain factor is still restricted by the
2377 frame's highest magnitude sample, in order to prevent clipping.
2380 Enable channels coupling. By default is enabled.
2381 By default, the Dynamic Audio Normalizer will amplify all channels by the same
2382 amount. This means the same gain factor will be applied to all channels, i.e.
2383 the maximum possible gain factor is determined by the "loudest" channel.
2384 However, in some recordings, it may happen that the volume of the different
2385 channels is uneven, e.g. one channel may be "quieter" than the other one(s).
2386 In this case, this option can be used to disable the channel coupling. This way,
2387 the gain factor will be determined independently for each channel, depending
2388 only on the individual channel's highest magnitude sample. This allows for
2389 harmonizing the volume of the different channels.
2392 Enable DC bias correction. By default is disabled.
2393 An audio signal (in the time domain) is a sequence of sample values.
2394 In the Dynamic Audio Normalizer these sample values are represented in the
2395 -1.0 to 1.0 range, regardless of the original input format. Normally, the
2396 audio signal, or "waveform", should be centered around the zero point.
2397 That means if we calculate the mean value of all samples in a file, or in a
2398 single frame, then the result should be 0.0 or at least very close to that
2399 value. If, however, there is a significant deviation of the mean value from
2400 0.0, in either positive or negative direction, this is referred to as a
2401 DC bias or DC offset. Since a DC bias is clearly undesirable, the Dynamic
2402 Audio Normalizer provides optional DC bias correction.
2403 With DC bias correction enabled, the Dynamic Audio Normalizer will determine
2404 the mean value, or "DC correction" offset, of each input frame and subtract
2405 that value from all of the frame's sample values which ensures those samples
2406 are centered around 0.0 again. Also, in order to avoid "gaps" at the frame
2407 boundaries, the DC correction offset values will be interpolated smoothly
2408 between neighbouring frames.
2411 Enable alternative boundary mode. By default is disabled.
2412 The Dynamic Audio Normalizer takes into account a certain neighbourhood
2413 around each frame. This includes the preceding frames as well as the
2414 subsequent frames. However, for the "boundary" frames, located at the very
2415 beginning and at the very end of the audio file, not all neighbouring
2416 frames are available. In particular, for the first few frames in the audio
2417 file, the preceding frames are not known. And, similarly, for the last few
2418 frames in the audio file, the subsequent frames are not known. Thus, the
2419 question arises which gain factors should be assumed for the missing frames
2420 in the "boundary" region. The Dynamic Audio Normalizer implements two modes
2421 to deal with this situation. The default boundary mode assumes a gain factor
2422 of exactly 1.0 for the missing frames, resulting in a smooth "fade in" and
2423 "fade out" at the beginning and at the end of the input, respectively.
2426 Set the compress factor. In range from 0.0 to 30.0. Default is 0.0.
2427 By default, the Dynamic Audio Normalizer does not apply "traditional"
2428 compression. This means that signal peaks will not be pruned and thus the
2429 full dynamic range will be retained within each local neighbourhood. However,
2430 in some cases it may be desirable to combine the Dynamic Audio Normalizer's
2431 normalization algorithm with a more "traditional" compression.
2432 For this purpose, the Dynamic Audio Normalizer provides an optional compression
2433 (thresholding) function. If (and only if) the compression feature is enabled,
2434 all input frames will be processed by a soft knee thresholding function prior
2435 to the actual normalization process. Put simply, the thresholding function is
2436 going to prune all samples whose magnitude exceeds a certain threshold value.
2437 However, the Dynamic Audio Normalizer does not simply apply a fixed threshold
2438 value. Instead, the threshold value will be adjusted for each individual
2440 In general, smaller parameters result in stronger compression, and vice versa.
2441 Values below 3.0 are not recommended, because audible distortion may appear.
2446 Make audio easier to listen to on headphones.
2448 This filter adds `cues' to 44.1kHz stereo (i.e. audio CD format) audio
2449 so that when listened to on headphones the stereo image is moved from
2450 inside your head (standard for headphones) to outside and in front of
2451 the listener (standard for speakers).
2457 Apply a two-pole peaking equalisation (EQ) filter. With this
2458 filter, the signal-level at and around a selected frequency can
2459 be increased or decreased, whilst (unlike bandpass and bandreject
2460 filters) that at all other frequencies is unchanged.
2462 In order to produce complex equalisation curves, this filter can
2463 be given several times, each with a different central frequency.
2465 The filter accepts the following options:
2469 Set the filter's central frequency in Hz.
2472 Set method to specify band-width of filter.
2485 Specify the band-width of a filter in width_type units.
2488 Set the required gain or attenuation in dB.
2489 Beware of clipping when using a positive gain.
2492 Specify which channels to filter, by default all available are filtered.
2495 @subsection Examples
2498 Attenuate 10 dB at 1000 Hz, with a bandwidth of 200 Hz:
2500 equalizer=f=1000:width_type=h:width=200:g=-10
2504 Apply 2 dB gain at 1000 Hz with Q 1 and attenuate 5 dB at 100 Hz with Q 2:
2506 equalizer=f=1000:width_type=q:width=1:g=2,equalizer=f=100:width_type=q:width=2:g=-5
2510 @section extrastereo
2512 Linearly increases the difference between left and right channels which
2513 adds some sort of "live" effect to playback.
2515 The filter accepts the following options:
2519 Sets the difference coefficient (default: 2.5). 0.0 means mono sound
2520 (average of both channels), with 1.0 sound will be unchanged, with
2521 -1.0 left and right channels will be swapped.
2524 Enable clipping. By default is enabled.
2527 @section firequalizer
2528 Apply FIR Equalization using arbitrary frequency response.
2530 The filter accepts the following option:
2534 Set gain curve equation (in dB). The expression can contain variables:
2537 the evaluated frequency
2541 channel number, set to 0 when multichannels evaluation is disabled
2543 channel id, see libavutil/channel_layout.h, set to the first channel id when
2544 multichannels evaluation is disabled
2548 channel_layout, see libavutil/channel_layout.h
2553 @item gain_interpolate(f)
2554 interpolate gain on frequency f based on gain_entry
2555 @item cubic_interpolate(f)
2556 same as gain_interpolate, but smoother
2558 This option is also available as command. Default is @code{gain_interpolate(f)}.
2561 Set gain entry for gain_interpolate function. The expression can
2565 store gain entry at frequency f with value g
2567 This option is also available as command.
2570 Set filter delay in seconds. Higher value means more accurate.
2571 Default is @code{0.01}.
2574 Set filter accuracy in Hz. Lower value means more accurate.
2575 Default is @code{5}.
2578 Set window function. Acceptable values are:
2581 rectangular window, useful when gain curve is already smooth
2583 hann window (default)
2589 3-terms continuous 1st derivative nuttall window
2591 minimum 3-terms discontinuous nuttall window
2593 4-terms continuous 1st derivative nuttall window
2595 minimum 4-terms discontinuous nuttall (blackman-nuttall) window
2597 blackman-harris window
2603 If enabled, use fixed number of audio samples. This improves speed when
2604 filtering with large delay. Default is disabled.
2607 Enable multichannels evaluation on gain. Default is disabled.
2610 Enable zero phase mode by subtracting timestamp to compensate delay.
2611 Default is disabled.
2614 Set scale used by gain. Acceptable values are:
2617 linear frequency, linear gain
2619 linear frequency, logarithmic (in dB) gain (default)
2621 logarithmic (in octave scale where 20 Hz is 0) frequency, linear gain
2623 logarithmic frequency, logarithmic gain
2627 Set file for dumping, suitable for gnuplot.
2630 Set scale for dumpfile. Acceptable values are same with scale option.
2634 Enable 2-channel convolution using complex FFT. This improves speed significantly.
2635 Default is disabled.
2638 @subsection Examples
2643 firequalizer=gain='if(lt(f,1000), 0, -INF)'
2646 lowpass at 1000 Hz with gain_entry:
2648 firequalizer=gain_entry='entry(1000,0); entry(1001, -INF)'
2651 custom equalization:
2653 firequalizer=gain_entry='entry(100,0); entry(400, -4); entry(1000, -6); entry(2000, 0)'
2656 higher delay with zero phase to compensate delay:
2658 firequalizer=delay=0.1:fixed=on:zero_phase=on
2661 lowpass on left channel, highpass on right channel:
2663 firequalizer=gain='if(eq(chid,1), gain_interpolate(f), if(eq(chid,2), gain_interpolate(1e6+f), 0))'
2664 :gain_entry='entry(1000, 0); entry(1001,-INF); entry(1e6+1000,0)':multi=on
2669 Apply a flanging effect to the audio.
2671 The filter accepts the following options:
2675 Set base delay in milliseconds. Range from 0 to 30. Default value is 0.
2678 Set added swep delay in milliseconds. Range from 0 to 10. Default value is 2.
2681 Set percentage regeneration (delayed signal feedback). Range from -95 to 95.
2685 Set percentage of delayed signal mixed with original. Range from 0 to 100.
2686 Default value is 71.
2689 Set sweeps per second (Hz). Range from 0.1 to 10. Default value is 0.5.
2692 Set swept wave shape, can be @var{triangular} or @var{sinusoidal}.
2693 Default value is @var{sinusoidal}.
2696 Set swept wave percentage-shift for multi channel. Range from 0 to 100.
2697 Default value is 25.
2700 Set delay-line interpolation, @var{linear} or @var{quadratic}.
2701 Default is @var{linear}.
2706 Decodes High Definition Compatible Digital (HDCD) data. A 16-bit PCM stream with
2707 embedded HDCD codes is expanded into a 20-bit PCM stream.
2709 The filter supports the Peak Extend and Low-level Gain Adjustment features
2710 of HDCD, and detects the Transient Filter flag.
2713 ffmpeg -i HDCD16.flac -af hdcd OUT24.flac
2716 When using the filter with wav, note the default encoding for wav is 16-bit,
2717 so the resulting 20-bit stream will be truncated back to 16-bit. Use something
2718 like @command{-acodec pcm_s24le} after the filter to get 24-bit PCM output.
2720 ffmpeg -i HDCD16.wav -af hdcd OUT16.wav
2721 ffmpeg -i HDCD16.wav -af hdcd -acodec pcm_s24le OUT24.wav
2724 The filter accepts the following options:
2727 @item disable_autoconvert
2728 Disable any automatic format conversion or resampling in the filter graph.
2730 @item process_stereo
2731 Process the stereo channels together. If target_gain does not match between
2732 channels, consider it invalid and use the last valid target_gain.
2735 Set the code detect timer period in ms.
2738 Always extend peaks above -3dBFS even if PE isn't signaled.
2741 Replace audio with a solid tone and adjust the amplitude to signal some
2742 specific aspect of the decoding process. The output file can be loaded in
2743 an audio editor alongside the original to aid analysis.
2745 @code{analyze_mode=pe:force_pe=true} can be used to see all samples above the PE level.
2752 Gain adjustment level at each sample
2754 Samples where peak extend occurs
2756 Samples where the code detect timer is active
2758 Samples where the target gain does not match between channels
2764 Apply a high-pass filter with 3dB point frequency.
2765 The filter can be either single-pole, or double-pole (the default).
2766 The filter roll off at 6dB per pole per octave (20dB per pole per decade).
2768 The filter accepts the following options:
2772 Set frequency in Hz. Default is 3000.
2775 Set number of poles. Default is 2.
2778 Set method to specify band-width of filter.
2791 Specify the band-width of a filter in width_type units.
2792 Applies only to double-pole filter.
2793 The default is 0.707q and gives a Butterworth response.
2796 Specify which channels to filter, by default all available are filtered.
2801 Join multiple input streams into one multi-channel stream.
2803 It accepts the following parameters:
2807 The number of input streams. It defaults to 2.
2809 @item channel_layout
2810 The desired output channel layout. It defaults to stereo.
2813 Map channels from inputs to output. The argument is a '|'-separated list of
2814 mappings, each in the @code{@var{input_idx}.@var{in_channel}-@var{out_channel}}
2815 form. @var{input_idx} is the 0-based index of the input stream. @var{in_channel}
2816 can be either the name of the input channel (e.g. FL for front left) or its
2817 index in the specified input stream. @var{out_channel} is the name of the output
2821 The filter will attempt to guess the mappings when they are not specified
2822 explicitly. It does so by first trying to find an unused matching input channel
2823 and if that fails it picks the first unused input channel.
2825 Join 3 inputs (with properly set channel layouts):
2827 ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT
2830 Build a 5.1 output from 6 single-channel streams:
2832 ffmpeg -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex
2833 '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'
2839 Load a LADSPA (Linux Audio Developer's Simple Plugin API) plugin.
2841 To enable compilation of this filter you need to configure FFmpeg with
2842 @code{--enable-ladspa}.
2846 Specifies the name of LADSPA plugin library to load. If the environment
2847 variable @env{LADSPA_PATH} is defined, the LADSPA plugin is searched in
2848 each one of the directories specified by the colon separated list in
2849 @env{LADSPA_PATH}, otherwise in the standard LADSPA paths, which are in
2850 this order: @file{HOME/.ladspa/lib/}, @file{/usr/local/lib/ladspa/},
2851 @file{/usr/lib/ladspa/}.
2854 Specifies the plugin within the library. Some libraries contain only
2855 one plugin, but others contain many of them. If this is not set filter
2856 will list all available plugins within the specified library.
2859 Set the '|' separated list of controls which are zero or more floating point
2860 values that determine the behavior of the loaded plugin (for example delay,
2862 Controls need to be defined using the following syntax:
2863 c0=@var{value0}|c1=@var{value1}|c2=@var{value2}|..., where
2864 @var{valuei} is the value set on the @var{i}-th control.
2865 Alternatively they can be also defined using the following syntax:
2866 @var{value0}|@var{value1}|@var{value2}|..., where
2867 @var{valuei} is the value set on the @var{i}-th control.
2868 If @option{controls} is set to @code{help}, all available controls and
2869 their valid ranges are printed.
2871 @item sample_rate, s
2872 Specify the sample rate, default to 44100. Only used if plugin have
2876 Set the number of samples per channel per each output frame, default
2877 is 1024. Only used if plugin have zero inputs.
2880 Set the minimum duration of the sourced audio. See
2881 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
2882 for the accepted syntax.
2883 Note that the resulting duration may be greater than the specified duration,
2884 as the generated audio is always cut at the end of a complete frame.
2885 If not specified, or the expressed duration is negative, the audio is
2886 supposed to be generated forever.
2887 Only used if plugin have zero inputs.
2891 @subsection Examples
2895 List all available plugins within amp (LADSPA example plugin) library:
2901 List all available controls and their valid ranges for @code{vcf_notch}
2902 plugin from @code{VCF} library:
2904 ladspa=f=vcf:p=vcf_notch:c=help
2908 Simulate low quality audio equipment using @code{Computer Music Toolkit} (CMT)
2911 ladspa=file=cmt:plugin=lofi:controls=c0=22|c1=12|c2=12
2915 Add reverberation to the audio using TAP-plugins
2916 (Tom's Audio Processing plugins):
2918 ladspa=file=tap_reverb:tap_reverb
2922 Generate white noise, with 0.2 amplitude:
2924 ladspa=file=cmt:noise_source_white:c=c0=.2
2928 Generate 20 bpm clicks using plugin @code{C* Click - Metronome} from the
2929 @code{C* Audio Plugin Suite} (CAPS) library:
2931 ladspa=file=caps:Click:c=c1=20'
2935 Apply @code{C* Eq10X2 - Stereo 10-band equaliser} effect:
2937 ladspa=caps:Eq10X2:c=c0=-48|c9=-24|c3=12|c4=2
2941 Increase volume by 20dB using fast lookahead limiter from Steve Harris
2942 @code{SWH Plugins} collection:
2944 ladspa=fast_lookahead_limiter_1913:fastLookaheadLimiter:20|0|2
2948 Attenuate low frequencies using Multiband EQ from Steve Harris
2949 @code{SWH Plugins} collection:
2951 ladspa=mbeq_1197:mbeq:-24|-24|-24|0|0|0|0|0|0|0|0|0|0|0|0
2955 @subsection Commands
2957 This filter supports the following commands:
2960 Modify the @var{N}-th control value.
2962 If the specified value is not valid, it is ignored and prior one is kept.
2967 EBU R128 loudness normalization. Includes both dynamic and linear normalization modes.
2968 Support for both single pass (livestreams, files) and double pass (files) modes.
2969 This algorithm can target IL, LRA, and maximum true peak.
2971 The filter accepts the following options:
2975 Set integrated loudness target.
2976 Range is -70.0 - -5.0. Default value is -24.0.
2979 Set loudness range target.
2980 Range is 1.0 - 20.0. Default value is 7.0.
2983 Set maximum true peak.
2984 Range is -9.0 - +0.0. Default value is -2.0.
2986 @item measured_I, measured_i
2987 Measured IL of input file.
2988 Range is -99.0 - +0.0.
2990 @item measured_LRA, measured_lra
2991 Measured LRA of input file.
2992 Range is 0.0 - 99.0.
2994 @item measured_TP, measured_tp
2995 Measured true peak of input file.
2996 Range is -99.0 - +99.0.
2998 @item measured_thresh
2999 Measured threshold of input file.
3000 Range is -99.0 - +0.0.
3003 Set offset gain. Gain is applied before the true-peak limiter.
3004 Range is -99.0 - +99.0. Default is +0.0.
3007 Normalize linearly if possible.
3008 measured_I, measured_LRA, measured_TP, and measured_thresh must also
3009 to be specified in order to use this mode.
3010 Options are true or false. Default is true.
3013 Treat mono input files as "dual-mono". If a mono file is intended for playback
3014 on a stereo system, its EBU R128 measurement will be perceptually incorrect.
3015 If set to @code{true}, this option will compensate for this effect.
3016 Multi-channel input files are not affected by this option.
3017 Options are true or false. Default is false.
3020 Set print format for stats. Options are summary, json, or none.
3021 Default value is none.
3026 Apply a low-pass filter with 3dB point frequency.
3027 The filter can be either single-pole or double-pole (the default).
3028 The filter roll off at 6dB per pole per octave (20dB per pole per decade).
3030 The filter accepts the following options:
3034 Set frequency in Hz. Default is 500.
3037 Set number of poles. Default is 2.
3040 Set method to specify band-width of filter.
3053 Specify the band-width of a filter in width_type units.
3054 Applies only to double-pole filter.
3055 The default is 0.707q and gives a Butterworth response.
3058 Specify which channels to filter, by default all available are filtered.
3061 @subsection Examples
3064 Lowpass only LFE channel, it LFE is not present it does nothing:
3073 Mix channels with specific gain levels. The filter accepts the output
3074 channel layout followed by a set of channels definitions.
3076 This filter is also designed to efficiently remap the channels of an audio
3079 The filter accepts parameters of the form:
3080 "@var{l}|@var{outdef}|@var{outdef}|..."
3084 output channel layout or number of channels
3087 output channel specification, of the form:
3088 "@var{out_name}=[@var{gain}*]@var{in_name}[(+-)[@var{gain}*]@var{in_name}...]"
3091 output channel to define, either a channel name (FL, FR, etc.) or a channel
3092 number (c0, c1, etc.)
3095 multiplicative coefficient for the channel, 1 leaving the volume unchanged
3098 input channel to use, see out_name for details; it is not possible to mix
3099 named and numbered input channels
3102 If the `=' in a channel specification is replaced by `<', then the gains for
3103 that specification will be renormalized so that the total is 1, thus
3104 avoiding clipping noise.
3106 @subsection Mixing examples
3108 For example, if you want to down-mix from stereo to mono, but with a bigger
3109 factor for the left channel:
3111 pan=1c|c0=0.9*c0+0.1*c1
3114 A customized down-mix to stereo that works automatically for 3-, 4-, 5- and
3115 7-channels surround:
3117 pan=stereo| FL < FL + 0.5*FC + 0.6*BL + 0.6*SL | FR < FR + 0.5*FC + 0.6*BR + 0.6*SR
3120 Note that @command{ffmpeg} integrates a default down-mix (and up-mix) system
3121 that should be preferred (see "-ac" option) unless you have very specific
3124 @subsection Remapping examples
3126 The channel remapping will be effective if, and only if:
3129 @item gain coefficients are zeroes or ones,
3130 @item only one input per channel output,
3133 If all these conditions are satisfied, the filter will notify the user ("Pure
3134 channel mapping detected"), and use an optimized and lossless method to do the
3137 For example, if you have a 5.1 source and want a stereo audio stream by
3138 dropping the extra channels:
3140 pan="stereo| c0=FL | c1=FR"
3143 Given the same source, you can also switch front left and front right channels
3144 and keep the input channel layout:
3146 pan="5.1| c0=c1 | c1=c0 | c2=c2 | c3=c3 | c4=c4 | c5=c5"
3149 If the input is a stereo audio stream, you can mute the front left channel (and
3150 still keep the stereo channel layout) with:
3155 Still with a stereo audio stream input, you can copy the right channel in both
3156 front left and right:
3158 pan="stereo| c0=FR | c1=FR"
3163 ReplayGain scanner filter. This filter takes an audio stream as an input and
3164 outputs it unchanged.
3165 At end of filtering it displays @code{track_gain} and @code{track_peak}.
3169 Convert the audio sample format, sample rate and channel layout. It is
3170 not meant to be used directly.
3173 Apply time-stretching and pitch-shifting with librubberband.
3175 The filter accepts the following options:
3179 Set tempo scale factor.
3182 Set pitch scale factor.
3185 Set transients detector.
3186 Possible values are:
3195 Possible values are:
3204 Possible values are:
3211 Set processing window size.
3212 Possible values are:
3221 Possible values are:
3228 Enable formant preservation when shift pitching.
3229 Possible values are:
3237 Possible values are:
3246 Possible values are:
3253 @section sidechaincompress
3255 This filter acts like normal compressor but has the ability to compress
3256 detected signal using second input signal.
3257 It needs two input streams and returns one output stream.
3258 First input stream will be processed depending on second stream signal.
3259 The filtered signal then can be filtered with other filters in later stages of
3260 processing. See @ref{pan} and @ref{amerge} filter.
3262 The filter accepts the following options:
3266 Set input gain. Default is 1. Range is between 0.015625 and 64.
3269 If a signal of second stream raises above this level it will affect the gain
3270 reduction of first stream.
3271 By default is 0.125. Range is between 0.00097563 and 1.
3274 Set a ratio about which the signal is reduced. 1:2 means that if the level
3275 raised 4dB above the threshold, it will be only 2dB above after the reduction.
3276 Default is 2. Range is between 1 and 20.
3279 Amount of milliseconds the signal has to rise above the threshold before gain
3280 reduction starts. Default is 20. Range is between 0.01 and 2000.
3283 Amount of milliseconds the signal has to fall below the threshold before
3284 reduction is decreased again. Default is 250. Range is between 0.01 and 9000.
3287 Set the amount by how much signal will be amplified after processing.
3288 Default is 2. Range is from 1 and 64.
3291 Curve the sharp knee around the threshold to enter gain reduction more softly.
3292 Default is 2.82843. Range is between 1 and 8.
3295 Choose if the @code{average} level between all channels of side-chain stream
3296 or the louder(@code{maximum}) channel of side-chain stream affects the
3297 reduction. Default is @code{average}.
3300 Should the exact signal be taken in case of @code{peak} or an RMS one in case
3301 of @code{rms}. Default is @code{rms} which is mainly smoother.
3304 Set sidechain gain. Default is 1. Range is between 0.015625 and 64.
3307 How much to use compressed signal in output. Default is 1.
3308 Range is between 0 and 1.
3311 @subsection Examples
3315 Full ffmpeg example taking 2 audio inputs, 1st input to be compressed
3316 depending on the signal of 2nd input and later compressed signal to be
3317 merged with 2nd input:
3319 ffmpeg -i main.flac -i sidechain.flac -filter_complex "[1:a]asplit=2[sc][mix];[0:a][sc]sidechaincompress[compr];[compr][mix]amerge"
3323 @section sidechaingate
3325 A sidechain gate acts like a normal (wideband) gate but has the ability to
3326 filter the detected signal before sending it to the gain reduction stage.
3327 Normally a gate uses the full range signal to detect a level above the
3329 For example: If you cut all lower frequencies from your sidechain signal
3330 the gate will decrease the volume of your track only if not enough highs
3331 appear. With this technique you are able to reduce the resonation of a
3332 natural drum or remove "rumbling" of muted strokes from a heavily distorted
3334 It needs two input streams and returns one output stream.
3335 First input stream will be processed depending on second stream signal.
3337 The filter accepts the following options:
3341 Set input level before filtering.
3342 Default is 1. Allowed range is from 0.015625 to 64.
3345 Set the level of gain reduction when the signal is below the threshold.
3346 Default is 0.06125. Allowed range is from 0 to 1.
3349 If a signal rises above this level the gain reduction is released.
3350 Default is 0.125. Allowed range is from 0 to 1.
3353 Set a ratio about which the signal is reduced.
3354 Default is 2. Allowed range is from 1 to 9000.
3357 Amount of milliseconds the signal has to rise above the threshold before gain
3359 Default is 20 milliseconds. Allowed range is from 0.01 to 9000.
3362 Amount of milliseconds the signal has to fall below the threshold before the
3363 reduction is increased again. Default is 250 milliseconds.
3364 Allowed range is from 0.01 to 9000.
3367 Set amount of amplification of signal after processing.
3368 Default is 1. Allowed range is from 1 to 64.
3371 Curve the sharp knee around the threshold to enter gain reduction more softly.
3372 Default is 2.828427125. Allowed range is from 1 to 8.
3375 Choose if exact signal should be taken for detection or an RMS like one.
3376 Default is rms. Can be peak or rms.
3379 Choose if the average level between all channels or the louder channel affects
3381 Default is average. Can be average or maximum.
3384 Set sidechain gain. Default is 1. Range is from 0.015625 to 64.
3387 @section silencedetect
3389 Detect silence in an audio stream.
3391 This filter logs a message when it detects that the input audio volume is less
3392 or equal to a noise tolerance value for a duration greater or equal to the
3393 minimum detected noise duration.
3395 The printed times and duration are expressed in seconds.
3397 The filter accepts the following options:
3401 Set silence duration until notification (default is 2 seconds).
3404 Set noise tolerance. Can be specified in dB (in case "dB" is appended to the
3405 specified value) or amplitude ratio. Default is -60dB, or 0.001.
3408 @subsection Examples
3412 Detect 5 seconds of silence with -50dB noise tolerance:
3414 silencedetect=n=-50dB:d=5
3418 Complete example with @command{ffmpeg} to detect silence with 0.0001 noise
3419 tolerance in @file{silence.mp3}:
3421 ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null -
3425 @section silenceremove
3427 Remove silence from the beginning, middle or end of the audio.
3429 The filter accepts the following options:
3433 This value is used to indicate if audio should be trimmed at beginning of
3434 the audio. A value of zero indicates no silence should be trimmed from the
3435 beginning. When specifying a non-zero value, it trims audio up until it
3436 finds non-silence. Normally, when trimming silence from beginning of audio
3437 the @var{start_periods} will be @code{1} but it can be increased to higher
3438 values to trim all audio up to specific count of non-silence periods.
3439 Default value is @code{0}.
3441 @item start_duration
3442 Specify the amount of time that non-silence must be detected before it stops
3443 trimming audio. By increasing the duration, bursts of noises can be treated
3444 as silence and trimmed off. Default value is @code{0}.
3446 @item start_threshold
3447 This indicates what sample value should be treated as silence. For digital
3448 audio, a value of @code{0} may be fine but for audio recorded from analog,
3449 you may wish to increase the value to account for background noise.
3450 Can be specified in dB (in case "dB" is appended to the specified value)
3451 or amplitude ratio. Default value is @code{0}.
3454 Set the count for trimming silence from the end of audio.
3455 To remove silence from the middle of a file, specify a @var{stop_periods}
3456 that is negative. This value is then treated as a positive value and is
3457 used to indicate the effect should restart processing as specified by
3458 @var{start_periods}, making it suitable for removing periods of silence
3459 in the middle of the audio.
3460 Default value is @code{0}.
3463 Specify a duration of silence that must exist before audio is not copied any
3464 more. By specifying a higher duration, silence that is wanted can be left in
3466 Default value is @code{0}.
3468 @item stop_threshold
3469 This is the same as @option{start_threshold} but for trimming silence from
3471 Can be specified in dB (in case "dB" is appended to the specified value)
3472 or amplitude ratio. Default value is @code{0}.
3475 This indicates that @var{stop_duration} length of audio should be left intact
3476 at the beginning of each period of silence.
3477 For example, if you want to remove long pauses between words but do not want
3478 to remove the pauses completely. Default value is @code{0}.
3481 Set how is silence detected. Can be @code{rms} or @code{peak}. Second is faster
3482 and works better with digital silence which is exactly 0.
3483 Default value is @code{rms}.
3486 Set ratio used to calculate size of window for detecting silence.
3487 Default value is @code{0.02}. Allowed range is from @code{0} to @code{10}.
3490 @subsection Examples
3494 The following example shows how this filter can be used to start a recording
3495 that does not contain the delay at the start which usually occurs between
3496 pressing the record button and the start of the performance:
3498 silenceremove=1:5:0.02
3502 Trim all silence encountered from beginning to end where there is more than 1
3503 second of silence in audio:
3505 silenceremove=0:0:0:-1:1:-90dB
3511 SOFAlizer uses head-related transfer functions (HRTFs) to create virtual
3512 loudspeakers around the user for binaural listening via headphones (audio
3513 formats up to 9 channels supported).
3514 The HRTFs are stored in SOFA files (see @url{http://www.sofacoustics.org/} for a database).
3515 SOFAlizer is developed at the Acoustics Research Institute (ARI) of the
3516 Austrian Academy of Sciences.
3518 To enable compilation of this filter you need to configure FFmpeg with
3519 @code{--enable-netcdf}.
3521 The filter accepts the following options:
3525 Set the SOFA file used for rendering.
3528 Set gain applied to audio. Value is in dB. Default is 0.
3531 Set rotation of virtual loudspeakers in deg. Default is 0.
3534 Set elevation of virtual speakers in deg. Default is 0.
3537 Set distance in meters between loudspeakers and the listener with near-field
3538 HRTFs. Default is 1.
3541 Set processing type. Can be @var{time} or @var{freq}. @var{time} is
3542 processing audio in time domain which is slow.
3543 @var{freq} is processing audio in frequency domain which is fast.
3544 Default is @var{freq}.
3547 Set custom positions of virtual loudspeakers. Syntax for this option is:
3548 <CH> <AZIM> <ELEV>[|<CH> <AZIM> <ELEV>|...].
3549 Each virtual loudspeaker is described with short channel name following with
3550 azimuth and elevation in degreees.
3551 Each virtual loudspeaker description is separated by '|'.
3552 For example to override front left and front right channel positions use:
3553 'speakers=FL 45 15|FR 345 15'.
3554 Descriptions with unrecognised channel names are ignored.
3557 @subsection Examples
3561 Using ClubFritz6 sofa file:
3563 sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=1
3567 Using ClubFritz12 sofa file and bigger radius with small rotation:
3569 sofalizer=sofa=/path/to/ClubFritz12.sofa:type=freq:radius=2:rotation=5
3573 Similar as above but with custom speaker positions for front left, front right, back left and back right
3574 and also with custom gain:
3576 "sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=2:speakers=FL 45|FR 315|BL 135|BR 225:gain=28"
3580 @section stereotools
3582 This filter has some handy utilities to manage stereo signals, for converting
3583 M/S stereo recordings to L/R signal while having control over the parameters
3584 or spreading the stereo image of master track.
3586 The filter accepts the following options:
3590 Set input level before filtering for both channels. Defaults is 1.
3591 Allowed range is from 0.015625 to 64.
3594 Set output level after filtering for both channels. Defaults is 1.
3595 Allowed range is from 0.015625 to 64.
3598 Set input balance between both channels. Default is 0.
3599 Allowed range is from -1 to 1.
3602 Set output balance between both channels. Default is 0.
3603 Allowed range is from -1 to 1.
3606 Enable softclipping. Results in analog distortion instead of harsh digital 0dB
3607 clipping. Disabled by default.
3610 Mute the left channel. Disabled by default.
3613 Mute the right channel. Disabled by default.
3616 Change the phase of the left channel. Disabled by default.
3619 Change the phase of the right channel. Disabled by default.
3622 Set stereo mode. Available values are:
3626 Left/Right to Left/Right, this is default.
3629 Left/Right to Mid/Side.
3632 Mid/Side to Left/Right.
3635 Left/Right to Left/Left.
3638 Left/Right to Right/Right.
3641 Left/Right to Left + Right.
3644 Left/Right to Right/Left.
3648 Set level of side signal. Default is 1.
3649 Allowed range is from 0.015625 to 64.
3652 Set balance of side signal. Default is 0.
3653 Allowed range is from -1 to 1.
3656 Set level of the middle signal. Default is 1.
3657 Allowed range is from 0.015625 to 64.
3660 Set middle signal pan. Default is 0. Allowed range is from -1 to 1.
3663 Set stereo base between mono and inversed channels. Default is 0.
3664 Allowed range is from -1 to 1.
3667 Set delay in milliseconds how much to delay left from right channel and
3668 vice versa. Default is 0. Allowed range is from -20 to 20.
3671 Set S/C level. Default is 1. Allowed range is from 1 to 100.
3674 Set the stereo phase in degrees. Default is 0. Allowed range is from 0 to 360.
3676 @item bmode_in, bmode_out
3677 Set balance mode for balance_in/balance_out option.
3679 Can be one of the following:
3683 Classic balance mode. Attenuate one channel at time.
3684 Gain is raised up to 1.
3687 Similar as classic mode above but gain is raised up to 2.
3690 Equal power distribution, from -6dB to +6dB range.
3694 @subsection Examples
3698 Apply karaoke like effect:
3700 stereotools=mlev=0.015625
3704 Convert M/S signal to L/R:
3706 "stereotools=mode=ms>lr"
3710 @section stereowiden
3712 This filter enhance the stereo effect by suppressing signal common to both
3713 channels and by delaying the signal of left into right and vice versa,
3714 thereby widening the stereo effect.
3716 The filter accepts the following options:
3720 Time in milliseconds of the delay of left signal into right and vice versa.
3721 Default is 20 milliseconds.
3724 Amount of gain in delayed signal into right and vice versa. Gives a delay
3725 effect of left signal in right output and vice versa which gives widening
3726 effect. Default is 0.3.
3729 Cross feed of left into right with inverted phase. This helps in suppressing
3730 the mono. If the value is 1 it will cancel all the signal common to both
3731 channels. Default is 0.3.
3734 Set level of input signal of original channel. Default is 0.8.
3739 Boost or cut treble (upper) frequencies of the audio using a two-pole
3740 shelving filter with a response similar to that of a standard
3741 hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
3743 The filter accepts the following options:
3747 Give the gain at whichever is the lower of ~22 kHz and the
3748 Nyquist frequency. Its useful range is about -20 (for a large cut)
3749 to +20 (for a large boost). Beware of clipping when using a positive gain.
3752 Set the filter's central frequency and so can be used
3753 to extend or reduce the frequency range to be boosted or cut.
3754 The default value is @code{3000} Hz.
3757 Set method to specify band-width of filter.
3770 Determine how steep is the filter's shelf transition.
3773 Specify which channels to filter, by default all available are filtered.
3778 Sinusoidal amplitude modulation.
3780 The filter accepts the following options:
3784 Modulation frequency in Hertz. Modulation frequencies in the subharmonic range
3785 (20 Hz or lower) will result in a tremolo effect.
3786 This filter may also be used as a ring modulator by specifying
3787 a modulation frequency higher than 20 Hz.
3788 Range is 0.1 - 20000.0. Default value is 5.0 Hz.
3791 Depth of modulation as a percentage. Range is 0.0 - 1.0.
3792 Default value is 0.5.
3797 Sinusoidal phase modulation.
3799 The filter accepts the following options:
3803 Modulation frequency in Hertz.
3804 Range is 0.1 - 20000.0. Default value is 5.0 Hz.
3807 Depth of modulation as a percentage. Range is 0.0 - 1.0.
3808 Default value is 0.5.
3813 Adjust the input audio volume.
3815 It accepts the following parameters:
3819 Set audio volume expression.
3821 Output values are clipped to the maximum value.
3823 The output audio volume is given by the relation:
3825 @var{output_volume} = @var{volume} * @var{input_volume}
3828 The default value for @var{volume} is "1.0".
3831 This parameter represents the mathematical precision.
3833 It determines which input sample formats will be allowed, which affects the
3834 precision of the volume scaling.
3838 8-bit fixed-point; this limits input sample format to U8, S16, and S32.
3840 32-bit floating-point; this limits input sample format to FLT. (default)
3842 64-bit floating-point; this limits input sample format to DBL.
3846 Choose the behaviour on encountering ReplayGain side data in input frames.
3850 Remove ReplayGain side data, ignoring its contents (the default).
3853 Ignore ReplayGain side data, but leave it in the frame.
3856 Prefer the track gain, if present.
3859 Prefer the album gain, if present.
3862 @item replaygain_preamp
3863 Pre-amplification gain in dB to apply to the selected replaygain gain.
3865 Default value for @var{replaygain_preamp} is 0.0.
3868 Set when the volume expression is evaluated.
3870 It accepts the following values:
3873 only evaluate expression once during the filter initialization, or
3874 when the @samp{volume} command is sent
3877 evaluate expression for each incoming frame
3880 Default value is @samp{once}.
3883 The volume expression can contain the following parameters.
3887 frame number (starting at zero)
3890 @item nb_consumed_samples
3891 number of samples consumed by the filter
3893 number of samples in the current frame
3895 original frame position in the file
3901 PTS at start of stream
3903 time at start of stream
3909 last set volume value
3912 Note that when @option{eval} is set to @samp{once} only the
3913 @var{sample_rate} and @var{tb} variables are available, all other
3914 variables will evaluate to NAN.
3916 @subsection Commands
3918 This filter supports the following commands:
3921 Modify the volume expression.
3922 The command accepts the same syntax of the corresponding option.
3924 If the specified expression is not valid, it is kept at its current
3926 @item replaygain_noclip
3927 Prevent clipping by limiting the gain applied.
3929 Default value for @var{replaygain_noclip} is 1.
3933 @subsection Examples
3937 Halve the input audio volume:
3941 volume=volume=-6.0206dB
3944 In all the above example the named key for @option{volume} can be
3945 omitted, for example like in:
3951 Increase input audio power by 6 decibels using fixed-point precision:
3953 volume=volume=6dB:precision=fixed
3957 Fade volume after time 10 with an annihilation period of 5 seconds:
3959 volume='if(lt(t,10),1,max(1-(t-10)/5,0))':eval=frame
3963 @section volumedetect
3965 Detect the volume of the input video.
3967 The filter has no parameters. The input is not modified. Statistics about
3968 the volume will be printed in the log when the input stream end is reached.
3970 In particular it will show the mean volume (root mean square), maximum
3971 volume (on a per-sample basis), and the beginning of a histogram of the
3972 registered volume values (from the maximum value to a cumulated 1/1000 of
3975 All volumes are in decibels relative to the maximum PCM value.
3977 @subsection Examples
3979 Here is an excerpt of the output:
3981 [Parsed_volumedetect_0 @ 0xa23120] mean_volume: -27 dB
3982 [Parsed_volumedetect_0 @ 0xa23120] max_volume: -4 dB
3983 [Parsed_volumedetect_0 @ 0xa23120] histogram_4db: 6
3984 [Parsed_volumedetect_0 @ 0xa23120] histogram_5db: 62
3985 [Parsed_volumedetect_0 @ 0xa23120] histogram_6db: 286
3986 [Parsed_volumedetect_0 @ 0xa23120] histogram_7db: 1042
3987 [Parsed_volumedetect_0 @ 0xa23120] histogram_8db: 2551
3988 [Parsed_volumedetect_0 @ 0xa23120] histogram_9db: 4609
3989 [Parsed_volumedetect_0 @ 0xa23120] histogram_10db: 8409
3995 The mean square energy is approximately -27 dB, or 10^-2.7.
3997 The largest sample is at -4 dB, or more precisely between -4 dB and -5 dB.
3999 There are 6 samples at -4 dB, 62 at -5 dB, 286 at -6 dB, etc.
4002 In other words, raising the volume by +4 dB does not cause any clipping,
4003 raising it by +5 dB causes clipping for 6 samples, etc.
4005 @c man end AUDIO FILTERS
4007 @chapter Audio Sources
4008 @c man begin AUDIO SOURCES
4010 Below is a description of the currently available audio sources.
4014 Buffer audio frames, and make them available to the filter chain.
4016 This source is mainly intended for a programmatic use, in particular
4017 through the interface defined in @file{libavfilter/asrc_abuffer.h}.
4019 It accepts the following parameters:
4023 The timebase which will be used for timestamps of submitted frames. It must be
4024 either a floating-point number or in @var{numerator}/@var{denominator} form.
4027 The sample rate of the incoming audio buffers.
4030 The sample format of the incoming audio buffers.
4031 Either a sample format name or its corresponding integer representation from
4032 the enum AVSampleFormat in @file{libavutil/samplefmt.h}
4034 @item channel_layout
4035 The channel layout of the incoming audio buffers.
4036 Either a channel layout name from channel_layout_map in
4037 @file{libavutil/channel_layout.c} or its corresponding integer representation
4038 from the AV_CH_LAYOUT_* macros in @file{libavutil/channel_layout.h}
4041 The number of channels of the incoming audio buffers.
4042 If both @var{channels} and @var{channel_layout} are specified, then they
4047 @subsection Examples
4050 abuffer=sample_rate=44100:sample_fmt=s16p:channel_layout=stereo
4053 will instruct the source to accept planar 16bit signed stereo at 44100Hz.
4054 Since the sample format with name "s16p" corresponds to the number
4055 6 and the "stereo" channel layout corresponds to the value 0x3, this is
4058 abuffer=sample_rate=44100:sample_fmt=6:channel_layout=0x3
4063 Generate an audio signal specified by an expression.
4065 This source accepts in input one or more expressions (one for each
4066 channel), which are evaluated and used to generate a corresponding
4069 This source accepts the following options:
4073 Set the '|'-separated expressions list for each separate channel. In case the
4074 @option{channel_layout} option is not specified, the selected channel layout
4075 depends on the number of provided expressions. Otherwise the last
4076 specified expression is applied to the remaining output channels.
4078 @item channel_layout, c
4079 Set the channel layout. The number of channels in the specified layout
4080 must be equal to the number of specified expressions.
4083 Set the minimum duration of the sourced audio. See
4084 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
4085 for the accepted syntax.
4086 Note that the resulting duration may be greater than the specified
4087 duration, as the generated audio is always cut at the end of a
4090 If not specified, or the expressed duration is negative, the audio is
4091 supposed to be generated forever.
4094 Set the number of samples per channel per each output frame,
4097 @item sample_rate, s
4098 Specify the sample rate, default to 44100.
4101 Each expression in @var{exprs} can contain the following constants:
4105 number of the evaluated sample, starting from 0
4108 time of the evaluated sample expressed in seconds, starting from 0
4115 @subsection Examples
4125 Generate a sin signal with frequency of 440 Hz, set sample rate to
4128 aevalsrc="sin(440*2*PI*t):s=8000"
4132 Generate a two channels signal, specify the channel layout (Front
4133 Center + Back Center) explicitly:
4135 aevalsrc="sin(420*2*PI*t)|cos(430*2*PI*t):c=FC|BC"
4139 Generate white noise:
4141 aevalsrc="-2+random(0)"
4145 Generate an amplitude modulated signal:
4147 aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)"
4151 Generate 2.5 Hz binaural beats on a 360 Hz carrier:
4153 aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) | 0.1*sin(2*PI*(360+2.5/2)*t)"
4160 The null audio source, return unprocessed audio frames. It is mainly useful
4161 as a template and to be employed in analysis / debugging tools, or as
4162 the source for filters which ignore the input data (for example the sox
4165 This source accepts the following options:
4169 @item channel_layout, cl
4171 Specifies the channel layout, and can be either an integer or a string
4172 representing a channel layout. The default value of @var{channel_layout}
4175 Check the channel_layout_map definition in
4176 @file{libavutil/channel_layout.c} for the mapping between strings and
4177 channel layout values.
4179 @item sample_rate, r
4180 Specifies the sample rate, and defaults to 44100.
4183 Set the number of samples per requested frames.
4187 @subsection Examples
4191 Set the sample rate to 48000 Hz and the channel layout to AV_CH_LAYOUT_MONO.
4193 anullsrc=r=48000:cl=4
4197 Do the same operation with a more obvious syntax:
4199 anullsrc=r=48000:cl=mono
4203 All the parameters need to be explicitly defined.
4207 Synthesize a voice utterance using the libflite library.
4209 To enable compilation of this filter you need to configure FFmpeg with
4210 @code{--enable-libflite}.
4212 Note that the flite library is not thread-safe.
4214 The filter accepts the following options:
4219 If set to 1, list the names of the available voices and exit
4220 immediately. Default value is 0.
4223 Set the maximum number of samples per frame. Default value is 512.
4226 Set the filename containing the text to speak.
4229 Set the text to speak.
4232 Set the voice to use for the speech synthesis. Default value is
4233 @code{kal}. See also the @var{list_voices} option.
4236 @subsection Examples
4240 Read from file @file{speech.txt}, and synthesize the text using the
4241 standard flite voice:
4243 flite=textfile=speech.txt
4247 Read the specified text selecting the @code{slt} voice:
4249 flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
4253 Input text to ffmpeg:
4255 ffmpeg -f lavfi -i flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
4259 Make @file{ffplay} speak the specified text, using @code{flite} and
4260 the @code{lavfi} device:
4262 ffplay -f lavfi flite=text='No more be grieved for which that thou hast done.'
4266 For more information about libflite, check:
4267 @url{http://www.speech.cs.cmu.edu/flite/}
4271 Generate a noise audio signal.
4273 The filter accepts the following options:
4276 @item sample_rate, r
4277 Specify the sample rate. Default value is 48000 Hz.
4280 Specify the amplitude (0.0 - 1.0) of the generated audio stream. Default value
4284 Specify the duration of the generated audio stream. Not specifying this option
4285 results in noise with an infinite length.
4287 @item color, colour, c
4288 Specify the color of noise. Available noise colors are white, pink, and brown.
4289 Default color is white.
4292 Specify a value used to seed the PRNG.
4295 Set the number of samples per each output frame, default is 1024.
4298 @subsection Examples
4303 Generate 60 seconds of pink noise, with a 44.1 kHz sampling rate and an amplitude of 0.5:
4305 anoisesrc=d=60:c=pink:r=44100:a=0.5
4311 Generate an audio signal made of a sine wave with amplitude 1/8.
4313 The audio signal is bit-exact.
4315 The filter accepts the following options:
4320 Set the carrier frequency. Default is 440 Hz.
4322 @item beep_factor, b
4323 Enable a periodic beep every second with frequency @var{beep_factor} times
4324 the carrier frequency. Default is 0, meaning the beep is disabled.
4326 @item sample_rate, r
4327 Specify the sample rate, default is 44100.
4330 Specify the duration of the generated audio stream.
4332 @item samples_per_frame
4333 Set the number of samples per output frame.
4335 The expression can contain the following constants:
4339 The (sequential) number of the output audio frame, starting from 0.
4342 The PTS (Presentation TimeStamp) of the output audio frame,
4343 expressed in @var{TB} units.
4346 The PTS of the output audio frame, expressed in seconds.
4349 The timebase of the output audio frames.
4352 Default is @code{1024}.
4355 @subsection Examples
4360 Generate a simple 440 Hz sine wave:
4366 Generate a 220 Hz sine wave with a 880 Hz beep each second, for 5 seconds:
4370 sine=frequency=220:beep_factor=4:duration=5
4374 Generate a 1 kHz sine wave following @code{1602,1601,1602,1601,1602} NTSC
4377 sine=1000:samples_per_frame='st(0,mod(n,5)); 1602-not(not(eq(ld(0),1)+eq(ld(0),3)))'
4381 @c man end AUDIO SOURCES
4383 @chapter Audio Sinks
4384 @c man begin AUDIO SINKS
4386 Below is a description of the currently available audio sinks.
4388 @section abuffersink
4390 Buffer audio frames, and make them available to the end of filter chain.
4392 This sink is mainly intended for programmatic use, in particular
4393 through the interface defined in @file{libavfilter/buffersink.h}
4394 or the options system.
4396 It accepts a pointer to an AVABufferSinkContext structure, which
4397 defines the incoming buffers' formats, to be passed as the opaque
4398 parameter to @code{avfilter_init_filter} for initialization.
4401 Null audio sink; do absolutely nothing with the input audio. It is
4402 mainly useful as a template and for use in analysis / debugging
4405 @c man end AUDIO SINKS
4407 @chapter Video Filters
4408 @c man begin VIDEO FILTERS
4410 When you configure your FFmpeg build, you can disable any of the
4411 existing filters using @code{--disable-filters}.
4412 The configure output will show the video filters included in your
4415 Below is a description of the currently available video filters.
4417 @section alphaextract
4419 Extract the alpha component from the input as a grayscale video. This
4420 is especially useful with the @var{alphamerge} filter.
4424 Add or replace the alpha component of the primary input with the
4425 grayscale value of a second input. This is intended for use with
4426 @var{alphaextract} to allow the transmission or storage of frame
4427 sequences that have alpha in a format that doesn't support an alpha
4430 For example, to reconstruct full frames from a normal YUV-encoded video
4431 and a separate video created with @var{alphaextract}, you might use:
4433 movie=in_alpha.mkv [alpha]; [in][alpha] alphamerge [out]
4436 Since this filter is designed for reconstruction, it operates on frame
4437 sequences without considering timestamps, and terminates when either
4438 input reaches end of stream. This will cause problems if your encoding
4439 pipeline drops frames. If you're trying to apply an image as an
4440 overlay to a video stream, consider the @var{overlay} filter instead.
4444 Same as the @ref{subtitles} filter, except that it doesn't require libavcodec
4445 and libavformat to work. On the other hand, it is limited to ASS (Advanced
4446 Substation Alpha) subtitles files.
4448 This filter accepts the following option in addition to the common options from
4449 the @ref{subtitles} filter:
4453 Set the shaping engine
4455 Available values are:
4458 The default libass shaping engine, which is the best available.
4460 Fast, font-agnostic shaper that can do only substitutions
4462 Slower shaper using OpenType for substitutions and positioning
4465 The default is @code{auto}.
4469 Apply an Adaptive Temporal Averaging Denoiser to the video input.
4471 The filter accepts the following options:
4475 Set threshold A for 1st plane. Default is 0.02.
4476 Valid range is 0 to 0.3.
4479 Set threshold B for 1st plane. Default is 0.04.
4480 Valid range is 0 to 5.
4483 Set threshold A for 2nd plane. Default is 0.02.
4484 Valid range is 0 to 0.3.
4487 Set threshold B for 2nd plane. Default is 0.04.
4488 Valid range is 0 to 5.
4491 Set threshold A for 3rd plane. Default is 0.02.
4492 Valid range is 0 to 0.3.
4495 Set threshold B for 3rd plane. Default is 0.04.
4496 Valid range is 0 to 5.
4498 Threshold A is designed to react on abrupt changes in the input signal and
4499 threshold B is designed to react on continuous changes in the input signal.
4502 Set number of frames filter will use for averaging. Default is 33. Must be odd
4503 number in range [5, 129].
4506 Set what planes of frame filter will use for averaging. Default is all.
4511 Apply average blur filter.
4513 The filter accepts the following options:
4517 Set horizontal kernel size.
4520 Set which planes to filter. By default all planes are filtered.
4523 Set vertical kernel size, if zero it will be same as @code{sizeX}.
4524 Default is @code{0}.
4529 Compute the bounding box for the non-black pixels in the input frame
4532 This filter computes the bounding box containing all the pixels with a
4533 luminance value greater than the minimum allowed value.
4534 The parameters describing the bounding box are printed on the filter
4537 The filter accepts the following option:
4541 Set the minimal luminance value. Default is @code{16}.
4544 @section bitplanenoise
4546 Show and measure bit plane noise.
4548 The filter accepts the following options:
4552 Set which plane to analyze. Default is @code{1}.
4555 Filter out noisy pixels from @code{bitplane} set above.
4556 Default is disabled.
4559 @section blackdetect
4561 Detect video intervals that are (almost) completely black. Can be
4562 useful to detect chapter transitions, commercials, or invalid
4563 recordings. Output lines contains the time for the start, end and
4564 duration of the detected black interval expressed in seconds.
4566 In order to display the output lines, you need to set the loglevel at
4567 least to the AV_LOG_INFO value.
4569 The filter accepts the following options:
4572 @item black_min_duration, d
4573 Set the minimum detected black duration expressed in seconds. It must
4574 be a non-negative floating point number.
4576 Default value is 2.0.
4578 @item picture_black_ratio_th, pic_th
4579 Set the threshold for considering a picture "black".
4580 Express the minimum value for the ratio:
4582 @var{nb_black_pixels} / @var{nb_pixels}
4585 for which a picture is considered black.
4586 Default value is 0.98.
4588 @item pixel_black_th, pix_th
4589 Set the threshold for considering a pixel "black".
4591 The threshold expresses the maximum pixel luminance value for which a
4592 pixel is considered "black". The provided value is scaled according to
4593 the following equation:
4595 @var{absolute_threshold} = @var{luminance_minimum_value} + @var{pixel_black_th} * @var{luminance_range_size}
4598 @var{luminance_range_size} and @var{luminance_minimum_value} depend on
4599 the input video format, the range is [0-255] for YUV full-range
4600 formats and [16-235] for YUV non full-range formats.
4602 Default value is 0.10.
4605 The following example sets the maximum pixel threshold to the minimum
4606 value, and detects only black intervals of 2 or more seconds:
4608 blackdetect=d=2:pix_th=0.00
4613 Detect frames that are (almost) completely black. Can be useful to
4614 detect chapter transitions or commercials. Output lines consist of
4615 the frame number of the detected frame, the percentage of blackness,
4616 the position in the file if known or -1 and the timestamp in seconds.
4618 In order to display the output lines, you need to set the loglevel at
4619 least to the AV_LOG_INFO value.
4621 This filter exports frame metadata @code{lavfi.blackframe.pblack}.
4622 The value represents the percentage of pixels in the picture that
4623 are below the threshold value.
4625 It accepts the following parameters:
4630 The percentage of the pixels that have to be below the threshold; it defaults to
4633 @item threshold, thresh
4634 The threshold below which a pixel value is considered black; it defaults to
4639 @section blend, tblend
4641 Blend two video frames into each other.
4643 The @code{blend} filter takes two input streams and outputs one
4644 stream, the first input is the "top" layer and second input is
4645 "bottom" layer. By default, the output terminates when the longest input terminates.
4647 The @code{tblend} (time blend) filter takes two consecutive frames
4648 from one single stream, and outputs the result obtained by blending
4649 the new frame on top of the old frame.
4651 A description of the accepted options follows.
4659 Set blend mode for specific pixel component or all pixel components in case
4660 of @var{all_mode}. Default value is @code{normal}.
4662 Available values for component modes are:
4703 Set blend opacity for specific pixel component or all pixel components in case
4704 of @var{all_opacity}. Only used in combination with pixel component blend modes.
4711 Set blend expression for specific pixel component or all pixel components in case
4712 of @var{all_expr}. Note that related mode options will be ignored if those are set.
4714 The expressions can use the following variables:
4718 The sequential number of the filtered frame, starting from @code{0}.
4722 the coordinates of the current sample
4726 the width and height of currently filtered plane
4730 Width and height scale depending on the currently filtered plane. It is the
4731 ratio between the corresponding luma plane number of pixels and the current
4732 plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and
4733 @code{0.5,0.5} for chroma planes.
4736 Time of the current frame, expressed in seconds.
4739 Value of pixel component at current location for first video frame (top layer).
4742 Value of pixel component at current location for second video frame (bottom layer).
4746 Force termination when the shortest input terminates. Default is
4747 @code{0}. This option is only defined for the @code{blend} filter.
4750 Continue applying the last bottom frame after the end of the stream. A value of
4751 @code{0} disable the filter after the last frame of the bottom layer is reached.
4752 Default is @code{1}. This option is only defined for the @code{blend} filter.
4755 @subsection Examples
4759 Apply transition from bottom layer to top layer in first 10 seconds:
4761 blend=all_expr='A*(if(gte(T,10),1,T/10))+B*(1-(if(gte(T,10),1,T/10)))'
4765 Apply 1x1 checkerboard effect:
4767 blend=all_expr='if(eq(mod(X,2),mod(Y,2)),A,B)'
4771 Apply uncover left effect:
4773 blend=all_expr='if(gte(N*SW+X,W),A,B)'
4777 Apply uncover down effect:
4779 blend=all_expr='if(gte(Y-N*SH,0),A,B)'
4783 Apply uncover up-left effect:
4785 blend=all_expr='if(gte(T*SH*40+Y,H)*gte((T*40*SW+X)*W/H,W),A,B)'
4789 Split diagonally video and shows top and bottom layer on each side:
4791 blend=all_expr=if(gt(X,Y*(W/H)),A,B)
4795 Display differences between the current and the previous frame:
4797 tblend=all_mode=difference128
4803 Apply a boxblur algorithm to the input video.
4805 It accepts the following parameters:
4809 @item luma_radius, lr
4810 @item luma_power, lp
4811 @item chroma_radius, cr
4812 @item chroma_power, cp
4813 @item alpha_radius, ar
4814 @item alpha_power, ap
4818 A description of the accepted options follows.
4821 @item luma_radius, lr
4822 @item chroma_radius, cr
4823 @item alpha_radius, ar
4824 Set an expression for the box radius in pixels used for blurring the
4825 corresponding input plane.
4827 The radius value must be a non-negative number, and must not be
4828 greater than the value of the expression @code{min(w,h)/2} for the
4829 luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma
4832 Default value for @option{luma_radius} is "2". If not specified,
4833 @option{chroma_radius} and @option{alpha_radius} default to the
4834 corresponding value set for @option{luma_radius}.
4836 The expressions can contain the following constants:
4840 The input width and height in pixels.
4844 The input chroma image width and height in pixels.
4848 The horizontal and vertical chroma subsample values. For example, for the
4849 pixel format "yuv422p", @var{hsub} is 2 and @var{vsub} is 1.
4852 @item luma_power, lp
4853 @item chroma_power, cp
4854 @item alpha_power, ap
4855 Specify how many times the boxblur filter is applied to the
4856 corresponding plane.
4858 Default value for @option{luma_power} is 2. If not specified,
4859 @option{chroma_power} and @option{alpha_power} default to the
4860 corresponding value set for @option{luma_power}.
4862 A value of 0 will disable the effect.
4865 @subsection Examples
4869 Apply a boxblur filter with the luma, chroma, and alpha radii
4872 boxblur=luma_radius=2:luma_power=1
4877 Set the luma radius to 2, and alpha and chroma radius to 0:
4879 boxblur=2:1:cr=0:ar=0
4883 Set the luma and chroma radii to a fraction of the video dimension:
4885 boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1
4891 Deinterlace the input video ("bwdif" stands for "Bob Weaver
4892 Deinterlacing Filter").
4894 Motion adaptive deinterlacing based on yadif with the use of w3fdif and cubic
4895 interpolation algorithms.
4896 It accepts the following parameters:
4900 The interlacing mode to adopt. It accepts one of the following values:
4904 Output one frame for each frame.
4906 Output one frame for each field.
4909 The default value is @code{send_field}.
4912 The picture field parity assumed for the input interlaced video. It accepts one
4913 of the following values:
4917 Assume the top field is first.
4919 Assume the bottom field is first.
4921 Enable automatic detection of field parity.
4924 The default value is @code{auto}.
4925 If the interlacing is unknown or the decoder does not export this information,
4926 top field first will be assumed.
4929 Specify which frames to deinterlace. Accept one of the following
4934 Deinterlace all frames.
4936 Only deinterlace frames marked as interlaced.
4939 The default value is @code{all}.
4943 YUV colorspace color/chroma keying.
4945 The filter accepts the following options:
4949 The color which will be replaced with transparency.
4952 Similarity percentage with the key color.
4954 0.01 matches only the exact key color, while 1.0 matches everything.
4959 0.0 makes pixels either fully transparent, or not transparent at all.
4961 Higher values result in semi-transparent pixels, with a higher transparency
4962 the more similar the pixels color is to the key color.
4965 Signals that the color passed is already in YUV instead of RGB.
4967 Litteral colors like "green" or "red" don't make sense with this enabled anymore.
4968 This can be used to pass exact YUV values as hexadecimal numbers.
4971 @subsection Examples
4975 Make every green pixel in the input image transparent:
4977 ffmpeg -i input.png -vf chromakey=green out.png
4981 Overlay a greenscreen-video on top of a static black background.
4983 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
4989 Display CIE color diagram with pixels overlaid onto it.
4991 The filter accepts the following options:
5006 @item uhdtv, rec2020
5019 Set what gamuts to draw.
5021 See @code{system} option for available values.
5024 Set ciescope size, by default set to 512.
5027 Set intensity used to map input pixel values to CIE diagram.
5030 Set contrast used to draw tongue colors that are out of active color system gamut.
5033 Correct gamma displayed on scope, by default enabled.
5036 Show white point on CIE diagram, by default disabled.
5039 Set input gamma. Used only with XYZ input color space.
5044 Visualize information exported by some codecs.
5046 Some codecs can export information through frames using side-data or other
5047 means. For example, some MPEG based codecs export motion vectors through the
5048 @var{export_mvs} flag in the codec @option{flags2} option.
5050 The filter accepts the following option:
5054 Set motion vectors to visualize.
5056 Available flags for @var{mv} are:
5060 forward predicted MVs of P-frames
5062 forward predicted MVs of B-frames
5064 backward predicted MVs of B-frames
5068 Display quantization parameters using the chroma planes.
5071 Set motion vectors type to visualize. Includes MVs from all frames unless specified by @var{frame_type} option.
5073 Available flags for @var{mv_type} are:
5077 forward predicted MVs
5079 backward predicted MVs
5082 @item frame_type, ft
5083 Set frame type to visualize motion vectors of.
5085 Available flags for @var{frame_type} are:
5089 intra-coded frames (I-frames)
5091 predicted frames (P-frames)
5093 bi-directionally predicted frames (B-frames)
5097 @subsection Examples
5101 Visualize forward predicted MVs of all frames using @command{ffplay}:
5103 ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv_type=fp
5107 Visualize multi-directionals MVs of P and B-Frames using @command{ffplay}:
5109 ffplay -flags2 +export_mvs input.mp4 -vf codecview=mv=pf+bf+bb
5113 @section colorbalance
5114 Modify intensity of primary colors (red, green and blue) of input frames.
5116 The filter allows an input frame to be adjusted in the shadows, midtones or highlights
5117 regions for the red-cyan, green-magenta or blue-yellow balance.
5119 A positive adjustment value shifts the balance towards the primary color, a negative
5120 value towards the complementary color.
5122 The filter accepts the following options:
5128 Adjust red, green and blue shadows (darkest pixels).
5133 Adjust red, green and blue midtones (medium pixels).
5138 Adjust red, green and blue highlights (brightest pixels).
5140 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
5143 @subsection Examples
5147 Add red color cast to shadows:
5154 RGB colorspace color keying.
5156 The filter accepts the following options:
5160 The color which will be replaced with transparency.
5163 Similarity percentage with the key color.
5165 0.01 matches only the exact key color, while 1.0 matches everything.
5170 0.0 makes pixels either fully transparent, or not transparent at all.
5172 Higher values result in semi-transparent pixels, with a higher transparency
5173 the more similar the pixels color is to the key color.
5176 @subsection Examples
5180 Make every green pixel in the input image transparent:
5182 ffmpeg -i input.png -vf colorkey=green out.png
5186 Overlay a greenscreen-video on top of a static background image.
5188 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
5192 @section colorlevels
5194 Adjust video input frames using levels.
5196 The filter accepts the following options:
5203 Adjust red, green, blue and alpha input black point.
5204 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
5210 Adjust red, green, blue and alpha input white point.
5211 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{1}.
5213 Input levels are used to lighten highlights (bright tones), darken shadows
5214 (dark tones), change the balance of bright and dark tones.
5220 Adjust red, green, blue and alpha output black point.
5221 Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{0}.
5227 Adjust red, green, blue and alpha output white point.
5228 Allowed ranges for options are @code{[0, 1.0]}. Defaults are @code{1}.
5230 Output levels allows manual selection of a constrained output level range.
5233 @subsection Examples
5237 Make video output darker:
5239 colorlevels=rimin=0.058:gimin=0.058:bimin=0.058
5245 colorlevels=rimin=0.039:gimin=0.039:bimin=0.039:rimax=0.96:gimax=0.96:bimax=0.96
5249 Make video output lighter:
5251 colorlevels=rimax=0.902:gimax=0.902:bimax=0.902
5255 Increase brightness:
5257 colorlevels=romin=0.5:gomin=0.5:bomin=0.5
5261 @section colorchannelmixer
5263 Adjust video input frames by re-mixing color channels.
5265 This filter modifies a color channel by adding the values associated to
5266 the other channels of the same pixels. For example if the value to
5267 modify is red, the output value will be:
5269 @var{red}=@var{red}*@var{rr} + @var{blue}*@var{rb} + @var{green}*@var{rg} + @var{alpha}*@var{ra}
5272 The filter accepts the following options:
5279 Adjust contribution of input red, green, blue and alpha channels for output red channel.
5280 Default is @code{1} for @var{rr}, and @code{0} for @var{rg}, @var{rb} and @var{ra}.
5286 Adjust contribution of input red, green, blue and alpha channels for output green channel.
5287 Default is @code{1} for @var{gg}, and @code{0} for @var{gr}, @var{gb} and @var{ga}.
5293 Adjust contribution of input red, green, blue and alpha channels for output blue channel.
5294 Default is @code{1} for @var{bb}, and @code{0} for @var{br}, @var{bg} and @var{ba}.
5300 Adjust contribution of input red, green, blue and alpha channels for output alpha channel.
5301 Default is @code{1} for @var{aa}, and @code{0} for @var{ar}, @var{ag} and @var{ab}.
5303 Allowed ranges for options are @code{[-2.0, 2.0]}.
5306 @subsection Examples
5310 Convert source to grayscale:
5312 colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3
5315 Simulate sepia tones:
5317 colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131
5321 @section colormatrix
5323 Convert color matrix.
5325 The filter accepts the following options:
5330 Specify the source and destination color matrix. Both values must be
5333 The accepted values are:
5361 For example to convert from BT.601 to SMPTE-240M, use the command:
5363 colormatrix=bt601:smpte240m
5368 Convert colorspace, transfer characteristics or color primaries.
5369 Input video needs to have an even size.
5371 The filter accepts the following options:
5376 Specify all color properties at once.
5378 The accepted values are:
5408 Specify output colorspace.
5410 The accepted values are:
5419 BT.470BG or BT.601-6 625
5422 SMPTE-170M or BT.601-6 525
5431 BT.2020 with non-constant luminance
5437 Specify output transfer characteristics.
5439 The accepted values are:
5451 Constant gamma of 2.2
5454 Constant gamma of 2.8
5457 SMPTE-170M, BT.601-6 625 or BT.601-6 525
5475 BT.2020 for 10-bits content
5478 BT.2020 for 12-bits content
5484 Specify output color primaries.
5486 The accepted values are:
5495 BT.470BG or BT.601-6 625
5498 SMPTE-170M or BT.601-6 525
5519 Specify output color range.
5521 The accepted values are:
5524 TV (restricted) range
5527 MPEG (restricted) range
5538 Specify output color format.
5540 The accepted values are:
5543 YUV 4:2:0 planar 8-bits
5546 YUV 4:2:0 planar 10-bits
5549 YUV 4:2:0 planar 12-bits
5552 YUV 4:2:2 planar 8-bits
5555 YUV 4:2:2 planar 10-bits
5558 YUV 4:2:2 planar 12-bits
5561 YUV 4:4:4 planar 8-bits
5564 YUV 4:4:4 planar 10-bits
5567 YUV 4:4:4 planar 12-bits
5572 Do a fast conversion, which skips gamma/primary correction. This will take
5573 significantly less CPU, but will be mathematically incorrect. To get output
5574 compatible with that produced by the colormatrix filter, use fast=1.
5577 Specify dithering mode.
5579 The accepted values are:
5585 Floyd-Steinberg dithering
5589 Whitepoint adaptation mode.
5591 The accepted values are:
5594 Bradford whitepoint adaptation
5597 von Kries whitepoint adaptation
5600 identity whitepoint adaptation (i.e. no whitepoint adaptation)
5604 Override all input properties at once. Same accepted values as @ref{all}.
5607 Override input colorspace. Same accepted values as @ref{space}.
5610 Override input color primaries. Same accepted values as @ref{primaries}.
5613 Override input transfer characteristics. Same accepted values as @ref{trc}.
5616 Override input color range. Same accepted values as @ref{range}.
5620 The filter converts the transfer characteristics, color space and color
5621 primaries to the specified user values. The output value, if not specified,
5622 is set to a default value based on the "all" property. If that property is
5623 also not specified, the filter will log an error. The output color range and
5624 format default to the same value as the input color range and format. The
5625 input transfer characteristics, color space, color primaries and color range
5626 should be set on the input data. If any of these are missing, the filter will
5627 log an error and no conversion will take place.
5629 For example to convert the input to SMPTE-240M, use the command:
5631 colorspace=smpte240m
5634 @section convolution
5636 Apply convolution 3x3 or 5x5 filter.
5638 The filter accepts the following options:
5645 Set matrix for each plane.
5646 Matrix is sequence of 9 or 25 signed integers.
5652 Set multiplier for calculated value for each plane.
5658 Set bias for each plane. This value is added to the result of the multiplication.
5659 Useful for making the overall image brighter or darker. Default is 0.0.
5662 @subsection Examples
5668 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"
5674 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"
5680 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"
5686 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"
5692 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"
5698 Copy the input video source unchanged to the output. This is mainly useful for
5703 Video filtering on GPU using Apple's CoreImage API on OSX.
5705 Hardware acceleration is based on an OpenGL context. Usually, this means it is
5706 processed by video hardware. However, software-based OpenGL implementations
5707 exist which means there is no guarantee for hardware processing. It depends on
5710 There are many filters and image generators provided by Apple that come with a
5711 large variety of options. The filter has to be referenced by its name along
5714 The coreimage filter accepts the following options:
5717 List all available filters and generators along with all their respective
5718 options as well as possible minimum and maximum values along with the default
5725 Specify all filters by their respective name and options.
5726 Use @var{list_filters} to determine all valid filter names and options.
5727 Numerical options are specified by a float value and are automatically clamped
5728 to their respective value range. Vector and color options have to be specified
5729 by a list of space separated float values. Character escaping has to be done.
5730 A special option name @code{default} is available to use default options for a
5733 It is required to specify either @code{default} or at least one of the filter options.
5734 All omitted options are used with their default values.
5735 The syntax of the filter string is as follows:
5737 filter=<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...][#<NAME>@@<OPTION>=<VALUE>[@@<OPTION>=<VALUE>][@@...]][#...]
5741 Specify a rectangle where the output of the filter chain is copied into the
5742 input image. It is given by a list of space separated float values:
5744 output_rect=x\ y\ width\ height
5746 If not given, the output rectangle equals the dimensions of the input image.
5747 The output rectangle is automatically cropped at the borders of the input
5748 image. Negative values are valid for each component.
5750 output_rect=25\ 25\ 100\ 100
5754 Several filters can be chained for successive processing without GPU-HOST
5755 transfers allowing for fast processing of complex filter chains.
5756 Currently, only filters with zero (generators) or exactly one (filters) input
5757 image and one output image are supported. Also, transition filters are not yet
5760 Some filters generate output images with additional padding depending on the
5761 respective filter kernel. The padding is automatically removed to ensure the
5762 filter output has the same size as the input image.
5764 For image generators, the size of the output image is determined by the
5765 previous output image of the filter chain or the input image of the whole
5766 filterchain, respectively. The generators do not use the pixel information of
5767 this image to generate their output. However, the generated output is
5768 blended onto this image, resulting in partial or complete coverage of the
5771 The @ref{coreimagesrc} video source can be used for generating input images
5772 which are directly fed into the filter chain. By using it, providing input
5773 images by another video source or an input video is not required.
5775 @subsection Examples
5780 List all filters available:
5782 coreimage=list_filters=true
5786 Use the CIBoxBlur filter with default options to blur an image:
5788 coreimage=filter=CIBoxBlur@@default
5792 Use a filter chain with CISepiaTone at default values and CIVignetteEffect with
5793 its center at 100x100 and a radius of 50 pixels:
5795 coreimage=filter=CIBoxBlur@@default#CIVignetteEffect@@inputCenter=100\ 100@@inputRadius=50
5799 Use nullsrc and CIQRCodeGenerator to create a QR code for the FFmpeg homepage,
5800 given as complete and escaped command-line for Apple's standard bash shell:
5802 ffmpeg -f lavfi -i nullsrc=s=100x100,coreimage=filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png
5808 Crop the input video to given dimensions.
5810 It accepts the following parameters:
5814 The width of the output video. It defaults to @code{iw}.
5815 This expression is evaluated only once during the filter
5816 configuration, or when the @samp{w} or @samp{out_w} command is sent.
5819 The height of the output video. It defaults to @code{ih}.
5820 This expression is evaluated only once during the filter
5821 configuration, or when the @samp{h} or @samp{out_h} command is sent.
5824 The horizontal position, in the input video, of the left edge of the output
5825 video. It defaults to @code{(in_w-out_w)/2}.
5826 This expression is evaluated per-frame.
5829 The vertical position, in the input video, of the top edge of the output video.
5830 It defaults to @code{(in_h-out_h)/2}.
5831 This expression is evaluated per-frame.
5834 If set to 1 will force the output display aspect ratio
5835 to be the same of the input, by changing the output sample aspect
5836 ratio. It defaults to 0.
5839 Enable exact cropping. If enabled, subsampled videos will be cropped at exact
5840 width/height/x/y as specified and will not be rounded to nearest smaller value.
5844 The @var{out_w}, @var{out_h}, @var{x}, @var{y} parameters are
5845 expressions containing the following constants:
5850 The computed values for @var{x} and @var{y}. They are evaluated for
5855 The input width and height.
5859 These are the same as @var{in_w} and @var{in_h}.
5863 The output (cropped) width and height.
5867 These are the same as @var{out_w} and @var{out_h}.
5870 same as @var{iw} / @var{ih}
5873 input sample aspect ratio
5876 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
5880 horizontal and vertical chroma subsample values. For example for the
5881 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
5884 The number of the input frame, starting from 0.
5887 the position in the file of the input frame, NAN if unknown
5890 The timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
5894 The expression for @var{out_w} may depend on the value of @var{out_h},
5895 and the expression for @var{out_h} may depend on @var{out_w}, but they
5896 cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are
5897 evaluated after @var{out_w} and @var{out_h}.
5899 The @var{x} and @var{y} parameters specify the expressions for the
5900 position of the top-left corner of the output (non-cropped) area. They
5901 are evaluated for each frame. If the evaluated value is not valid, it
5902 is approximated to the nearest valid value.
5904 The expression for @var{x} may depend on @var{y}, and the expression
5905 for @var{y} may depend on @var{x}.
5907 @subsection Examples
5911 Crop area with size 100x100 at position (12,34).
5916 Using named options, the example above becomes:
5918 crop=w=100:h=100:x=12:y=34
5922 Crop the central input area with size 100x100:
5928 Crop the central input area with size 2/3 of the input video:
5930 crop=2/3*in_w:2/3*in_h
5934 Crop the input video central square:
5941 Delimit the rectangle with the top-left corner placed at position
5942 100:100 and the right-bottom corner corresponding to the right-bottom
5943 corner of the input image.
5945 crop=in_w-100:in_h-100:100:100
5949 Crop 10 pixels from the left and right borders, and 20 pixels from
5950 the top and bottom borders
5952 crop=in_w-2*10:in_h-2*20
5956 Keep only the bottom right quarter of the input image:
5958 crop=in_w/2:in_h/2:in_w/2:in_h/2
5962 Crop height for getting Greek harmony:
5964 crop=in_w:1/PHI*in_w
5968 Apply trembling effect:
5970 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)
5974 Apply erratic camera effect depending on timestamp:
5976 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)"
5980 Set x depending on the value of y:
5982 crop=in_w/2:in_h/2:y:10+10*sin(n/10)
5986 @subsection Commands
5988 This filter supports the following commands:
5994 Set width/height of the output video and the horizontal/vertical position
5996 The command accepts the same syntax of the corresponding option.
5998 If the specified expression is not valid, it is kept at its current
6004 Auto-detect the crop size.
6006 It calculates the necessary cropping parameters and prints the
6007 recommended parameters via the logging system. The detected dimensions
6008 correspond to the non-black area of the input video.
6010 It accepts the following parameters:
6015 Set higher black value threshold, which can be optionally specified
6016 from nothing (0) to everything (255 for 8-bit based formats). An intensity
6017 value greater to the set value is considered non-black. It defaults to 24.
6018 You can also specify a value between 0.0 and 1.0 which will be scaled depending
6019 on the bitdepth of the pixel format.
6022 The value which the width/height should be divisible by. It defaults to
6023 16. The offset is automatically adjusted to center the video. Use 2 to
6024 get only even dimensions (needed for 4:2:2 video). 16 is best when
6025 encoding to most video codecs.
6027 @item reset_count, reset
6028 Set the counter that determines after how many frames cropdetect will
6029 reset the previously detected largest video area and start over to
6030 detect the current optimal crop area. Default value is 0.
6032 This can be useful when channel logos distort the video area. 0
6033 indicates 'never reset', and returns the largest area encountered during
6040 Apply color adjustments using curves.
6042 This filter is similar to the Adobe Photoshop and GIMP curves tools. Each
6043 component (red, green and blue) has its values defined by @var{N} key points
6044 tied from each other using a smooth curve. The x-axis represents the pixel
6045 values from the input frame, and the y-axis the new pixel values to be set for
6048 By default, a component curve is defined by the two points @var{(0;0)} and
6049 @var{(1;1)}. This creates a straight line where each original pixel value is
6050 "adjusted" to its own value, which means no change to the image.
6052 The filter allows you to redefine these two points and add some more. A new
6053 curve (using a natural cubic spline interpolation) will be define to pass
6054 smoothly through all these new coordinates. The new defined points needs to be
6055 strictly increasing over the x-axis, and their @var{x} and @var{y} values must
6056 be in the @var{[0;1]} interval. If the computed curves happened to go outside
6057 the vector spaces, the values will be clipped accordingly.
6059 The filter accepts the following options:
6063 Select one of the available color presets. This option can be used in addition
6064 to the @option{r}, @option{g}, @option{b} parameters; in this case, the later
6065 options takes priority on the preset values.
6066 Available presets are:
6069 @item color_negative
6072 @item increase_contrast
6074 @item linear_contrast
6075 @item medium_contrast
6077 @item strong_contrast
6080 Default is @code{none}.
6082 Set the master key points. These points will define a second pass mapping. It
6083 is sometimes called a "luminance" or "value" mapping. It can be used with
6084 @option{r}, @option{g}, @option{b} or @option{all} since it acts like a
6085 post-processing LUT.
6087 Set the key points for the red component.
6089 Set the key points for the green component.
6091 Set the key points for the blue component.
6093 Set the key points for all components (not including master).
6094 Can be used in addition to the other key points component
6095 options. In this case, the unset component(s) will fallback on this
6096 @option{all} setting.
6098 Specify a Photoshop curves file (@code{.acv}) to import the settings from.
6100 Save Gnuplot script of the curves in specified file.
6103 To avoid some filtergraph syntax conflicts, each key points list need to be
6104 defined using the following syntax: @code{x0/y0 x1/y1 x2/y2 ...}.
6106 @subsection Examples
6110 Increase slightly the middle level of blue:
6112 curves=blue='0/0 0.5/0.58 1/1'
6118 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'
6120 Here we obtain the following coordinates for each components:
6123 @code{(0;0.11) (0.42;0.51) (1;0.95)}
6125 @code{(0;0) (0.50;0.48) (1;1)}
6127 @code{(0;0.22) (0.49;0.44) (1;0.80)}
6131 The previous example can also be achieved with the associated built-in preset:
6133 curves=preset=vintage
6143 Use a Photoshop preset and redefine the points of the green component:
6145 curves=psfile='MyCurvesPresets/purple.acv':green='0/0 0.45/0.53 1/1'
6149 Check out the curves of the @code{cross_process} profile using @command{ffmpeg}
6150 and @command{gnuplot}:
6152 ffmpeg -f lavfi -i color -vf curves=cross_process:plot=/tmp/curves.plt -frames:v 1 -f null -
6153 gnuplot -p /tmp/curves.plt
6159 Video data analysis filter.
6161 This filter shows hexadecimal pixel values of part of video.
6163 The filter accepts the following options:
6167 Set output video size.
6170 Set x offset from where to pick pixels.
6173 Set y offset from where to pick pixels.
6176 Set scope mode, can be one of the following:
6179 Draw hexadecimal pixel values with white color on black background.
6182 Draw hexadecimal pixel values with input video pixel color on black
6186 Draw hexadecimal pixel values on color background picked from input video,
6187 the text color is picked in such way so its always visible.
6191 Draw rows and columns numbers on left and top of video.
6194 Set background opacity.
6199 Denoise frames using 2D DCT (frequency domain filtering).
6201 This filter is not designed for real time.
6203 The filter accepts the following options:
6207 Set the noise sigma constant.
6209 This @var{sigma} defines a hard threshold of @code{3 * sigma}; every DCT
6210 coefficient (absolute value) below this threshold with be dropped.
6212 If you need a more advanced filtering, see @option{expr}.
6214 Default is @code{0}.
6217 Set number overlapping pixels for each block. Since the filter can be slow, you
6218 may want to reduce this value, at the cost of a less effective filter and the
6219 risk of various artefacts.
6221 If the overlapping value doesn't permit processing the whole input width or
6222 height, a warning will be displayed and according borders won't be denoised.
6224 Default value is @var{blocksize}-1, which is the best possible setting.
6227 Set the coefficient factor expression.
6229 For each coefficient of a DCT block, this expression will be evaluated as a
6230 multiplier value for the coefficient.
6232 If this is option is set, the @option{sigma} option will be ignored.
6234 The absolute value of the coefficient can be accessed through the @var{c}
6238 Set the @var{blocksize} using the number of bits. @code{1<<@var{n}} defines the
6239 @var{blocksize}, which is the width and height of the processed blocks.
6241 The default value is @var{3} (8x8) and can be raised to @var{4} for a
6242 @var{blocksize} of 16x16. Note that changing this setting has huge consequences
6243 on the speed processing. Also, a larger block size does not necessarily means a
6247 @subsection Examples
6249 Apply a denoise with a @option{sigma} of @code{4.5}:
6254 The same operation can be achieved using the expression system:
6256 dctdnoiz=e='gte(c, 4.5*3)'
6259 Violent denoise using a block size of @code{16x16}:
6266 Remove banding artifacts from input video.
6267 It works by replacing banded pixels with average value of referenced pixels.
6269 The filter accepts the following options:
6276 Set banding detection threshold for each plane. Default is 0.02.
6277 Valid range is 0.00003 to 0.5.
6278 If difference between current pixel and reference pixel is less than threshold,
6279 it will be considered as banded.
6282 Banding detection range in pixels. Default is 16. If positive, random number
6283 in range 0 to set value will be used. If negative, exact absolute value
6285 The range defines square of four pixels around current pixel.
6288 Set direction in radians from which four pixel will be compared. If positive,
6289 random direction from 0 to set direction will be picked. If negative, exact of
6290 absolute value will be picked. For example direction 0, -PI or -2*PI radians
6291 will pick only pixels on same row and -PI/2 will pick only pixels on same
6295 If enabled, current pixel is compared with average value of all four
6296 surrounding pixels. The default is enabled. If disabled current pixel is
6297 compared with all four surrounding pixels. The pixel is considered banded
6298 if only all four differences with surrounding pixels are less than threshold.
6301 If enabled, current pixel is changed if and only if all pixel components are banded,
6302 e.g. banding detection threshold is triggered for all color components.
6303 The default is disabled.
6309 Drop duplicated frames at regular intervals.
6311 The filter accepts the following options:
6315 Set the number of frames from which one will be dropped. Setting this to
6316 @var{N} means one frame in every batch of @var{N} frames will be dropped.
6317 Default is @code{5}.
6320 Set the threshold for duplicate detection. If the difference metric for a frame
6321 is less than or equal to this value, then it is declared as duplicate. Default
6325 Set scene change threshold. Default is @code{15}.
6329 Set the size of the x and y-axis blocks used during metric calculations.
6330 Larger blocks give better noise suppression, but also give worse detection of
6331 small movements. Must be a power of two. Default is @code{32}.
6334 Mark main input as a pre-processed input and activate clean source input
6335 stream. This allows the input to be pre-processed with various filters to help
6336 the metrics calculation while keeping the frame selection lossless. When set to
6337 @code{1}, the first stream is for the pre-processed input, and the second
6338 stream is the clean source from where the kept frames are chosen. Default is
6342 Set whether or not chroma is considered in the metric calculations. Default is
6348 Apply deflate effect to the video.
6350 This filter replaces the pixel by the local(3x3) average by taking into account
6351 only values lower than the pixel.
6353 It accepts the following options:
6360 Limit the maximum change for each plane, default is 65535.
6361 If 0, plane will remain unchanged.
6366 Remove temporal frame luminance variations.
6368 It accepts the following options:
6372 Set moving-average filter size in frames. Default is 5. Allowed range is 2 - 129.
6375 Set averaging mode to smooth temporal luminance variations.
6377 Available values are:
6402 Do not actually modify frame. Useful when one only wants metadata.
6407 Remove judder produced by partially interlaced telecined content.
6409 Judder can be introduced, for instance, by @ref{pullup} filter. If the original
6410 source was partially telecined content then the output of @code{pullup,dejudder}
6411 will have a variable frame rate. May change the recorded frame rate of the
6412 container. Aside from that change, this filter will not affect constant frame
6415 The option available in this filter is:
6419 Specify the length of the window over which the judder repeats.
6421 Accepts any integer greater than 1. Useful values are:
6425 If the original was telecined from 24 to 30 fps (Film to NTSC).
6428 If the original was telecined from 25 to 30 fps (PAL to NTSC).
6431 If a mixture of the two.
6434 The default is @samp{4}.
6439 Suppress a TV station logo by a simple interpolation of the surrounding
6440 pixels. Just set a rectangle covering the logo and watch it disappear
6441 (and sometimes something even uglier appear - your mileage may vary).
6443 It accepts the following parameters:
6448 Specify the top left corner coordinates of the logo. They must be
6453 Specify the width and height of the logo to clear. They must be
6457 Specify the thickness of the fuzzy edge of the rectangle (added to
6458 @var{w} and @var{h}). The default value is 1. This option is
6459 deprecated, setting higher values should no longer be necessary and
6463 When set to 1, a green rectangle is drawn on the screen to simplify
6464 finding the right @var{x}, @var{y}, @var{w}, and @var{h} parameters.
6465 The default value is 0.
6467 The rectangle is drawn on the outermost pixels which will be (partly)
6468 replaced with interpolated values. The values of the next pixels
6469 immediately outside this rectangle in each direction will be used to
6470 compute the interpolated pixel values inside the rectangle.
6474 @subsection Examples
6478 Set a rectangle covering the area with top left corner coordinates 0,0
6479 and size 100x77, and a band of size 10:
6481 delogo=x=0:y=0:w=100:h=77:band=10
6488 Attempt to fix small changes in horizontal and/or vertical shift. This
6489 filter helps remove camera shake from hand-holding a camera, bumping a
6490 tripod, moving on a vehicle, etc.
6492 The filter accepts the following options:
6500 Specify a rectangular area where to limit the search for motion
6502 If desired the search for motion vectors can be limited to a
6503 rectangular area of the frame defined by its top left corner, width
6504 and height. These parameters have the same meaning as the drawbox
6505 filter which can be used to visualise the position of the bounding
6508 This is useful when simultaneous movement of subjects within the frame
6509 might be confused for camera motion by the motion vector search.
6511 If any or all of @var{x}, @var{y}, @var{w} and @var{h} are set to -1
6512 then the full frame is used. This allows later options to be set
6513 without specifying the bounding box for the motion vector search.
6515 Default - search the whole frame.
6519 Specify the maximum extent of movement in x and y directions in the
6520 range 0-64 pixels. Default 16.
6523 Specify how to generate pixels to fill blanks at the edge of the
6524 frame. Available values are:
6527 Fill zeroes at blank locations
6529 Original image at blank locations
6531 Extruded edge value at blank locations
6533 Mirrored edge at blank locations
6535 Default value is @samp{mirror}.
6538 Specify the blocksize to use for motion search. Range 4-128 pixels,
6542 Specify the contrast threshold for blocks. Only blocks with more than
6543 the specified contrast (difference between darkest and lightest
6544 pixels) will be considered. Range 1-255, default 125.
6547 Specify the search strategy. Available values are:
6550 Set exhaustive search
6552 Set less exhaustive search.
6554 Default value is @samp{exhaustive}.
6557 If set then a detailed log of the motion search is written to the
6561 If set to 1, specify using OpenCL capabilities, only available if
6562 FFmpeg was configured with @code{--enable-opencl}. Default value is 0.
6568 Apply an exact inverse of the telecine operation. It requires a predefined
6569 pattern specified using the pattern option which must be the same as that passed
6570 to the telecine filter.
6572 This filter accepts the following options:
6581 The default value is @code{top}.
6585 A string of numbers representing the pulldown pattern you wish to apply.
6586 The default value is @code{23}.
6589 A number representing position of the first frame with respect to the telecine
6590 pattern. This is to be used if the stream is cut. The default value is @code{0}.
6595 Apply dilation effect to the video.
6597 This filter replaces the pixel by the local(3x3) maximum.
6599 It accepts the following options:
6606 Limit the maximum change for each plane, default is 65535.
6607 If 0, plane will remain unchanged.
6610 Flag which specifies the pixel to refer to. Default is 255 i.e. all eight
6613 Flags to local 3x3 coordinates maps like this:
6622 Displace pixels as indicated by second and third input stream.
6624 It takes three input streams and outputs one stream, the first input is the
6625 source, and second and third input are displacement maps.
6627 The second input specifies how much to displace pixels along the
6628 x-axis, while the third input specifies how much to displace pixels
6630 If one of displacement map streams terminates, last frame from that
6631 displacement map will be used.
6633 Note that once generated, displacements maps can be reused over and over again.
6635 A description of the accepted options follows.
6639 Set displace behavior for pixels that are out of range.
6641 Available values are:
6644 Missing pixels are replaced by black pixels.
6647 Adjacent pixels will spread out to replace missing pixels.
6650 Out of range pixels are wrapped so they point to pixels of other side.
6652 Default is @samp{smear}.
6656 @subsection Examples
6660 Add ripple effect to rgb input of video size hd720:
6662 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
6666 Add wave effect to rgb input of video size hd720:
6668 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
6674 Draw a colored box on the input image.
6676 It accepts the following parameters:
6681 The expressions which specify the top left corner coordinates of the box. It defaults to 0.
6685 The expressions which specify the width and height of the box; if 0 they are interpreted as
6686 the input width and height. It defaults to 0.
6689 Specify the color of the box to write. For the general syntax of this option,
6690 check the "Color" section in the ffmpeg-utils manual. If the special
6691 value @code{invert} is used, the box edge color is the same as the
6692 video with inverted luma.
6695 The expression which sets the thickness of the box edge. Default value is @code{3}.
6697 See below for the list of accepted constants.
6700 The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
6701 following constants:
6705 The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
6709 horizontal and vertical chroma subsample values. For example for the
6710 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
6714 The input width and height.
6717 The input sample aspect ratio.
6721 The x and y offset coordinates where the box is drawn.
6725 The width and height of the drawn box.
6728 The thickness of the drawn box.
6730 These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
6731 each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
6735 @subsection Examples
6739 Draw a black box around the edge of the input image:
6745 Draw a box with color red and an opacity of 50%:
6747 drawbox=10:20:200:60:red@@0.5
6750 The previous example can be specified as:
6752 drawbox=x=10:y=20:w=200:h=60:color=red@@0.5
6756 Fill the box with pink color:
6758 drawbox=x=10:y=10:w=100:h=100:color=pink@@0.5:t=max
6762 Draw a 2-pixel red 2.40:1 mask:
6764 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
6770 Draw a grid on the input image.
6772 It accepts the following parameters:
6777 The expressions which specify the coordinates of some point of grid intersection (meant to configure offset). Both default to 0.
6781 The expressions which specify the width and height of the grid cell, if 0 they are interpreted as the
6782 input width and height, respectively, minus @code{thickness}, so image gets
6783 framed. Default to 0.
6786 Specify the color of the grid. For the general syntax of this option,
6787 check the "Color" section in the ffmpeg-utils manual. If the special
6788 value @code{invert} is used, the grid color is the same as the
6789 video with inverted luma.
6792 The expression which sets the thickness of the grid line. Default value is @code{1}.
6794 See below for the list of accepted constants.
6797 The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
6798 following constants:
6802 The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
6806 horizontal and vertical chroma subsample values. For example for the
6807 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
6811 The input grid cell width and height.
6814 The input sample aspect ratio.
6818 The x and y coordinates of some point of grid intersection (meant to configure offset).
6822 The width and height of the drawn cell.
6825 The thickness of the drawn cell.
6827 These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
6828 each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
6832 @subsection Examples
6836 Draw a grid with cell 100x100 pixels, thickness 2 pixels, with color red and an opacity of 50%:
6838 drawgrid=width=100:height=100:thickness=2:color=red@@0.5
6842 Draw a white 3x3 grid with an opacity of 50%:
6844 drawgrid=w=iw/3:h=ih/3:t=2:c=white@@0.5
6851 Draw a text string or text from a specified file on top of a video, using the
6852 libfreetype library.
6854 To enable compilation of this filter, you need to configure FFmpeg with
6855 @code{--enable-libfreetype}.
6856 To enable default font fallback and the @var{font} option you need to
6857 configure FFmpeg with @code{--enable-libfontconfig}.
6858 To enable the @var{text_shaping} option, you need to configure FFmpeg with
6859 @code{--enable-libfribidi}.
6863 It accepts the following parameters:
6868 Used to draw a box around text using the background color.
6869 The value must be either 1 (enable) or 0 (disable).
6870 The default value of @var{box} is 0.
6873 Set the width of the border to be drawn around the box using @var{boxcolor}.
6874 The default value of @var{boxborderw} is 0.
6877 The color to be used for drawing box around text. For the syntax of this
6878 option, check the "Color" section in the ffmpeg-utils manual.
6880 The default value of @var{boxcolor} is "white".
6883 Set the line spacing in pixels of the border to be drawn around the box using @var{box}.
6884 The default value of @var{line_spacing} is 0.
6887 Set the width of the border to be drawn around the text using @var{bordercolor}.
6888 The default value of @var{borderw} is 0.
6891 Set the color to be used for drawing border around text. For the syntax of this
6892 option, check the "Color" section in the ffmpeg-utils manual.
6894 The default value of @var{bordercolor} is "black".
6897 Select how the @var{text} is expanded. Can be either @code{none},
6898 @code{strftime} (deprecated) or
6899 @code{normal} (default). See the @ref{drawtext_expansion, Text expansion} section
6903 Set a start time for the count. Value is in microseconds. Only applied
6904 in the deprecated strftime expansion mode. To emulate in normal expansion
6905 mode use the @code{pts} function, supplying the start time (in seconds)
6906 as the second argument.
6909 If true, check and fix text coords to avoid clipping.
6912 The color to be used for drawing fonts. For the syntax of this option, check
6913 the "Color" section in the ffmpeg-utils manual.
6915 The default value of @var{fontcolor} is "black".
6917 @item fontcolor_expr
6918 String which is expanded the same way as @var{text} to obtain dynamic
6919 @var{fontcolor} value. By default this option has empty value and is not
6920 processed. When this option is set, it overrides @var{fontcolor} option.
6923 The font family to be used for drawing text. By default Sans.
6926 The font file to be used for drawing text. The path must be included.
6927 This parameter is mandatory if the fontconfig support is disabled.
6930 Draw the text applying alpha blending. The value can
6931 be a number between 0.0 and 1.0.
6932 The expression accepts the same variables @var{x, y} as well.
6933 The default value is 1.
6934 Please see @var{fontcolor_expr}.
6937 The font size to be used for drawing text.
6938 The default value of @var{fontsize} is 16.
6941 If set to 1, attempt to shape the text (for example, reverse the order of
6942 right-to-left text and join Arabic characters) before drawing it.
6943 Otherwise, just draw the text exactly as given.
6944 By default 1 (if supported).
6947 The flags to be used for loading the fonts.
6949 The flags map the corresponding flags supported by libfreetype, and are
6950 a combination of the following values:
6957 @item vertical_layout
6958 @item force_autohint
6961 @item ignore_global_advance_width
6963 @item ignore_transform
6969 Default value is "default".
6971 For more information consult the documentation for the FT_LOAD_*
6975 The color to be used for drawing a shadow behind the drawn text. For the
6976 syntax of this option, check the "Color" section in the ffmpeg-utils manual.
6978 The default value of @var{shadowcolor} is "black".
6982 The x and y offsets for the text shadow position with respect to the
6983 position of the text. They can be either positive or negative
6984 values. The default value for both is "0".
6987 The starting frame number for the n/frame_num variable. The default value
6991 The size in number of spaces to use for rendering the tab.
6995 Set the initial timecode representation in "hh:mm:ss[:;.]ff"
6996 format. It can be used with or without text parameter. @var{timecode_rate}
6997 option must be specified.
6999 @item timecode_rate, rate, r
7000 Set the timecode frame rate (timecode only).
7003 If set to 1, the output of the timecode option will wrap around at 24 hours.
7004 Default is 0 (disabled).
7007 The text string to be drawn. The text must be a sequence of UTF-8
7009 This parameter is mandatory if no file is specified with the parameter
7013 A text file containing text to be drawn. The text must be a sequence
7014 of UTF-8 encoded characters.
7016 This parameter is mandatory if no text string is specified with the
7017 parameter @var{text}.
7019 If both @var{text} and @var{textfile} are specified, an error is thrown.
7022 If set to 1, the @var{textfile} will be reloaded before each frame.
7023 Be sure to update it atomically, or it may be read partially, or even fail.
7027 The expressions which specify the offsets where text will be drawn
7028 within the video frame. They are relative to the top/left border of the
7031 The default value of @var{x} and @var{y} is "0".
7033 See below for the list of accepted constants and functions.
7036 The parameters for @var{x} and @var{y} are expressions containing the
7037 following constants and functions:
7041 input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
7045 horizontal and vertical chroma subsample values. For example for the
7046 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
7049 the height of each text line
7057 @item max_glyph_a, ascent
7058 the maximum distance from the baseline to the highest/upper grid
7059 coordinate used to place a glyph outline point, for all the rendered
7061 It is a positive value, due to the grid's orientation with the Y axis
7064 @item max_glyph_d, descent
7065 the maximum distance from the baseline to the lowest grid coordinate
7066 used to place a glyph outline point, for all the rendered glyphs.
7067 This is a negative value, due to the grid's orientation, with the Y axis
7071 maximum glyph height, that is the maximum height for all the glyphs
7072 contained in the rendered text, it is equivalent to @var{ascent} -
7076 maximum glyph width, that is the maximum width for all the glyphs
7077 contained in the rendered text
7080 the number of input frame, starting from 0
7082 @item rand(min, max)
7083 return a random number included between @var{min} and @var{max}
7086 The input sample aspect ratio.
7089 timestamp expressed in seconds, NAN if the input timestamp is unknown
7092 the height of the rendered text
7095 the width of the rendered text
7099 the x and y offset coordinates where the text is drawn.
7101 These parameters allow the @var{x} and @var{y} expressions to refer
7102 each other, so you can for example specify @code{y=x/dar}.
7105 @anchor{drawtext_expansion}
7106 @subsection Text expansion
7108 If @option{expansion} is set to @code{strftime},
7109 the filter recognizes strftime() sequences in the provided text and
7110 expands them accordingly. Check the documentation of strftime(). This
7111 feature is deprecated.
7113 If @option{expansion} is set to @code{none}, the text is printed verbatim.
7115 If @option{expansion} is set to @code{normal} (which is the default),
7116 the following expansion mechanism is used.
7118 The backslash character @samp{\}, followed by any character, always expands to
7119 the second character.
7121 Sequences of the form @code{%@{...@}} are expanded. The text between the
7122 braces is a function name, possibly followed by arguments separated by ':'.
7123 If the arguments contain special characters or delimiters (':' or '@}'),
7124 they should be escaped.
7126 Note that they probably must also be escaped as the value for the
7127 @option{text} option in the filter argument string and as the filter
7128 argument in the filtergraph description, and possibly also for the shell,
7129 that makes up to four levels of escaping; using a text file avoids these
7132 The following functions are available:
7137 The expression evaluation result.
7139 It must take one argument specifying the expression to be evaluated,
7140 which accepts the same constants and functions as the @var{x} and
7141 @var{y} values. Note that not all constants should be used, for
7142 example the text size is not known when evaluating the expression, so
7143 the constants @var{text_w} and @var{text_h} will have an undefined
7146 @item expr_int_format, eif
7147 Evaluate the expression's value and output as formatted integer.
7149 The first argument is the expression to be evaluated, just as for the @var{expr} function.
7150 The second argument specifies the output format. Allowed values are @samp{x},
7151 @samp{X}, @samp{d} and @samp{u}. They are treated exactly as in the
7152 @code{printf} function.
7153 The third parameter is optional and sets the number of positions taken by the output.
7154 It can be used to add padding with zeros from the left.
7157 The time at which the filter is running, expressed in UTC.
7158 It can accept an argument: a strftime() format string.
7161 The time at which the filter is running, expressed in the local time zone.
7162 It can accept an argument: a strftime() format string.
7165 Frame metadata. Takes one or two arguments.
7167 The first argument is mandatory and specifies the metadata key.
7169 The second argument is optional and specifies a default value, used when the
7170 metadata key is not found or empty.
7173 The frame number, starting from 0.
7176 A 1 character description of the current picture type.
7179 The timestamp of the current frame.
7180 It can take up to three arguments.
7182 The first argument is the format of the timestamp; it defaults to @code{flt}
7183 for seconds as a decimal number with microsecond accuracy; @code{hms} stands
7184 for a formatted @var{[-]HH:MM:SS.mmm} timestamp with millisecond accuracy.
7185 @code{gmtime} stands for the timestamp of the frame formatted as UTC time;
7186 @code{localtime} stands for the timestamp of the frame formatted as
7187 local time zone time.
7189 The second argument is an offset added to the timestamp.
7191 If the format is set to @code{localtime} or @code{gmtime},
7192 a third argument may be supplied: a strftime() format string.
7193 By default, @var{YYYY-MM-DD HH:MM:SS} format will be used.
7196 @subsection Examples
7200 Draw "Test Text" with font FreeSerif, using the default values for the
7201 optional parameters.
7204 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"
7208 Draw 'Test Text' with font FreeSerif of size 24 at position x=100
7209 and y=50 (counting from the top-left corner of the screen), text is
7210 yellow with a red box around it. Both the text and the box have an
7214 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
7215 x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2"
7218 Note that the double quotes are not necessary if spaces are not used
7219 within the parameter list.
7222 Show the text at the center of the video frame:
7224 drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h)/2"
7228 Show the text at a random position, switching to a new position every 30 seconds:
7230 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)"
7234 Show a text line sliding from right to left in the last row of the video
7235 frame. The file @file{LONG_LINE} is assumed to contain a single line
7238 drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t"
7242 Show the content of file @file{CREDITS} off the bottom of the frame and scroll up.
7244 drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t"
7248 Draw a single green letter "g", at the center of the input video.
7249 The glyph baseline is placed at half screen height.
7251 drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent"
7255 Show text for 1 second every 3 seconds:
7257 drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:enable=lt(mod(t\,3)\,1):text='blink'"
7261 Use fontconfig to set the font. Note that the colons need to be escaped.
7263 drawtext='fontfile=Linux Libertine O-40\:style=Semibold:text=FFmpeg'
7267 Print the date of a real-time encoding (see strftime(3)):
7269 drawtext='fontfile=FreeSans.ttf:text=%@{localtime\:%a %b %d %Y@}'
7273 Show text fading in and out (appearing/disappearing):
7276 DS=1.0 # display start
7277 DE=10.0 # display end
7278 FID=1.5 # fade in duration
7279 FOD=5 # fade out duration
7280 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 @}"
7284 Horizontally align multiple separate texts. Note that @option{max_glyph_a}
7285 and the @option{fontsize} value are included in the @option{y} offset.
7287 drawtext=fontfile=FreeSans.ttf:text=DOG:fontsize=24:x=10:y=20+24-max_glyph_a,
7288 drawtext=fontfile=FreeSans.ttf:text=cow:fontsize=24:x=80:y=20+24-max_glyph_a
7293 For more information about libfreetype, check:
7294 @url{http://www.freetype.org/}.
7296 For more information about fontconfig, check:
7297 @url{http://freedesktop.org/software/fontconfig/fontconfig-user.html}.
7299 For more information about libfribidi, check:
7300 @url{http://fribidi.org/}.
7304 Detect and draw edges. The filter uses the Canny Edge Detection algorithm.
7306 The filter accepts the following options:
7311 Set low and high threshold values used by the Canny thresholding
7314 The high threshold selects the "strong" edge pixels, which are then
7315 connected through 8-connectivity with the "weak" edge pixels selected
7316 by the low threshold.
7318 @var{low} and @var{high} threshold values must be chosen in the range
7319 [0,1], and @var{low} should be lesser or equal to @var{high}.
7321 Default value for @var{low} is @code{20/255}, and default value for @var{high}
7325 Define the drawing mode.
7329 Draw white/gray wires on black background.
7332 Mix the colors to create a paint/cartoon effect.
7335 Default value is @var{wires}.
7338 @subsection Examples
7342 Standard edge detection with custom values for the hysteresis thresholding:
7344 edgedetect=low=0.1:high=0.4
7348 Painting effect without thresholding:
7350 edgedetect=mode=colormix:high=0
7355 Set brightness, contrast, saturation and approximate gamma adjustment.
7357 The filter accepts the following options:
7361 Set the contrast expression. The value must be a float value in range
7362 @code{-2.0} to @code{2.0}. The default value is "1".
7365 Set the brightness expression. The value must be a float value in
7366 range @code{-1.0} to @code{1.0}. The default value is "0".
7369 Set the saturation expression. The value must be a float in
7370 range @code{0.0} to @code{3.0}. The default value is "1".
7373 Set the gamma expression. The value must be a float in range
7374 @code{0.1} to @code{10.0}. The default value is "1".
7377 Set the gamma expression for red. The value must be a float in
7378 range @code{0.1} to @code{10.0}. The default value is "1".
7381 Set the gamma expression for green. The value must be a float in range
7382 @code{0.1} to @code{10.0}. The default value is "1".
7385 Set the gamma expression for blue. The value must be a float in range
7386 @code{0.1} to @code{10.0}. The default value is "1".
7389 Set the gamma weight expression. It can be used to reduce the effect
7390 of a high gamma value on bright image areas, e.g. keep them from
7391 getting overamplified and just plain white. The value must be a float
7392 in range @code{0.0} to @code{1.0}. A value of @code{0.0} turns the
7393 gamma correction all the way down while @code{1.0} leaves it at its
7394 full strength. Default is "1".
7397 Set when the expressions for brightness, contrast, saturation and
7398 gamma expressions are evaluated.
7400 It accepts the following values:
7403 only evaluate expressions once during the filter initialization or
7404 when a command is processed
7407 evaluate expressions for each incoming frame
7410 Default value is @samp{init}.
7413 The expressions accept the following parameters:
7416 frame count of the input frame starting from 0
7419 byte position of the corresponding packet in the input file, NAN if
7423 frame rate of the input video, NAN if the input frame rate is unknown
7426 timestamp expressed in seconds, NAN if the input timestamp is unknown
7429 @subsection Commands
7430 The filter supports the following commands:
7434 Set the contrast expression.
7437 Set the brightness expression.
7440 Set the saturation expression.
7443 Set the gamma expression.
7446 Set the gamma_r expression.
7449 Set gamma_g expression.
7452 Set gamma_b expression.
7455 Set gamma_weight expression.
7457 The command accepts the same syntax of the corresponding option.
7459 If the specified expression is not valid, it is kept at its current
7466 Apply erosion effect to the video.
7468 This filter replaces the pixel by the local(3x3) minimum.
7470 It accepts the following options:
7477 Limit the maximum change for each plane, default is 65535.
7478 If 0, plane will remain unchanged.
7481 Flag which specifies the pixel to refer to. Default is 255 i.e. all eight
7484 Flags to local 3x3 coordinates maps like this:
7491 @section extractplanes
7493 Extract color channel components from input video stream into
7494 separate grayscale video streams.
7496 The filter accepts the following option:
7500 Set plane(s) to extract.
7502 Available values for planes are:
7513 Choosing planes not available in the input will result in an error.
7514 That means you cannot select @code{r}, @code{g}, @code{b} planes
7515 with @code{y}, @code{u}, @code{v} planes at same time.
7518 @subsection Examples
7522 Extract luma, u and v color channel component from input video frame
7523 into 3 grayscale outputs:
7525 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
7531 Apply a posterize effect using the ELBG (Enhanced LBG) algorithm.
7533 For each input image, the filter will compute the optimal mapping from
7534 the input to the output given the codebook length, that is the number
7535 of distinct output colors.
7537 This filter accepts the following options.
7540 @item codebook_length, l
7541 Set codebook length. The value must be a positive integer, and
7542 represents the number of distinct output colors. Default value is 256.
7545 Set the maximum number of iterations to apply for computing the optimal
7546 mapping. The higher the value the better the result and the higher the
7547 computation time. Default value is 1.
7550 Set a random seed, must be an integer included between 0 and
7551 UINT32_MAX. If not specified, or if explicitly set to -1, the filter
7552 will try to use a good random seed on a best effort basis.
7555 Set pal8 output pixel format. This option does not work with codebook
7556 length greater than 256.
7561 Apply a fade-in/out effect to the input video.
7563 It accepts the following parameters:
7567 The effect type can be either "in" for a fade-in, or "out" for a fade-out
7569 Default is @code{in}.
7571 @item start_frame, s
7572 Specify the number of the frame to start applying the fade
7573 effect at. Default is 0.
7576 The number of frames that the fade effect lasts. At the end of the
7577 fade-in effect, the output video will have the same intensity as the input video.
7578 At the end of the fade-out transition, the output video will be filled with the
7579 selected @option{color}.
7583 If set to 1, fade only alpha channel, if one exists on the input.
7586 @item start_time, st
7587 Specify the timestamp (in seconds) of the frame to start to apply the fade
7588 effect. If both start_frame and start_time are specified, the fade will start at
7589 whichever comes last. Default is 0.
7592 The number of seconds for which the fade effect has to last. At the end of the
7593 fade-in effect the output video will have the same intensity as the input video,
7594 at the end of the fade-out transition the output video will be filled with the
7595 selected @option{color}.
7596 If both duration and nb_frames are specified, duration is used. Default is 0
7597 (nb_frames is used by default).
7600 Specify the color of the fade. Default is "black".
7603 @subsection Examples
7607 Fade in the first 30 frames of video:
7612 The command above is equivalent to:
7618 Fade out the last 45 frames of a 200-frame video:
7621 fade=type=out:start_frame=155:nb_frames=45
7625 Fade in the first 25 frames and fade out the last 25 frames of a 1000-frame video:
7627 fade=in:0:25, fade=out:975:25
7631 Make the first 5 frames yellow, then fade in from frame 5-24:
7633 fade=in:5:20:color=yellow
7637 Fade in alpha over first 25 frames of video:
7639 fade=in:0:25:alpha=1
7643 Make the first 5.5 seconds black, then fade in for 0.5 seconds:
7645 fade=t=in:st=5.5:d=0.5
7651 Apply arbitrary expressions to samples in frequency domain
7655 Adjust the dc value (gain) of the luma plane of the image. The filter
7656 accepts an integer value in range @code{0} to @code{1000}. The default
7657 value is set to @code{0}.
7660 Adjust the dc value (gain) of the 1st chroma plane of the image. The
7661 filter accepts an integer value in range @code{0} to @code{1000}. The
7662 default value is set to @code{0}.
7665 Adjust the dc value (gain) of the 2nd chroma plane of the image. The
7666 filter accepts an integer value in range @code{0} to @code{1000}. The
7667 default value is set to @code{0}.
7670 Set the frequency domain weight expression for the luma plane.
7673 Set the frequency domain weight expression for the 1st chroma plane.
7676 Set the frequency domain weight expression for the 2nd chroma plane.
7678 The filter accepts the following variables:
7681 The coordinates of the current sample.
7685 The width and height of the image.
7688 @subsection Examples
7694 fftfilt=dc_Y=128:weight_Y='squish(1-(Y+X)/100)'
7700 fftfilt=dc_Y=0:weight_Y='squish((Y+X)/100-1)'
7706 fftfilt=dc_Y=0:weight_Y='1+squish(1-(Y+X)/100)'
7712 fftfilt=dc_Y=0:weight_Y='exp(-4 * ((Y+X)/(W+H)))'
7719 Extract a single field from an interlaced image using stride
7720 arithmetic to avoid wasting CPU time. The output frames are marked as
7723 The filter accepts the following options:
7727 Specify whether to extract the top (if the value is @code{0} or
7728 @code{top}) or the bottom field (if the value is @code{1} or
7734 Create new frames by copying the top and bottom fields from surrounding frames
7735 supplied as numbers by the hint file.
7739 Set file containing hints: absolute/relative frame numbers.
7741 There must be one line for each frame in a clip. Each line must contain two
7742 numbers separated by the comma, optionally followed by @code{-} or @code{+}.
7743 Numbers supplied on each line of file can not be out of [N-1,N+1] where N
7744 is current frame number for @code{absolute} mode or out of [-1, 1] range
7745 for @code{relative} mode. First number tells from which frame to pick up top
7746 field and second number tells from which frame to pick up bottom field.
7748 If optionally followed by @code{+} output frame will be marked as interlaced,
7749 else if followed by @code{-} output frame will be marked as progressive, else
7750 it will be marked same as input frame.
7751 If line starts with @code{#} or @code{;} that line is skipped.
7754 Can be item @code{absolute} or @code{relative}. Default is @code{absolute}.
7757 Example of first several lines of @code{hint} file for @code{relative} mode:
7760 1,0 - # second frame, use third's frame top field and second's frame bottom field
7761 1,0 - # third frame, use fourth's frame top field and third's frame bottom field
7778 Field matching filter for inverse telecine. It is meant to reconstruct the
7779 progressive frames from a telecined stream. The filter does not drop duplicated
7780 frames, so to achieve a complete inverse telecine @code{fieldmatch} needs to be
7781 followed by a decimation filter such as @ref{decimate} in the filtergraph.
7783 The separation of the field matching and the decimation is notably motivated by
7784 the possibility of inserting a de-interlacing filter fallback between the two.
7785 If the source has mixed telecined and real interlaced content,
7786 @code{fieldmatch} will not be able to match fields for the interlaced parts.
7787 But these remaining combed frames will be marked as interlaced, and thus can be
7788 de-interlaced by a later filter such as @ref{yadif} before decimation.
7790 In addition to the various configuration options, @code{fieldmatch} can take an
7791 optional second stream, activated through the @option{ppsrc} option. If
7792 enabled, the frames reconstruction will be based on the fields and frames from
7793 this second stream. This allows the first input to be pre-processed in order to
7794 help the various algorithms of the filter, while keeping the output lossless
7795 (assuming the fields are matched properly). Typically, a field-aware denoiser,
7796 or brightness/contrast adjustments can help.
7798 Note that this filter uses the same algorithms as TIVTC/TFM (AviSynth project)
7799 and VIVTC/VFM (VapourSynth project). The later is a light clone of TFM from
7800 which @code{fieldmatch} is based on. While the semantic and usage are very
7801 close, some behaviour and options names can differ.
7803 The @ref{decimate} filter currently only works for constant frame rate input.
7804 If your input has mixed telecined (30fps) and progressive content with a lower
7805 framerate like 24fps use the following filterchain to produce the necessary cfr
7806 stream: @code{dejudder,fps=30000/1001,fieldmatch,decimate}.
7808 The filter accepts the following options:
7812 Specify the assumed field order of the input stream. Available values are:
7816 Auto detect parity (use FFmpeg's internal parity value).
7818 Assume bottom field first.
7820 Assume top field first.
7823 Note that it is sometimes recommended not to trust the parity announced by the
7826 Default value is @var{auto}.
7829 Set the matching mode or strategy to use. @option{pc} mode is the safest in the
7830 sense that it won't risk creating jerkiness due to duplicate frames when
7831 possible, but if there are bad edits or blended fields it will end up
7832 outputting combed frames when a good match might actually exist. On the other
7833 hand, @option{pcn_ub} mode is the most risky in terms of creating jerkiness,
7834 but will almost always find a good frame if there is one. The other values are
7835 all somewhere in between @option{pc} and @option{pcn_ub} in terms of risking
7836 jerkiness and creating duplicate frames versus finding good matches in sections
7837 with bad edits, orphaned fields, blended fields, etc.
7839 More details about p/c/n/u/b are available in @ref{p/c/n/u/b meaning} section.
7841 Available values are:
7845 2-way matching (p/c)
7847 2-way matching, and trying 3rd match if still combed (p/c + n)
7849 2-way matching, and trying 3rd match (same order) if still combed (p/c + u)
7851 2-way matching, trying 3rd match if still combed, and trying 4th/5th matches if
7852 still combed (p/c + n + u/b)
7854 3-way matching (p/c/n)
7856 3-way matching, and trying 4th/5th matches if all 3 of the original matches are
7857 detected as combed (p/c/n + u/b)
7860 The parenthesis at the end indicate the matches that would be used for that
7861 mode assuming @option{order}=@var{tff} (and @option{field} on @var{auto} or
7864 In terms of speed @option{pc} mode is by far the fastest and @option{pcn_ub} is
7867 Default value is @var{pc_n}.
7870 Mark the main input stream as a pre-processed input, and enable the secondary
7871 input stream as the clean source to pick the fields from. See the filter
7872 introduction for more details. It is similar to the @option{clip2} feature from
7875 Default value is @code{0} (disabled).
7878 Set the field to match from. It is recommended to set this to the same value as
7879 @option{order} unless you experience matching failures with that setting. In
7880 certain circumstances changing the field that is used to match from can have a
7881 large impact on matching performance. Available values are:
7885 Automatic (same value as @option{order}).
7887 Match from the bottom field.
7889 Match from the top field.
7892 Default value is @var{auto}.
7895 Set whether or not chroma is included during the match comparisons. In most
7896 cases it is recommended to leave this enabled. You should set this to @code{0}
7897 only if your clip has bad chroma problems such as heavy rainbowing or other
7898 artifacts. Setting this to @code{0} could also be used to speed things up at
7899 the cost of some accuracy.
7901 Default value is @code{1}.
7905 These define an exclusion band which excludes the lines between @option{y0} and
7906 @option{y1} from being included in the field matching decision. An exclusion
7907 band can be used to ignore subtitles, a logo, or other things that may
7908 interfere with the matching. @option{y0} sets the starting scan line and
7909 @option{y1} sets the ending line; all lines in between @option{y0} and
7910 @option{y1} (including @option{y0} and @option{y1}) will be ignored. Setting
7911 @option{y0} and @option{y1} to the same value will disable the feature.
7912 @option{y0} and @option{y1} defaults to @code{0}.
7915 Set the scene change detection threshold as a percentage of maximum change on
7916 the luma plane. Good values are in the @code{[8.0, 14.0]} range. Scene change
7917 detection is only relevant in case @option{combmatch}=@var{sc}. The range for
7918 @option{scthresh} is @code{[0.0, 100.0]}.
7920 Default value is @code{12.0}.
7923 When @option{combatch} is not @var{none}, @code{fieldmatch} will take into
7924 account the combed scores of matches when deciding what match to use as the
7925 final match. Available values are:
7929 No final matching based on combed scores.
7931 Combed scores are only used when a scene change is detected.
7933 Use combed scores all the time.
7936 Default is @var{sc}.
7939 Force @code{fieldmatch} to calculate the combed metrics for certain matches and
7940 print them. This setting is known as @option{micout} in TFM/VFM vocabulary.
7941 Available values are:
7945 No forced calculation.
7947 Force p/c/n calculations.
7949 Force p/c/n/u/b calculations.
7952 Default value is @var{none}.
7955 This is the area combing threshold used for combed frame detection. This
7956 essentially controls how "strong" or "visible" combing must be to be detected.
7957 Larger values mean combing must be more visible and smaller values mean combing
7958 can be less visible or strong and still be detected. Valid settings are from
7959 @code{-1} (every pixel will be detected as combed) to @code{255} (no pixel will
7960 be detected as combed). This is basically a pixel difference value. A good
7961 range is @code{[8, 12]}.
7963 Default value is @code{9}.
7966 Sets whether or not chroma is considered in the combed frame decision. Only
7967 disable this if your source has chroma problems (rainbowing, etc.) that are
7968 causing problems for the combed frame detection with chroma enabled. Actually,
7969 using @option{chroma}=@var{0} is usually more reliable, except for the case
7970 where there is chroma only combing in the source.
7972 Default value is @code{0}.
7976 Respectively set the x-axis and y-axis size of the window used during combed
7977 frame detection. This has to do with the size of the area in which
7978 @option{combpel} pixels are required to be detected as combed for a frame to be
7979 declared combed. See the @option{combpel} parameter description for more info.
7980 Possible values are any number that is a power of 2 starting at 4 and going up
7983 Default value is @code{16}.
7986 The number of combed pixels inside any of the @option{blocky} by
7987 @option{blockx} size blocks on the frame for the frame to be detected as
7988 combed. While @option{cthresh} controls how "visible" the combing must be, this
7989 setting controls "how much" combing there must be in any localized area (a
7990 window defined by the @option{blockx} and @option{blocky} settings) on the
7991 frame. Minimum value is @code{0} and maximum is @code{blocky x blockx} (at
7992 which point no frames will ever be detected as combed). This setting is known
7993 as @option{MI} in TFM/VFM vocabulary.
7995 Default value is @code{80}.
7998 @anchor{p/c/n/u/b meaning}
7999 @subsection p/c/n/u/b meaning
8001 @subsubsection p/c/n
8003 We assume the following telecined stream:
8006 Top fields: 1 2 2 3 4
8007 Bottom fields: 1 2 3 4 4
8010 The numbers correspond to the progressive frame the fields relate to. Here, the
8011 first two frames are progressive, the 3rd and 4th are combed, and so on.
8013 When @code{fieldmatch} is configured to run a matching from bottom
8014 (@option{field}=@var{bottom}) this is how this input stream get transformed:
8019 B 1 2 3 4 4 <-- matching reference
8028 As a result of the field matching, we can see that some frames get duplicated.
8029 To perform a complete inverse telecine, you need to rely on a decimation filter
8030 after this operation. See for instance the @ref{decimate} filter.
8032 The same operation now matching from top fields (@option{field}=@var{top})
8037 T 1 2 2 3 4 <-- matching reference
8047 In these examples, we can see what @var{p}, @var{c} and @var{n} mean;
8048 basically, they refer to the frame and field of the opposite parity:
8051 @item @var{p} matches the field of the opposite parity in the previous frame
8052 @item @var{c} matches the field of the opposite parity in the current frame
8053 @item @var{n} matches the field of the opposite parity in the next frame
8058 The @var{u} and @var{b} matching are a bit special in the sense that they match
8059 from the opposite parity flag. In the following examples, we assume that we are
8060 currently matching the 2nd frame (Top:2, bottom:2). According to the match, a
8061 'x' is placed above and below each matched fields.
8063 With bottom matching (@option{field}=@var{bottom}):
8068 Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2
8069 Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3
8077 With top matching (@option{field}=@var{top}):
8082 Top 1 2 2 1 2 2 1 2 2 1 2 2 1 2 2
8083 Bottom 1 2 3 1 2 3 1 2 3 1 2 3 1 2 3
8091 @subsection Examples
8093 Simple IVTC of a top field first telecined stream:
8095 fieldmatch=order=tff:combmatch=none, decimate
8098 Advanced IVTC, with fallback on @ref{yadif} for still combed frames:
8100 fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate
8105 Transform the field order of the input video.
8107 It accepts the following parameters:
8112 The output field order. Valid values are @var{tff} for top field first or @var{bff}
8113 for bottom field first.
8116 The default value is @samp{tff}.
8118 The transformation is done by shifting the picture content up or down
8119 by one line, and filling the remaining line with appropriate picture content.
8120 This method is consistent with most broadcast field order converters.
8122 If the input video is not flagged as being interlaced, or it is already
8123 flagged as being of the required output field order, then this filter does
8124 not alter the incoming video.
8126 It is very useful when converting to or from PAL DV material,
8127 which is bottom field first.
8131 ffmpeg -i in.vob -vf "fieldorder=bff" out.dv
8134 @section fifo, afifo
8136 Buffer input images and send them when they are requested.
8138 It is mainly useful when auto-inserted by the libavfilter
8141 It does not take parameters.
8145 Find a rectangular object
8147 It accepts the following options:
8151 Filepath of the object image, needs to be in gray8.
8154 Detection threshold, default is 0.5.
8157 Number of mipmaps, default is 3.
8159 @item xmin, ymin, xmax, ymax
8160 Specifies the rectangle in which to search.
8163 @subsection Examples
8167 Generate a representative palette of a given video using @command{ffmpeg}:
8169 ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
8175 Cover a rectangular object
8177 It accepts the following options:
8181 Filepath of the optional cover image, needs to be in yuv420.
8186 It accepts the following values:
8189 cover it by the supplied image
8191 cover it by interpolating the surrounding pixels
8194 Default value is @var{blur}.
8197 @subsection Examples
8201 Generate a representative palette of a given video using @command{ffmpeg}:
8203 ffmpeg -i file.ts -vf find_rect=newref.pgm,cover_rect=cover.jpg:mode=cover new.mkv
8210 Convert the input video to one of the specified pixel formats.
8211 Libavfilter will try to pick one that is suitable as input to
8214 It accepts the following parameters:
8218 A '|'-separated list of pixel format names, such as
8219 "pix_fmts=yuv420p|monow|rgb24".
8223 @subsection Examples
8227 Convert the input video to the @var{yuv420p} format
8229 format=pix_fmts=yuv420p
8232 Convert the input video to any of the formats in the list
8234 format=pix_fmts=yuv420p|yuv444p|yuv410p
8241 Convert the video to specified constant frame rate by duplicating or dropping
8242 frames as necessary.
8244 It accepts the following parameters:
8248 The desired output frame rate. The default is @code{25}.
8253 Possible values are:
8256 zero round towards 0
8260 round towards -infinity
8262 round towards +infinity
8266 The default is @code{near}.
8269 Assume the first PTS should be the given value, in seconds. This allows for
8270 padding/trimming at the start of stream. By default, no assumption is made
8271 about the first frame's expected PTS, so no padding or trimming is done.
8272 For example, this could be set to 0 to pad the beginning with duplicates of
8273 the first frame if a video stream starts after the audio stream or to trim any
8274 frames with a negative PTS.
8278 Alternatively, the options can be specified as a flat string:
8279 @var{fps}[:@var{round}].
8281 See also the @ref{setpts} filter.
8283 @subsection Examples
8287 A typical usage in order to set the fps to 25:
8293 Sets the fps to 24, using abbreviation and rounding method to round to nearest:
8295 fps=fps=film:round=near
8301 Pack two different video streams into a stereoscopic video, setting proper
8302 metadata on supported codecs. The two views should have the same size and
8303 framerate and processing will stop when the shorter video ends. Please note
8304 that you may conveniently adjust view properties with the @ref{scale} and
8307 It accepts the following parameters:
8311 The desired packing format. Supported values are:
8316 The views are next to each other (default).
8319 The views are on top of each other.
8322 The views are packed by line.
8325 The views are packed by column.
8328 The views are temporally interleaved.
8337 # Convert left and right views into a frame-sequential video
8338 ffmpeg -i LEFT -i RIGHT -filter_complex framepack=frameseq OUTPUT
8340 # Convert views into a side-by-side video with the same output resolution as the input
8341 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
8346 Change the frame rate by interpolating new video output frames from the source
8349 This filter is not designed to function correctly with interlaced media. If
8350 you wish to change the frame rate of interlaced media then you are required
8351 to deinterlace before this filter and re-interlace after this filter.
8353 A description of the accepted options follows.
8357 Specify the output frames per second. This option can also be specified
8358 as a value alone. The default is @code{50}.
8361 Specify the start of a range where the output frame will be created as a
8362 linear interpolation of two frames. The range is [@code{0}-@code{255}],
8363 the default is @code{15}.
8366 Specify the end of a range where the output frame will be created as a
8367 linear interpolation of two frames. The range is [@code{0}-@code{255}],
8368 the default is @code{240}.
8371 Specify the level at which a scene change is detected as a value between
8372 0 and 100 to indicate a new scene; a low value reflects a low
8373 probability for the current frame to introduce a new scene, while a higher
8374 value means the current frame is more likely to be one.
8375 The default is @code{7}.
8378 Specify flags influencing the filter process.
8380 Available value for @var{flags} is:
8383 @item scene_change_detect, scd
8384 Enable scene change detection using the value of the option @var{scene}.
8385 This flag is enabled by default.
8391 Select one frame every N-th frame.
8393 This filter accepts the following option:
8396 Select frame after every @code{step} frames.
8397 Allowed values are positive integers higher than 0. Default value is @code{1}.
8403 Apply a frei0r effect to the input video.
8405 To enable the compilation of this filter, you need to install the frei0r
8406 header and configure FFmpeg with @code{--enable-frei0r}.
8408 It accepts the following parameters:
8413 The name of the frei0r effect to load. If the environment variable
8414 @env{FREI0R_PATH} is defined, the frei0r effect is searched for in each of the
8415 directories specified by the colon-separated list in @env{FREIOR_PATH}.
8416 Otherwise, the standard frei0r paths are searched, in this order:
8417 @file{HOME/.frei0r-1/lib/}, @file{/usr/local/lib/frei0r-1/},
8418 @file{/usr/lib/frei0r-1/}.
8421 A '|'-separated list of parameters to pass to the frei0r effect.
8425 A frei0r effect parameter can be a boolean (its value is either
8426 "y" or "n"), a double, a color (specified as
8427 @var{R}/@var{G}/@var{B}, where @var{R}, @var{G}, and @var{B} are floating point
8428 numbers between 0.0 and 1.0, inclusive) or by a color description specified in the "Color"
8429 section in the ffmpeg-utils manual), a position (specified as @var{X}/@var{Y}, where
8430 @var{X} and @var{Y} are floating point numbers) and/or a string.
8432 The number and types of parameters depend on the loaded effect. If an
8433 effect parameter is not specified, the default value is set.
8435 @subsection Examples
8439 Apply the distort0r effect, setting the first two double parameters:
8441 frei0r=filter_name=distort0r:filter_params=0.5|0.01
8445 Apply the colordistance effect, taking a color as the first parameter:
8447 frei0r=colordistance:0.2/0.3/0.4
8448 frei0r=colordistance:violet
8449 frei0r=colordistance:0x112233
8453 Apply the perspective effect, specifying the top left and top right image
8456 frei0r=perspective:0.2/0.2|0.8/0.2
8460 For more information, see
8461 @url{http://frei0r.dyne.org}
8465 Apply fast and simple postprocessing. It is a faster version of @ref{spp}.
8467 It splits (I)DCT into horizontal/vertical passes. Unlike the simple post-
8468 processing filter, one of them is performed once per block, not per pixel.
8469 This allows for much higher speed.
8471 The filter accepts the following options:
8475 Set quality. This option defines the number of levels for averaging. It accepts
8476 an integer in the range 4-5. Default value is @code{4}.
8479 Force a constant quantization parameter. It accepts an integer in range 0-63.
8480 If not set, the filter will use the QP from the video stream (if available).
8483 Set filter strength. It accepts an integer in range -15 to 32. Lower values mean
8484 more details but also more artifacts, while higher values make the image smoother
8485 but also blurrier. Default value is @code{0} − PSNR optimal.
8488 Enable the use of the QP from the B-Frames if set to @code{1}. Using this
8489 option may cause flicker since the B-Frames have often larger QP. Default is
8490 @code{0} (not enabled).
8496 Apply Gaussian blur filter.
8498 The filter accepts the following options:
8502 Set horizontal sigma, standard deviation of Gaussian blur. Default is @code{0.5}.
8505 Set number of steps for Gaussian approximation. Defauls is @code{1}.
8508 Set which planes to filter. By default all planes are filtered.
8511 Set vertical sigma, if negative it will be same as @code{sigma}.
8512 Default is @code{-1}.
8517 The filter accepts the following options:
8521 Set the luminance expression.
8523 Set the chrominance blue expression.
8525 Set the chrominance red expression.
8527 Set the alpha expression.
8529 Set the red expression.
8531 Set the green expression.
8533 Set the blue expression.
8536 The colorspace is selected according to the specified options. If one
8537 of the @option{lum_expr}, @option{cb_expr}, or @option{cr_expr}
8538 options is specified, the filter will automatically select a YCbCr
8539 colorspace. If one of the @option{red_expr}, @option{green_expr}, or
8540 @option{blue_expr} options is specified, it will select an RGB
8543 If one of the chrominance expression is not defined, it falls back on the other
8544 one. If no alpha expression is specified it will evaluate to opaque value.
8545 If none of chrominance expressions are specified, they will evaluate
8546 to the luminance expression.
8548 The expressions can use the following variables and functions:
8552 The sequential number of the filtered frame, starting from @code{0}.
8556 The coordinates of the current sample.
8560 The width and height of the image.
8564 Width and height scale depending on the currently filtered plane. It is the
8565 ratio between the corresponding luma plane number of pixels and the current
8566 plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and
8567 @code{0.5,0.5} for chroma planes.
8570 Time of the current frame, expressed in seconds.
8573 Return the value of the pixel at location (@var{x},@var{y}) of the current
8577 Return the value of the pixel at location (@var{x},@var{y}) of the luminance
8581 Return the value of the pixel at location (@var{x},@var{y}) of the
8582 blue-difference chroma plane. Return 0 if there is no such plane.
8585 Return the value of the pixel at location (@var{x},@var{y}) of the
8586 red-difference chroma plane. Return 0 if there is no such plane.
8591 Return the value of the pixel at location (@var{x},@var{y}) of the
8592 red/green/blue component. Return 0 if there is no such component.
8595 Return the value of the pixel at location (@var{x},@var{y}) of the alpha
8596 plane. Return 0 if there is no such plane.
8599 For functions, if @var{x} and @var{y} are outside the area, the value will be
8600 automatically clipped to the closer edge.
8602 @subsection Examples
8606 Flip the image horizontally:
8612 Generate a bidimensional sine wave, with angle @code{PI/3} and a
8613 wavelength of 100 pixels:
8615 geq=128 + 100*sin(2*(PI/100)*(cos(PI/3)*(X-50*T) + sin(PI/3)*Y)):128:128
8619 Generate a fancy enigmatic moving light:
8621 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
8625 Generate a quick emboss effect:
8627 format=gray,geq=lum_expr='(p(X,Y)+(256-p(X-4,Y-4)))/2'
8631 Modify RGB components depending on pixel position:
8633 geq=r='X/W*r(X,Y)':g='(1-X/W)*g(X,Y)':b='(H-Y)/H*b(X,Y)'
8637 Create a radial gradient that is the same size as the input (also see
8638 the @ref{vignette} filter):
8640 geq=lum=255*gauss((X/W-0.5)*3)*gauss((Y/H-0.5)*3)/gauss(0)/gauss(0),format=gray
8646 Fix the banding artifacts that are sometimes introduced into nearly flat
8647 regions by truncation to 8-bit color depth.
8648 Interpolate the gradients that should go where the bands are, and
8651 It is designed for playback only. Do not use it prior to
8652 lossy compression, because compression tends to lose the dither and
8653 bring back the bands.
8655 It accepts the following parameters:
8660 The maximum amount by which the filter will change any one pixel. This is also
8661 the threshold for detecting nearly flat regions. Acceptable values range from
8662 .51 to 64; the default value is 1.2. Out-of-range values will be clipped to the
8666 The neighborhood to fit the gradient to. A larger radius makes for smoother
8667 gradients, but also prevents the filter from modifying the pixels near detailed
8668 regions. Acceptable values are 8-32; the default value is 16. Out-of-range
8669 values will be clipped to the valid range.
8673 Alternatively, the options can be specified as a flat string:
8674 @var{strength}[:@var{radius}]
8676 @subsection Examples
8680 Apply the filter with a @code{3.5} strength and radius of @code{8}:
8686 Specify radius, omitting the strength (which will fall-back to the default
8697 Apply a Hald CLUT to a video stream.
8699 First input is the video stream to process, and second one is the Hald CLUT.
8700 The Hald CLUT input can be a simple picture or a complete video stream.
8702 The filter accepts the following options:
8706 Force termination when the shortest input terminates. Default is @code{0}.
8708 Continue applying the last CLUT after the end of the stream. A value of
8709 @code{0} disable the filter after the last frame of the CLUT is reached.
8710 Default is @code{1}.
8713 @code{haldclut} also has the same interpolation options as @ref{lut3d} (both
8714 filters share the same internals).
8716 More information about the Hald CLUT can be found on Eskil Steenberg's website
8717 (Hald CLUT author) at @url{http://www.quelsolaar.com/technology/clut.html}.
8719 @subsection Workflow examples
8721 @subsubsection Hald CLUT video stream
8723 Generate an identity Hald CLUT stream altered with various effects:
8725 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
8728 Note: make sure you use a lossless codec.
8730 Then use it with @code{haldclut} to apply it on some random stream:
8732 ffmpeg -f lavfi -i mandelbrot -i clut.nut -filter_complex '[0][1] haldclut' -t 20 mandelclut.mkv
8735 The Hald CLUT will be applied to the 10 first seconds (duration of
8736 @file{clut.nut}), then the latest picture of that CLUT stream will be applied
8737 to the remaining frames of the @code{mandelbrot} stream.
8739 @subsubsection Hald CLUT with preview
8741 A Hald CLUT is supposed to be a squared image of @code{Level*Level*Level} by
8742 @code{Level*Level*Level} pixels. For a given Hald CLUT, FFmpeg will select the
8743 biggest possible square starting at the top left of the picture. The remaining
8744 padding pixels (bottom or right) will be ignored. This area can be used to add
8745 a preview of the Hald CLUT.
8747 Typically, the following generated Hald CLUT will be supported by the
8748 @code{haldclut} filter:
8751 ffmpeg -f lavfi -i @ref{haldclutsrc}=8 -vf "
8752 pad=iw+320 [padded_clut];
8753 smptebars=s=320x256, split [a][b];
8754 [padded_clut][a] overlay=W-320:h, curves=color_negative [main];
8755 [main][b] overlay=W-320" -frames:v 1 clut.png
8758 It contains the original and a preview of the effect of the CLUT: SMPTE color
8759 bars are displayed on the right-top, and below the same color bars processed by
8762 Then, the effect of this Hald CLUT can be visualized with:
8764 ffplay input.mkv -vf "movie=clut.png, [in] haldclut"
8769 Flip the input video horizontally.
8771 For example, to horizontally flip the input video with @command{ffmpeg}:
8773 ffmpeg -i in.avi -vf "hflip" out.avi
8777 This filter applies a global color histogram equalization on a
8780 It can be used to correct video that has a compressed range of pixel
8781 intensities. The filter redistributes the pixel intensities to
8782 equalize their distribution across the intensity range. It may be
8783 viewed as an "automatically adjusting contrast filter". This filter is
8784 useful only for correcting degraded or poorly captured source
8787 The filter accepts the following options:
8791 Determine the amount of equalization to be applied. As the strength
8792 is reduced, the distribution of pixel intensities more-and-more
8793 approaches that of the input frame. The value must be a float number
8794 in the range [0,1] and defaults to 0.200.
8797 Set the maximum intensity that can generated and scale the output
8798 values appropriately. The strength should be set as desired and then
8799 the intensity can be limited if needed to avoid washing-out. The value
8800 must be a float number in the range [0,1] and defaults to 0.210.
8803 Set the antibanding level. If enabled the filter will randomly vary
8804 the luminance of output pixels by a small amount to avoid banding of
8805 the histogram. Possible values are @code{none}, @code{weak} or
8806 @code{strong}. It defaults to @code{none}.
8811 Compute and draw a color distribution histogram for the input video.
8813 The computed histogram is a representation of the color component
8814 distribution in an image.
8816 Standard histogram displays the color components distribution in an image.
8817 Displays color graph for each color component. Shows distribution of
8818 the Y, U, V, A or R, G, B components, depending on input format, in the
8819 current frame. Below each graph a color component scale meter is shown.
8821 The filter accepts the following options:
8825 Set height of level. Default value is @code{200}.
8826 Allowed range is [50, 2048].
8829 Set height of color scale. Default value is @code{12}.
8830 Allowed range is [0, 40].
8834 It accepts the following values:
8837 Per color component graphs are placed below each other.
8840 Per color component graphs are placed side by side.
8843 Presents information identical to that in the @code{parade}, except
8844 that the graphs representing color components are superimposed directly
8847 Default is @code{stack}.
8850 Set mode. Can be either @code{linear}, or @code{logarithmic}.
8851 Default is @code{linear}.
8854 Set what color components to display.
8855 Default is @code{7}.
8858 Set foreground opacity. Default is @code{0.7}.
8861 Set background opacity. Default is @code{0.5}.
8864 @subsection Examples
8869 Calculate and draw histogram:
8871 ffplay -i input -vf histogram
8879 This is a high precision/quality 3d denoise filter. It aims to reduce
8880 image noise, producing smooth images and making still images really
8881 still. It should enhance compressibility.
8883 It accepts the following optional parameters:
8887 A non-negative floating point number which specifies spatial luma strength.
8890 @item chroma_spatial
8891 A non-negative floating point number which specifies spatial chroma strength.
8892 It defaults to 3.0*@var{luma_spatial}/4.0.
8895 A floating point number which specifies luma temporal strength. It defaults to
8896 6.0*@var{luma_spatial}/4.0.
8899 A floating point number which specifies chroma temporal strength. It defaults to
8900 @var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}.
8903 @anchor{hwupload_cuda}
8904 @section hwupload_cuda
8906 Upload system memory frames to a CUDA device.
8908 It accepts the following optional parameters:
8912 The number of the CUDA device to use
8917 Apply a high-quality magnification filter designed for pixel art. This filter
8918 was originally created by Maxim Stepin.
8920 It accepts the following option:
8924 Set the scaling dimension: @code{2} for @code{hq2x}, @code{3} for
8925 @code{hq3x} and @code{4} for @code{hq4x}.
8926 Default is @code{3}.
8930 Stack input videos horizontally.
8932 All streams must be of same pixel format and of same height.
8934 Note that this filter is faster than using @ref{overlay} and @ref{pad} filter
8935 to create same output.
8937 The filter accept the following option:
8941 Set number of input streams. Default is 2.
8944 If set to 1, force the output to terminate when the shortest input
8945 terminates. Default value is 0.
8950 Modify the hue and/or the saturation of the input.
8952 It accepts the following parameters:
8956 Specify the hue angle as a number of degrees. It accepts an expression,
8957 and defaults to "0".
8960 Specify the saturation in the [-10,10] range. It accepts an expression and
8964 Specify the hue angle as a number of radians. It accepts an
8965 expression, and defaults to "0".
8968 Specify the brightness in the [-10,10] range. It accepts an expression and
8972 @option{h} and @option{H} are mutually exclusive, and can't be
8973 specified at the same time.
8975 The @option{b}, @option{h}, @option{H} and @option{s} option values are
8976 expressions containing the following constants:
8980 frame count of the input frame starting from 0
8983 presentation timestamp of the input frame expressed in time base units
8986 frame rate of the input video, NAN if the input frame rate is unknown
8989 timestamp expressed in seconds, NAN if the input timestamp is unknown
8992 time base of the input video
8995 @subsection Examples
8999 Set the hue to 90 degrees and the saturation to 1.0:
9005 Same command but expressing the hue in radians:
9011 Rotate hue and make the saturation swing between 0
9012 and 2 over a period of 1 second:
9014 hue="H=2*PI*t: s=sin(2*PI*t)+1"
9018 Apply a 3 seconds saturation fade-in effect starting at 0:
9023 The general fade-in expression can be written as:
9025 hue="s=min(0\, max((t-START)/DURATION\, 1))"
9029 Apply a 3 seconds saturation fade-out effect starting at 5 seconds:
9031 hue="s=max(0\, min(1\, (8-t)/3))"
9034 The general fade-out expression can be written as:
9036 hue="s=max(0\, min(1\, (START+DURATION-t)/DURATION))"
9041 @subsection Commands
9043 This filter supports the following commands:
9049 Modify the hue and/or the saturation and/or brightness of the input video.
9050 The command accepts the same syntax of the corresponding option.
9052 If the specified expression is not valid, it is kept at its current
9058 Grow first stream into second stream by connecting components.
9059 This makes it possible to build more robust edge masks.
9061 This filter accepts the following options:
9065 Set which planes will be processed as bitmap, unprocessed planes will be
9066 copied from first stream.
9067 By default value 0xf, all planes will be processed.
9070 Set threshold which is used in filtering. If pixel component value is higher than
9071 this value filter algorithm for connecting components is activated.
9072 By default value is 0.
9077 Detect video interlacing type.
9079 This filter tries to detect if the input frames are interlaced, progressive,
9080 top or bottom field first. It will also try to detect fields that are
9081 repeated between adjacent frames (a sign of telecine).
9083 Single frame detection considers only immediately adjacent frames when classifying each frame.
9084 Multiple frame detection incorporates the classification history of previous frames.
9086 The filter will log these metadata values:
9089 @item single.current_frame
9090 Detected type of current frame using single-frame detection. One of:
9091 ``tff'' (top field first), ``bff'' (bottom field first),
9092 ``progressive'', or ``undetermined''
9095 Cumulative number of frames detected as top field first using single-frame detection.
9098 Cumulative number of frames detected as top field first using multiple-frame detection.
9101 Cumulative number of frames detected as bottom field first using single-frame detection.
9103 @item multiple.current_frame
9104 Detected type of current frame using multiple-frame detection. One of:
9105 ``tff'' (top field first), ``bff'' (bottom field first),
9106 ``progressive'', or ``undetermined''
9109 Cumulative number of frames detected as bottom field first using multiple-frame detection.
9111 @item single.progressive
9112 Cumulative number of frames detected as progressive using single-frame detection.
9114 @item multiple.progressive
9115 Cumulative number of frames detected as progressive using multiple-frame detection.
9117 @item single.undetermined
9118 Cumulative number of frames that could not be classified using single-frame detection.
9120 @item multiple.undetermined
9121 Cumulative number of frames that could not be classified using multiple-frame detection.
9123 @item repeated.current_frame
9124 Which field in the current frame is repeated from the last. One of ``neither'', ``top'', or ``bottom''.
9126 @item repeated.neither
9127 Cumulative number of frames with no repeated field.
9130 Cumulative number of frames with the top field repeated from the previous frame's top field.
9132 @item repeated.bottom
9133 Cumulative number of frames with the bottom field repeated from the previous frame's bottom field.
9136 The filter accepts the following options:
9140 Set interlacing threshold.
9142 Set progressive threshold.
9144 Threshold for repeated field detection.
9146 Number of frames after which a given frame's contribution to the
9147 statistics is halved (i.e., it contributes only 0.5 to its
9148 classification). The default of 0 means that all frames seen are given
9149 full weight of 1.0 forever.
9150 @item analyze_interlaced_flag
9151 When this is not 0 then idet will use the specified number of frames to determine
9152 if the interlaced flag is accurate, it will not count undetermined frames.
9153 If the flag is found to be accurate it will be used without any further
9154 computations, if it is found to be inaccurate it will be cleared without any
9155 further computations. This allows inserting the idet filter as a low computational
9156 method to clean up the interlaced flag
9161 Deinterleave or interleave fields.
9163 This filter allows one to process interlaced images fields without
9164 deinterlacing them. Deinterleaving splits the input frame into 2
9165 fields (so called half pictures). Odd lines are moved to the top
9166 half of the output image, even lines to the bottom half.
9167 You can process (filter) them independently and then re-interleave them.
9169 The filter accepts the following options:
9173 @item chroma_mode, c
9175 Available values for @var{luma_mode}, @var{chroma_mode} and
9176 @var{alpha_mode} are:
9182 @item deinterleave, d
9183 Deinterleave fields, placing one above the other.
9186 Interleave fields. Reverse the effect of deinterleaving.
9188 Default value is @code{none}.
9191 @item chroma_swap, cs
9192 @item alpha_swap, as
9193 Swap luma/chroma/alpha fields. Exchange even & odd lines. Default value is @code{0}.
9198 Apply inflate effect to the video.
9200 This filter replaces the pixel by the local(3x3) average by taking into account
9201 only values higher than the pixel.
9203 It accepts the following options:
9210 Limit the maximum change for each plane, default is 65535.
9211 If 0, plane will remain unchanged.
9216 Simple interlacing filter from progressive contents. This interleaves upper (or
9217 lower) lines from odd frames with lower (or upper) lines from even frames,
9218 halving the frame rate and preserving image height.
9221 Original Original New Frame
9222 Frame 'j' Frame 'j+1' (tff)
9223 ========== =========== ==================
9224 Line 0 --------------------> Frame 'j' Line 0
9225 Line 1 Line 1 ----> Frame 'j+1' Line 1
9226 Line 2 ---------------------> Frame 'j' Line 2
9227 Line 3 Line 3 ----> Frame 'j+1' Line 3
9229 New Frame + 1 will be generated by Frame 'j+2' and Frame 'j+3' and so on
9232 It accepts the following optional parameters:
9236 This determines whether the interlaced frame is taken from the even
9237 (tff - default) or odd (bff) lines of the progressive frame.
9240 Vertical lowpass filter to avoid twitter interlacing and
9241 reduce moire patterns.
9245 Disable vertical lowpass filter
9248 Enable linear filter (default)
9251 Enable complex filter. This will slightly less reduce twitter and moire
9252 but better retain detail and subjective sharpness impression.
9259 Deinterlace input video by applying Donald Graft's adaptive kernel
9260 deinterling. Work on interlaced parts of a video to produce
9263 The description of the accepted parameters follows.
9267 Set the threshold which affects the filter's tolerance when
9268 determining if a pixel line must be processed. It must be an integer
9269 in the range [0,255] and defaults to 10. A value of 0 will result in
9270 applying the process on every pixels.
9273 Paint pixels exceeding the threshold value to white if set to 1.
9277 Set the fields order. Swap fields if set to 1, leave fields alone if
9281 Enable additional sharpening if set to 1. Default is 0.
9284 Enable twoway sharpening if set to 1. Default is 0.
9287 @subsection Examples
9291 Apply default values:
9293 kerndeint=thresh=10:map=0:order=0:sharp=0:twoway=0
9297 Enable additional sharpening:
9303 Paint processed pixels in white:
9309 @section lenscorrection
9311 Correct radial lens distortion
9313 This filter can be used to correct for radial distortion as can result from the use
9314 of wide angle lenses, and thereby re-rectify the image. To find the right parameters
9315 one can use tools available for example as part of opencv or simply trial-and-error.
9316 To use opencv use the calibration sample (under samples/cpp) from the opencv sources
9317 and extract the k1 and k2 coefficients from the resulting matrix.
9319 Note that effectively the same filter is available in the open-source tools Krita and
9320 Digikam from the KDE project.
9322 In contrast to the @ref{vignette} filter, which can also be used to compensate lens errors,
9323 this filter corrects the distortion of the image, whereas @ref{vignette} corrects the
9324 brightness distribution, so you may want to use both filters together in certain
9325 cases, though you will have to take care of ordering, i.e. whether vignetting should
9326 be applied before or after lens correction.
9330 The filter accepts the following options:
9334 Relative x-coordinate of the focal point of the image, and thereby the center of the
9335 distortion. This value has a range [0,1] and is expressed as fractions of the image
9338 Relative y-coordinate of the focal point of the image, and thereby the center of the
9339 distortion. This value has a range [0,1] and is expressed as fractions of the image
9342 Coefficient of the quadratic correction term. 0.5 means no correction.
9344 Coefficient of the double quadratic correction term. 0.5 means no correction.
9347 The formula that generates the correction is:
9349 @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)
9351 where @var{r_0} is halve of the image diagonal and @var{r_src} and @var{r_tgt} are the
9352 distances from the focal point in the source and target images, respectively.
9358 The filter accepts the following options:
9362 Set the number of loops.
9365 Set maximal size in number of frames.
9368 Set first frame of loop.
9374 Apply a 3D LUT to an input video.
9376 The filter accepts the following options:
9380 Set the 3D LUT file name.
9382 Currently supported formats:
9394 Select interpolation mode.
9396 Available values are:
9400 Use values from the nearest defined point.
9402 Interpolate values using the 8 points defining a cube.
9404 Interpolate values using a tetrahedron.
9410 Turn certain luma values into transparency.
9412 The filter accepts the following options:
9416 Set the luma which will be used as base for transparency.
9417 Default value is @code{0}.
9420 Set the range of luma values to be keyed out.
9421 Default value is @code{0}.
9424 Set the range of softness. Default value is @code{0}.
9425 Use this to control gradual transition from zero to full transparency.
9428 @section lut, lutrgb, lutyuv
9430 Compute a look-up table for binding each pixel component input value
9431 to an output value, and apply it to the input video.
9433 @var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb}
9434 to an RGB input video.
9436 These filters accept the following parameters:
9439 set first pixel component expression
9441 set second pixel component expression
9443 set third pixel component expression
9445 set fourth pixel component expression, corresponds to the alpha component
9448 set red component expression
9450 set green component expression
9452 set blue component expression
9454 alpha component expression
9457 set Y/luminance component expression
9459 set U/Cb component expression
9461 set V/Cr component expression
9464 Each of them specifies the expression to use for computing the lookup table for
9465 the corresponding pixel component values.
9467 The exact component associated to each of the @var{c*} options depends on the
9470 The @var{lut} filter requires either YUV or RGB pixel formats in input,
9471 @var{lutrgb} requires RGB pixel formats in input, and @var{lutyuv} requires YUV.
9473 The expressions can contain the following constants and functions:
9478 The input width and height.
9481 The input value for the pixel component.
9484 The input value, clipped to the @var{minval}-@var{maxval} range.
9487 The maximum value for the pixel component.
9490 The minimum value for the pixel component.
9493 The negated value for the pixel component value, clipped to the
9494 @var{minval}-@var{maxval} range; it corresponds to the expression
9495 "maxval-clipval+minval".
9498 The computed value in @var{val}, clipped to the
9499 @var{minval}-@var{maxval} range.
9501 @item gammaval(gamma)
9502 The computed gamma correction value of the pixel component value,
9503 clipped to the @var{minval}-@var{maxval} range. It corresponds to the
9505 "pow((clipval-minval)/(maxval-minval)\,@var{gamma})*(maxval-minval)+minval"
9509 All expressions default to "val".
9511 @subsection Examples
9517 lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val"
9518 lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val"
9521 The above is the same as:
9523 lutrgb="r=negval:g=negval:b=negval"
9524 lutyuv="y=negval:u=negval:v=negval"
9534 Remove chroma components, turning the video into a graytone image:
9536 lutyuv="u=128:v=128"
9540 Apply a luma burning effect:
9546 Remove green and blue components:
9552 Set a constant alpha channel value on input:
9554 format=rgba,lutrgb=a="maxval-minval/2"
9558 Correct luminance gamma by a factor of 0.5:
9560 lutyuv=y=gammaval(0.5)
9564 Discard least significant bits of luma:
9566 lutyuv=y='bitand(val, 128+64+32)'
9570 Technicolor like effect:
9572 lutyuv=u='(val-maxval/2)*2+maxval/2':v='(val-maxval/2)*2+maxval/2'
9578 Compute and apply a lookup table from two video inputs.
9580 This filter accepts the following parameters:
9583 set first pixel component expression
9585 set second pixel component expression
9587 set third pixel component expression
9589 set fourth pixel component expression, corresponds to the alpha component
9592 Each of them specifies the expression to use for computing the lookup table for
9593 the corresponding pixel component values.
9595 The exact component associated to each of the @var{c*} options depends on the
9598 The expressions can contain the following constants:
9603 The input width and height.
9606 The first input value for the pixel component.
9609 The second input value for the pixel component.
9612 The first input video bit depth.
9615 The second input video bit depth.
9618 All expressions default to "x".
9620 @subsection Examples
9624 Highlight differences between two RGB video streams:
9626 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)'
9630 Highlight differences between two YUV video streams:
9632 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)'
9636 @section maskedclamp
9638 Clamp the first input stream with the second input and third input stream.
9640 Returns the value of first stream to be between second input
9641 stream - @code{undershoot} and third input stream + @code{overshoot}.
9643 This filter accepts the following options:
9646 Default value is @code{0}.
9649 Default value is @code{0}.
9652 Set which planes will be processed as bitmap, unprocessed planes will be
9653 copied from first stream.
9654 By default value 0xf, all planes will be processed.
9657 @section maskedmerge
9659 Merge the first input stream with the second input stream using per pixel
9660 weights in the third input stream.
9662 A value of 0 in the third stream pixel component means that pixel component
9663 from first stream is returned unchanged, while maximum value (eg. 255 for
9664 8-bit videos) means that pixel component from second stream is returned
9665 unchanged. Intermediate values define the amount of merging between both
9666 input stream's pixel components.
9668 This filter accepts the following options:
9671 Set which planes will be processed as bitmap, unprocessed planes will be
9672 copied from first stream.
9673 By default value 0xf, all planes will be processed.
9678 Apply motion-compensation deinterlacing.
9680 It needs one field per frame as input and must thus be used together
9681 with yadif=1/3 or equivalent.
9683 This filter accepts the following options:
9686 Set the deinterlacing mode.
9688 It accepts one of the following values:
9693 use iterative motion estimation
9695 like @samp{slow}, but use multiple reference frames.
9697 Default value is @samp{fast}.
9700 Set the picture field parity assumed for the input video. It must be
9701 one of the following values:
9705 assume top field first
9707 assume bottom field first
9710 Default value is @samp{bff}.
9713 Set per-block quantization parameter (QP) used by the internal
9716 Higher values should result in a smoother motion vector field but less
9717 optimal individual vectors. Default value is 1.
9720 @section mergeplanes
9722 Merge color channel components from several video streams.
9724 The filter accepts up to 4 input streams, and merge selected input
9725 planes to the output video.
9727 This filter accepts the following options:
9730 Set input to output plane mapping. Default is @code{0}.
9732 The mappings is specified as a bitmap. It should be specified as a
9733 hexadecimal number in the form 0xAa[Bb[Cc[Dd]]]. 'Aa' describes the
9734 mapping for the first plane of the output stream. 'A' sets the number of
9735 the input stream to use (from 0 to 3), and 'a' the plane number of the
9736 corresponding input to use (from 0 to 3). The rest of the mappings is
9737 similar, 'Bb' describes the mapping for the output stream second
9738 plane, 'Cc' describes the mapping for the output stream third plane and
9739 'Dd' describes the mapping for the output stream fourth plane.
9742 Set output pixel format. Default is @code{yuva444p}.
9745 @subsection Examples
9749 Merge three gray video streams of same width and height into single video stream:
9751 [a0][a1][a2]mergeplanes=0x001020:yuv444p
9755 Merge 1st yuv444p stream and 2nd gray video stream into yuva444p video stream:
9757 [a0][a1]mergeplanes=0x00010210:yuva444p
9761 Swap Y and A plane in yuva444p stream:
9763 format=yuva444p,mergeplanes=0x03010200:yuva444p
9767 Swap U and V plane in yuv420p stream:
9769 format=yuv420p,mergeplanes=0x000201:yuv420p
9773 Cast a rgb24 clip to yuv444p:
9775 format=rgb24,mergeplanes=0x000102:yuv444p
9781 Estimate and export motion vectors using block matching algorithms.
9782 Motion vectors are stored in frame side data to be used by other filters.
9784 This filter accepts the following options:
9787 Specify the motion estimation method. Accepts one of the following values:
9791 Exhaustive search algorithm.
9793 Three step search algorithm.
9795 Two dimensional logarithmic search algorithm.
9797 New three step search algorithm.
9799 Four step search algorithm.
9801 Diamond search algorithm.
9803 Hexagon-based search algorithm.
9805 Enhanced predictive zonal search algorithm.
9807 Uneven multi-hexagon search algorithm.
9809 Default value is @samp{esa}.
9812 Macroblock size. Default @code{16}.
9815 Search parameter. Default @code{7}.
9818 @section midequalizer
9820 Apply Midway Image Equalization effect using two video streams.
9822 Midway Image Equalization adjusts a pair of images to have the same
9823 histogram, while maintaining their dynamics as much as possible. It's
9824 useful for e.g. matching exposures from a pair of stereo cameras.
9826 This filter has two inputs and one output, which must be of same pixel format, but
9827 may be of different sizes. The output of filter is first input adjusted with
9828 midway histogram of both inputs.
9830 This filter accepts the following option:
9834 Set which planes to process. Default is @code{15}, which is all available planes.
9837 @section minterpolate
9839 Convert the video to specified frame rate using motion interpolation.
9841 This filter accepts the following options:
9844 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}.
9847 Motion interpolation mode. Following values are accepted:
9850 Duplicate previous or next frame for interpolating new ones.
9852 Blend source frames. Interpolated frame is mean of previous and next frames.
9854 Motion compensated interpolation. Following options are effective when this mode is selected:
9858 Motion compensation mode. Following values are accepted:
9861 Overlapped block motion compensation.
9863 Adaptive overlapped block motion compensation. Window weighting coefficients are controlled adaptively according to the reliabilities of the neighboring motion vectors to reduce oversmoothing.
9865 Default mode is @samp{obmc}.
9868 Motion estimation mode. Following values are accepted:
9871 Bidirectional motion estimation. Motion vectors are estimated for each source frame in both forward and backward directions.
9873 Bilateral motion estimation. Motion vectors are estimated directly for interpolated frame.
9875 Default mode is @samp{bilat}.
9878 The algorithm to be used for motion estimation. Following values are accepted:
9881 Exhaustive search algorithm.
9883 Three step search algorithm.
9885 Two dimensional logarithmic search algorithm.
9887 New three step search algorithm.
9889 Four step search algorithm.
9891 Diamond search algorithm.
9893 Hexagon-based search algorithm.
9895 Enhanced predictive zonal search algorithm.
9897 Uneven multi-hexagon search algorithm.
9899 Default algorithm is @samp{epzs}.
9902 Macroblock size. Default @code{16}.
9905 Motion estimation search parameter. Default @code{32}.
9908 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).
9913 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:
9916 Disable scene change detection.
9918 Frame difference. Corresponding pixel values are compared and if it satisfies @var{scd_threshold} scene change is detected.
9920 Default method is @samp{fdiff}.
9923 Scene change detection threshold. Default is @code{5.0}.
9928 Drop frames that do not differ greatly from the previous frame in
9929 order to reduce frame rate.
9931 The main use of this filter is for very-low-bitrate encoding
9932 (e.g. streaming over dialup modem), but it could in theory be used for
9933 fixing movies that were inverse-telecined incorrectly.
9935 A description of the accepted options follows.
9939 Set the maximum number of consecutive frames which can be dropped (if
9940 positive), or the minimum interval between dropped frames (if
9941 negative). If the value is 0, the frame is dropped unregarding the
9942 number of previous sequentially dropped frames.
9949 Set the dropping threshold values.
9951 Values for @option{hi} and @option{lo} are for 8x8 pixel blocks and
9952 represent actual pixel value differences, so a threshold of 64
9953 corresponds to 1 unit of difference for each pixel, or the same spread
9954 out differently over the block.
9956 A frame is a candidate for dropping if no 8x8 blocks differ by more
9957 than a threshold of @option{hi}, and if no more than @option{frac} blocks (1
9958 meaning the whole image) differ by more than a threshold of @option{lo}.
9960 Default value for @option{hi} is 64*12, default value for @option{lo} is
9961 64*5, and default value for @option{frac} is 0.33.
9969 It accepts an integer in input; if non-zero it negates the
9970 alpha component (if available). The default value in input is 0.
9974 Denoise frames using Non-Local Means algorithm.
9976 Each pixel is adjusted by looking for other pixels with similar contexts. This
9977 context similarity is defined by comparing their surrounding patches of size
9978 @option{p}x@option{p}. Patches are searched in an area of @option{r}x@option{r}
9981 Note that the research area defines centers for patches, which means some
9982 patches will be made of pixels outside that research area.
9984 The filter accepts the following options.
9988 Set denoising strength.
9994 Same as @option{p} but for chroma planes.
9996 The default value is @var{0} and means automatic.
10002 Same as @option{r} but for chroma planes.
10004 The default value is @var{0} and means automatic.
10009 Deinterlace video using neural network edge directed interpolation.
10011 This filter accepts the following options:
10015 Mandatory option, without binary file filter can not work.
10016 Currently file can be found here:
10017 https://github.com/dubhater/vapoursynth-nnedi3/blob/master/src/nnedi3_weights.bin
10020 Set which frames to deinterlace, by default it is @code{all}.
10021 Can be @code{all} or @code{interlaced}.
10024 Set mode of operation.
10026 Can be one of the following:
10030 Use frame flags, both fields.
10032 Use frame flags, single field.
10034 Use top field only.
10036 Use bottom field only.
10038 Use both fields, top first.
10040 Use both fields, bottom first.
10044 Set which planes to process, by default filter process all frames.
10047 Set size of local neighborhood around each pixel, used by the predictor neural
10050 Can be one of the following:
10063 Set the number of neurons in predicctor neural network.
10064 Can be one of the following:
10075 Controls the number of different neural network predictions that are blended
10076 together to compute the final output value. Can be @code{fast}, default or
10080 Set which set of weights to use in the predictor.
10081 Can be one of the following:
10085 weights trained to minimize absolute error
10087 weights trained to minimize squared error
10091 Controls whether or not the prescreener neural network is used to decide
10092 which pixels should be processed by the predictor neural network and which
10093 can be handled by simple cubic interpolation.
10094 The prescreener is trained to know whether cubic interpolation will be
10095 sufficient for a pixel or whether it should be predicted by the predictor nn.
10096 The computational complexity of the prescreener nn is much less than that of
10097 the predictor nn. Since most pixels can be handled by cubic interpolation,
10098 using the prescreener generally results in much faster processing.
10099 The prescreener is pretty accurate, so the difference between using it and not
10100 using it is almost always unnoticeable.
10102 Can be one of the following:
10110 Default is @code{new}.
10113 Set various debugging flags.
10118 Force libavfilter not to use any of the specified pixel formats for the
10119 input to the next filter.
10121 It accepts the following parameters:
10125 A '|'-separated list of pixel format names, such as
10126 apix_fmts=yuv420p|monow|rgb24".
10130 @subsection Examples
10134 Force libavfilter to use a format different from @var{yuv420p} for the
10135 input to the vflip filter:
10137 noformat=pix_fmts=yuv420p,vflip
10141 Convert the input video to any of the formats not contained in the list:
10143 noformat=yuv420p|yuv444p|yuv410p
10149 Add noise on video input frame.
10151 The filter accepts the following options:
10159 Set noise seed for specific pixel component or all pixel components in case
10160 of @var{all_seed}. Default value is @code{123457}.
10162 @item all_strength, alls
10163 @item c0_strength, c0s
10164 @item c1_strength, c1s
10165 @item c2_strength, c2s
10166 @item c3_strength, c3s
10167 Set noise strength for specific pixel component or all pixel components in case
10168 @var{all_strength}. Default value is @code{0}. Allowed range is [0, 100].
10170 @item all_flags, allf
10171 @item c0_flags, c0f
10172 @item c1_flags, c1f
10173 @item c2_flags, c2f
10174 @item c3_flags, c3f
10175 Set pixel component flags or set flags for all components if @var{all_flags}.
10176 Available values for component flags are:
10179 averaged temporal noise (smoother)
10181 mix random noise with a (semi)regular pattern
10183 temporal noise (noise pattern changes between frames)
10185 uniform noise (gaussian otherwise)
10189 @subsection Examples
10191 Add temporal and uniform noise to input video:
10193 noise=alls=20:allf=t+u
10198 Pass the video source unchanged to the output.
10201 Optical Character Recognition
10203 This filter uses Tesseract for optical character recognition.
10205 It accepts the following options:
10209 Set datapath to tesseract data. Default is to use whatever was
10210 set at installation.
10213 Set language, default is "eng".
10216 Set character whitelist.
10219 Set character blacklist.
10222 The filter exports recognized text as the frame metadata @code{lavfi.ocr.text}.
10226 Apply a video transform using libopencv.
10228 To enable this filter, install the libopencv library and headers and
10229 configure FFmpeg with @code{--enable-libopencv}.
10231 It accepts the following parameters:
10236 The name of the libopencv filter to apply.
10238 @item filter_params
10239 The parameters to pass to the libopencv filter. If not specified, the default
10240 values are assumed.
10244 Refer to the official libopencv documentation for more precise
10246 @url{http://docs.opencv.org/master/modules/imgproc/doc/filtering.html}
10248 Several libopencv filters are supported; see the following subsections.
10253 Dilate an image by using a specific structuring element.
10254 It corresponds to the libopencv function @code{cvDilate}.
10256 It accepts the parameters: @var{struct_el}|@var{nb_iterations}.
10258 @var{struct_el} represents a structuring element, and has the syntax:
10259 @var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape}
10261 @var{cols} and @var{rows} represent the number of columns and rows of
10262 the structuring element, @var{anchor_x} and @var{anchor_y} the anchor
10263 point, and @var{shape} the shape for the structuring element. @var{shape}
10264 must be "rect", "cross", "ellipse", or "custom".
10266 If the value for @var{shape} is "custom", it must be followed by a
10267 string of the form "=@var{filename}". The file with name
10268 @var{filename} is assumed to represent a binary image, with each
10269 printable character corresponding to a bright pixel. When a custom
10270 @var{shape} is used, @var{cols} and @var{rows} are ignored, the number
10271 or columns and rows of the read file are assumed instead.
10273 The default value for @var{struct_el} is "3x3+0x0/rect".
10275 @var{nb_iterations} specifies the number of times the transform is
10276 applied to the image, and defaults to 1.
10280 # Use the default values
10283 # Dilate using a structuring element with a 5x5 cross, iterating two times
10284 ocv=filter_name=dilate:filter_params=5x5+2x2/cross|2
10286 # Read the shape from the file diamond.shape, iterating two times.
10287 # The file diamond.shape may contain a pattern of characters like this
10293 # The specified columns and rows are ignored
10294 # but the anchor point coordinates are not
10295 ocv=dilate:0x0+2x2/custom=diamond.shape|2
10300 Erode an image by using a specific structuring element.
10301 It corresponds to the libopencv function @code{cvErode}.
10303 It accepts the parameters: @var{struct_el}:@var{nb_iterations},
10304 with the same syntax and semantics as the @ref{dilate} filter.
10308 Smooth the input video.
10310 The filter takes the following parameters:
10311 @var{type}|@var{param1}|@var{param2}|@var{param3}|@var{param4}.
10313 @var{type} is the type of smooth filter to apply, and must be one of
10314 the following values: "blur", "blur_no_scale", "median", "gaussian",
10315 or "bilateral". The default value is "gaussian".
10317 The meaning of @var{param1}, @var{param2}, @var{param3}, and @var{param4}
10318 depend on the smooth type. @var{param1} and
10319 @var{param2} accept integer positive values or 0. @var{param3} and
10320 @var{param4} accept floating point values.
10322 The default value for @var{param1} is 3. The default value for the
10323 other parameters is 0.
10325 These parameters correspond to the parameters assigned to the
10326 libopencv function @code{cvSmooth}.
10328 @section oscilloscope
10330 2D Video Oscilloscope.
10332 Useful to measure spatial impulse, step responses, chroma delays, etc.
10334 It accepts the following parameters:
10338 Set scope center x position.
10341 Set scope center y position.
10344 Set scope size, relative to frame diagonal.
10347 Set scope tilt/rotation.
10353 Set trace center x position.
10356 Set trace center y position.
10359 Set trace width, relative to width of frame.
10362 Set trace height, relative to height of frame.
10365 Set which components to trace. By default it traces first three components.
10368 Draw trace grid. By default is enabled.
10371 Draw some statistics. By default is enabled.
10374 Draw scope. By default is enabled.
10377 @subsection Examples
10381 Inspect full first row of video frame.
10383 oscilloscope=x=0.5:y=0:s=1
10387 Inspect full last row of video frame.
10389 oscilloscope=x=0.5:y=1:s=1
10393 Inspect full 5th line of video frame of height 1080.
10395 oscilloscope=x=0.5:y=5/1080:s=1
10399 Inspect full last column of video frame.
10401 oscilloscope=x=1:y=0.5:s=1:t=1
10409 Overlay one video on top of another.
10411 It takes two inputs and has one output. The first input is the "main"
10412 video on which the second input is overlaid.
10414 It accepts the following parameters:
10416 A description of the accepted options follows.
10421 Set the expression for the x and y coordinates of the overlaid video
10422 on the main video. Default value is "0" for both expressions. In case
10423 the expression is invalid, it is set to a huge value (meaning that the
10424 overlay will not be displayed within the output visible area).
10427 The action to take when EOF is encountered on the secondary input; it accepts
10428 one of the following values:
10432 Repeat the last frame (the default).
10436 Pass the main input through.
10440 Set when the expressions for @option{x}, and @option{y} are evaluated.
10442 It accepts the following values:
10445 only evaluate expressions once during the filter initialization or
10446 when a command is processed
10449 evaluate expressions for each incoming frame
10452 Default value is @samp{frame}.
10455 If set to 1, force the output to terminate when the shortest input
10456 terminates. Default value is 0.
10459 Set the format for the output video.
10461 It accepts the following values:
10464 force YUV420 output
10467 force YUV422 output
10470 force YUV444 output
10473 force packed RGB output
10476 force planar RGB output
10479 Default value is @samp{yuv420}.
10481 @item rgb @emph{(deprecated)}
10482 If set to 1, force the filter to accept inputs in the RGB
10483 color space. Default value is 0. This option is deprecated, use
10484 @option{format} instead.
10487 If set to 1, force the filter to draw the last overlay frame over the
10488 main input until the end of the stream. A value of 0 disables this
10489 behavior. Default value is 1.
10492 The @option{x}, and @option{y} expressions can contain the following
10498 The main input width and height.
10502 The overlay input width and height.
10506 The computed values for @var{x} and @var{y}. They are evaluated for
10511 horizontal and vertical chroma subsample values of the output
10512 format. For example for the pixel format "yuv422p" @var{hsub} is 2 and
10516 the number of input frame, starting from 0
10519 the position in the file of the input frame, NAN if unknown
10522 The timestamp, expressed in seconds. It's NAN if the input timestamp is unknown.
10526 Note that the @var{n}, @var{pos}, @var{t} variables are available only
10527 when evaluation is done @emph{per frame}, and will evaluate to NAN
10528 when @option{eval} is set to @samp{init}.
10530 Be aware that frames are taken from each input video in timestamp
10531 order, hence, if their initial timestamps differ, it is a good idea
10532 to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to
10533 have them begin in the same zero timestamp, as the example for
10534 the @var{movie} filter does.
10536 You can chain together more overlays but you should test the
10537 efficiency of such approach.
10539 @subsection Commands
10541 This filter supports the following commands:
10545 Modify the x and y of the overlay input.
10546 The command accepts the same syntax of the corresponding option.
10548 If the specified expression is not valid, it is kept at its current
10552 @subsection Examples
10556 Draw the overlay at 10 pixels from the bottom right corner of the main
10559 overlay=main_w-overlay_w-10:main_h-overlay_h-10
10562 Using named options the example above becomes:
10564 overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10
10568 Insert a transparent PNG logo in the bottom left corner of the input,
10569 using the @command{ffmpeg} tool with the @code{-filter_complex} option:
10571 ffmpeg -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output
10575 Insert 2 different transparent PNG logos (second logo on bottom
10576 right corner) using the @command{ffmpeg} tool:
10578 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
10582 Add a transparent color layer on top of the main video; @code{WxH}
10583 must specify the size of the main input to the overlay filter:
10585 color=color=red@@.3:size=WxH [over]; [in][over] overlay [out]
10589 Play an original video and a filtered version (here with the deshake
10590 filter) side by side using the @command{ffplay} tool:
10592 ffplay input.avi -vf 'split[a][b]; [a]pad=iw*2:ih[src]; [b]deshake[filt]; [src][filt]overlay=w'
10595 The above command is the same as:
10597 ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w'
10601 Make a sliding overlay appearing from the left to the right top part of the
10602 screen starting since time 2:
10604 overlay=x='if(gte(t,2), -w+(t-2)*20, NAN)':y=0
10608 Compose output by putting two input videos side to side:
10610 ffmpeg -i left.avi -i right.avi -filter_complex "
10611 nullsrc=size=200x100 [background];
10612 [0:v] setpts=PTS-STARTPTS, scale=100x100 [left];
10613 [1:v] setpts=PTS-STARTPTS, scale=100x100 [right];
10614 [background][left] overlay=shortest=1 [background+left];
10615 [background+left][right] overlay=shortest=1:x=100 [left+right]
10620 Mask 10-20 seconds of a video by applying the delogo filter to a section
10622 ffmpeg -i test.avi -codec:v:0 wmv2 -ar 11025 -b:v 9000k
10623 -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]'
10628 Chain several overlays in cascade:
10630 nullsrc=s=200x200 [bg];
10631 testsrc=s=100x100, split=4 [in0][in1][in2][in3];
10632 [in0] lutrgb=r=0, [bg] overlay=0:0 [mid0];
10633 [in1] lutrgb=g=0, [mid0] overlay=100:0 [mid1];
10634 [in2] lutrgb=b=0, [mid1] overlay=0:100 [mid2];
10635 [in3] null, [mid2] overlay=100:100 [out0]
10642 Apply Overcomplete Wavelet denoiser.
10644 The filter accepts the following options:
10650 Larger depth values will denoise lower frequency components more, but
10651 slow down filtering.
10653 Must be an int in the range 8-16, default is @code{8}.
10655 @item luma_strength, ls
10658 Must be a double value in the range 0-1000, default is @code{1.0}.
10660 @item chroma_strength, cs
10661 Set chroma strength.
10663 Must be a double value in the range 0-1000, default is @code{1.0}.
10669 Add paddings to the input image, and place the original input at the
10670 provided @var{x}, @var{y} coordinates.
10672 It accepts the following parameters:
10677 Specify an expression for the size of the output image with the
10678 paddings added. If the value for @var{width} or @var{height} is 0, the
10679 corresponding input size is used for the output.
10681 The @var{width} expression can reference the value set by the
10682 @var{height} expression, and vice versa.
10684 The default value of @var{width} and @var{height} is 0.
10688 Specify the offsets to place the input image at within the padded area,
10689 with respect to the top/left border of the output image.
10691 The @var{x} expression can reference the value set by the @var{y}
10692 expression, and vice versa.
10694 The default value of @var{x} and @var{y} is 0.
10696 If @var{x} or @var{y} evaluate to a negative number, they'll be changed
10697 so the input image is centered on the padded area.
10700 Specify the color of the padded area. For the syntax of this option,
10701 check the "Color" section in the ffmpeg-utils manual.
10703 The default value of @var{color} is "black".
10706 Specify when to evaluate @var{width}, @var{height}, @var{x} and @var{y} expression.
10708 It accepts the following values:
10712 Only evaluate expressions once during the filter initialization or when
10713 a command is processed.
10716 Evaluate expressions for each incoming frame.
10720 Default value is @samp{init}.
10723 Pad to aspect instead to a resolution.
10727 The value for the @var{width}, @var{height}, @var{x}, and @var{y}
10728 options are expressions containing the following constants:
10733 The input video width and height.
10737 These are the same as @var{in_w} and @var{in_h}.
10741 The output width and height (the size of the padded area), as
10742 specified by the @var{width} and @var{height} expressions.
10746 These are the same as @var{out_w} and @var{out_h}.
10750 The x and y offsets as specified by the @var{x} and @var{y}
10751 expressions, or NAN if not yet specified.
10754 same as @var{iw} / @var{ih}
10757 input sample aspect ratio
10760 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
10764 The horizontal and vertical chroma subsample values. For example for the
10765 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
10768 @subsection Examples
10772 Add paddings with the color "violet" to the input video. The output video
10773 size is 640x480, and the top-left corner of the input video is placed at
10776 pad=640:480:0:40:violet
10779 The example above is equivalent to the following command:
10781 pad=width=640:height=480:x=0:y=40:color=violet
10785 Pad the input to get an output with dimensions increased by 3/2,
10786 and put the input video at the center of the padded area:
10788 pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2"
10792 Pad the input to get a squared output with size equal to the maximum
10793 value between the input width and height, and put the input video at
10794 the center of the padded area:
10796 pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2"
10800 Pad the input to get a final w/h ratio of 16:9:
10802 pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2"
10806 In case of anamorphic video, in order to set the output display aspect
10807 correctly, it is necessary to use @var{sar} in the expression,
10808 according to the relation:
10810 (ih * X / ih) * sar = output_dar
10811 X = output_dar / sar
10814 Thus the previous example needs to be modified to:
10816 pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2"
10820 Double the output size and put the input video in the bottom-right
10821 corner of the output padded area:
10823 pad="2*iw:2*ih:ow-iw:oh-ih"
10827 @anchor{palettegen}
10828 @section palettegen
10830 Generate one palette for a whole video stream.
10832 It accepts the following options:
10836 Set the maximum number of colors to quantize in the palette.
10837 Note: the palette will still contain 256 colors; the unused palette entries
10840 @item reserve_transparent
10841 Create a palette of 255 colors maximum and reserve the last one for
10842 transparency. Reserving the transparency color is useful for GIF optimization.
10843 If not set, the maximum of colors in the palette will be 256. You probably want
10844 to disable this option for a standalone image.
10848 Set statistics mode.
10850 It accepts the following values:
10853 Compute full frame histograms.
10855 Compute histograms only for the part that differs from previous frame. This
10856 might be relevant to give more importance to the moving part of your input if
10857 the background is static.
10859 Compute new histogram for each frame.
10862 Default value is @var{full}.
10865 The filter also exports the frame metadata @code{lavfi.color_quant_ratio}
10866 (@code{nb_color_in / nb_color_out}) which you can use to evaluate the degree of
10867 color quantization of the palette. This information is also visible at
10868 @var{info} logging level.
10870 @subsection Examples
10874 Generate a representative palette of a given video using @command{ffmpeg}:
10876 ffmpeg -i input.mkv -vf palettegen palette.png
10880 @section paletteuse
10882 Use a palette to downsample an input video stream.
10884 The filter takes two inputs: one video stream and a palette. The palette must
10885 be a 256 pixels image.
10887 It accepts the following options:
10891 Select dithering mode. Available algorithms are:
10894 Ordered 8x8 bayer dithering (deterministic)
10896 Dithering as defined by Paul Heckbert in 1982 (simple error diffusion).
10897 Note: this dithering is sometimes considered "wrong" and is included as a
10899 @item floyd_steinberg
10900 Floyd and Steingberg dithering (error diffusion)
10902 Frankie Sierra dithering v2 (error diffusion)
10904 Frankie Sierra dithering v2 "Lite" (error diffusion)
10907 Default is @var{sierra2_4a}.
10910 When @var{bayer} dithering is selected, this option defines the scale of the
10911 pattern (how much the crosshatch pattern is visible). A low value means more
10912 visible pattern for less banding, and higher value means less visible pattern
10913 at the cost of more banding.
10915 The option must be an integer value in the range [0,5]. Default is @var{2}.
10918 If set, define the zone to process
10922 Only the changing rectangle will be reprocessed. This is similar to GIF
10923 cropping/offsetting compression mechanism. This option can be useful for speed
10924 if only a part of the image is changing, and has use cases such as limiting the
10925 scope of the error diffusal @option{dither} to the rectangle that bounds the
10926 moving scene (it leads to more deterministic output if the scene doesn't change
10927 much, and as a result less moving noise and better GIF compression).
10930 Default is @var{none}.
10933 Take new palette for each output frame.
10936 @subsection Examples
10940 Use a palette (generated for example with @ref{palettegen}) to encode a GIF
10941 using @command{ffmpeg}:
10943 ffmpeg -i input.mkv -i palette.png -lavfi paletteuse output.gif
10947 @section perspective
10949 Correct perspective of video not recorded perpendicular to the screen.
10951 A description of the accepted parameters follows.
10962 Set coordinates expression for top left, top right, bottom left and bottom right corners.
10963 Default values are @code{0:0:W:0:0:H:W:H} with which perspective will remain unchanged.
10964 If the @code{sense} option is set to @code{source}, then the specified points will be sent
10965 to the corners of the destination. If the @code{sense} option is set to @code{destination},
10966 then the corners of the source will be sent to the specified coordinates.
10968 The expressions can use the following variables:
10973 the width and height of video frame.
10977 Output frame count.
10980 @item interpolation
10981 Set interpolation for perspective correction.
10983 It accepts the following values:
10989 Default value is @samp{linear}.
10992 Set interpretation of coordinate options.
10994 It accepts the following values:
10998 Send point in the source specified by the given coordinates to
10999 the corners of the destination.
11001 @item 1, destination
11003 Send the corners of the source to the point in the destination specified
11004 by the given coordinates.
11006 Default value is @samp{source}.
11010 Set when the expressions for coordinates @option{x0,y0,...x3,y3} are evaluated.
11012 It accepts the following values:
11015 only evaluate expressions once during the filter initialization or
11016 when a command is processed
11019 evaluate expressions for each incoming frame
11022 Default value is @samp{init}.
11027 Delay interlaced video by one field time so that the field order changes.
11029 The intended use is to fix PAL movies that have been captured with the
11030 opposite field order to the film-to-video transfer.
11032 A description of the accepted parameters follows.
11038 It accepts the following values:
11041 Capture field order top-first, transfer bottom-first.
11042 Filter will delay the bottom field.
11045 Capture field order bottom-first, transfer top-first.
11046 Filter will delay the top field.
11049 Capture and transfer with the same field order. This mode only exists
11050 for the documentation of the other options to refer to, but if you
11051 actually select it, the filter will faithfully do nothing.
11054 Capture field order determined automatically by field flags, transfer
11056 Filter selects among @samp{t} and @samp{b} modes on a frame by frame
11057 basis using field flags. If no field information is available,
11058 then this works just like @samp{u}.
11061 Capture unknown or varying, transfer opposite.
11062 Filter selects among @samp{t} and @samp{b} on a frame by frame basis by
11063 analyzing the images and selecting the alternative that produces best
11064 match between the fields.
11067 Capture top-first, transfer unknown or varying.
11068 Filter selects among @samp{t} and @samp{p} using image analysis.
11071 Capture bottom-first, transfer unknown or varying.
11072 Filter selects among @samp{b} and @samp{p} using image analysis.
11075 Capture determined by field flags, transfer unknown or varying.
11076 Filter selects among @samp{t}, @samp{b} and @samp{p} using field flags and
11077 image analysis. If no field information is available, then this works just
11078 like @samp{U}. This is the default mode.
11081 Both capture and transfer unknown or varying.
11082 Filter selects among @samp{t}, @samp{b} and @samp{p} using image analysis only.
11086 @section pixdesctest
11088 Pixel format descriptor test filter, mainly useful for internal
11089 testing. The output video should be equal to the input video.
11093 format=monow, pixdesctest
11096 can be used to test the monowhite pixel format descriptor definition.
11100 Display sample values of color channels. Mainly useful for checking color and levels.
11102 The filters accept the following options:
11106 Set scope X position, offset on X axis.
11109 Set scope Y position, offset on Y axis.
11118 Set window opacity. This window also holds statistics about pixel area.
11123 Enable the specified chain of postprocessing subfilters using libpostproc. This
11124 library should be automatically selected with a GPL build (@code{--enable-gpl}).
11125 Subfilters must be separated by '/' and can be disabled by prepending a '-'.
11126 Each subfilter and some options have a short and a long name that can be used
11127 interchangeably, i.e. dr/dering are the same.
11129 The filters accept the following options:
11133 Set postprocessing subfilters string.
11136 All subfilters share common options to determine their scope:
11140 Honor the quality commands for this subfilter.
11143 Do chrominance filtering, too (default).
11146 Do luminance filtering only (no chrominance).
11149 Do chrominance filtering only (no luminance).
11152 These options can be appended after the subfilter name, separated by a '|'.
11154 Available subfilters are:
11157 @item hb/hdeblock[|difference[|flatness]]
11158 Horizontal deblocking filter
11161 Difference factor where higher values mean more deblocking (default: @code{32}).
11163 Flatness threshold where lower values mean more deblocking (default: @code{39}).
11166 @item vb/vdeblock[|difference[|flatness]]
11167 Vertical deblocking filter
11170 Difference factor where higher values mean more deblocking (default: @code{32}).
11172 Flatness threshold where lower values mean more deblocking (default: @code{39}).
11175 @item ha/hadeblock[|difference[|flatness]]
11176 Accurate horizontal deblocking filter
11179 Difference factor where higher values mean more deblocking (default: @code{32}).
11181 Flatness threshold where lower values mean more deblocking (default: @code{39}).
11184 @item va/vadeblock[|difference[|flatness]]
11185 Accurate vertical deblocking filter
11188 Difference factor where higher values mean more deblocking (default: @code{32}).
11190 Flatness threshold where lower values mean more deblocking (default: @code{39}).
11194 The horizontal and vertical deblocking filters share the difference and
11195 flatness values so you cannot set different horizontal and vertical
11199 @item h1/x1hdeblock
11200 Experimental horizontal deblocking filter
11202 @item v1/x1vdeblock
11203 Experimental vertical deblocking filter
11208 @item tn/tmpnoise[|threshold1[|threshold2[|threshold3]]], temporal noise reducer
11211 larger -> stronger filtering
11213 larger -> stronger filtering
11215 larger -> stronger filtering
11218 @item al/autolevels[:f/fullyrange], automatic brightness / contrast correction
11221 Stretch luminance to @code{0-255}.
11224 @item lb/linblenddeint
11225 Linear blend deinterlacing filter that deinterlaces the given block by
11226 filtering all lines with a @code{(1 2 1)} filter.
11228 @item li/linipoldeint
11229 Linear interpolating deinterlacing filter that deinterlaces the given block by
11230 linearly interpolating every second line.
11232 @item ci/cubicipoldeint
11233 Cubic interpolating deinterlacing filter deinterlaces the given block by
11234 cubically interpolating every second line.
11236 @item md/mediandeint
11237 Median deinterlacing filter that deinterlaces the given block by applying a
11238 median filter to every second line.
11240 @item fd/ffmpegdeint
11241 FFmpeg deinterlacing filter that deinterlaces the given block by filtering every
11242 second line with a @code{(-1 4 2 4 -1)} filter.
11245 Vertically applied FIR lowpass deinterlacing filter that deinterlaces the given
11246 block by filtering all lines with a @code{(-1 2 6 2 -1)} filter.
11248 @item fq/forceQuant[|quantizer]
11249 Overrides the quantizer table from the input with the constant quantizer you
11257 Default pp filter combination (@code{hb|a,vb|a,dr|a})
11260 Fast pp filter combination (@code{h1|a,v1|a,dr|a})
11263 High quality pp filter combination (@code{ha|a|128|7,va|a,dr|a})
11266 @subsection Examples
11270 Apply horizontal and vertical deblocking, deringing and automatic
11271 brightness/contrast:
11277 Apply default filters without brightness/contrast correction:
11283 Apply default filters and temporal denoiser:
11285 pp=default/tmpnoise|1|2|3
11289 Apply deblocking on luminance only, and switch vertical deblocking on or off
11290 automatically depending on available CPU time:
11297 Apply Postprocessing filter 7. It is variant of the @ref{spp} filter,
11298 similar to spp = 6 with 7 point DCT, where only the center sample is
11301 The filter accepts the following options:
11305 Force a constant quantization parameter. It accepts an integer in range
11306 0 to 63. If not set, the filter will use the QP from the video stream
11310 Set thresholding mode. Available modes are:
11314 Set hard thresholding.
11316 Set soft thresholding (better de-ringing effect, but likely blurrier).
11318 Set medium thresholding (good results, default).
11322 @section premultiply
11323 Apply alpha premultiply effect to input video stream using first plane
11324 of second stream as alpha.
11326 Both streams must have same dimensions and same pixel format.
11328 The filter accepts the following option:
11332 Set which planes will be processed, unprocessed planes will be copied.
11333 By default value 0xf, all planes will be processed.
11337 Apply prewitt operator to input video stream.
11339 The filter accepts the following option:
11343 Set which planes will be processed, unprocessed planes will be copied.
11344 By default value 0xf, all planes will be processed.
11347 Set value which will be multiplied with filtered result.
11350 Set value which will be added to filtered result.
11355 Obtain the average, maximum and minimum PSNR (Peak Signal to Noise
11356 Ratio) between two input videos.
11358 This filter takes in input two input videos, the first input is
11359 considered the "main" source and is passed unchanged to the
11360 output. The second input is used as a "reference" video for computing
11363 Both video inputs must have the same resolution and pixel format for
11364 this filter to work correctly. Also it assumes that both inputs
11365 have the same number of frames, which are compared one by one.
11367 The obtained average PSNR is printed through the logging system.
11369 The filter stores the accumulated MSE (mean squared error) of each
11370 frame, and at the end of the processing it is averaged across all frames
11371 equally, and the following formula is applied to obtain the PSNR:
11374 PSNR = 10*log10(MAX^2/MSE)
11377 Where MAX is the average of the maximum values of each component of the
11380 The description of the accepted parameters follows.
11383 @item stats_file, f
11384 If specified the filter will use the named file to save the PSNR of
11385 each individual frame. When filename equals "-" the data is sent to
11388 @item stats_version
11389 Specifies which version of the stats file format to use. Details of
11390 each format are written below.
11391 Default value is 1.
11393 @item stats_add_max
11394 Determines whether the max value is output to the stats log.
11395 Default value is 0.
11396 Requires stats_version >= 2. If this is set and stats_version < 2,
11397 the filter will return an error.
11400 The file printed if @var{stats_file} is selected, contains a sequence of
11401 key/value pairs of the form @var{key}:@var{value} for each compared
11404 If a @var{stats_version} greater than 1 is specified, a header line precedes
11405 the list of per-frame-pair stats, with key value pairs following the frame
11406 format with the following parameters:
11409 @item psnr_log_version
11410 The version of the log file format. Will match @var{stats_version}.
11413 A comma separated list of the per-frame-pair parameters included in
11417 A description of each shown per-frame-pair parameter follows:
11421 sequential number of the input frame, starting from 1
11424 Mean Square Error pixel-by-pixel average difference of the compared
11425 frames, averaged over all the image components.
11427 @item mse_y, mse_u, mse_v, mse_r, mse_g, mse_g, mse_a
11428 Mean Square Error pixel-by-pixel average difference of the compared
11429 frames for the component specified by the suffix.
11431 @item psnr_y, psnr_u, psnr_v, psnr_r, psnr_g, psnr_b, psnr_a
11432 Peak Signal to Noise ratio of the compared frames for the component
11433 specified by the suffix.
11435 @item max_avg, max_y, max_u, max_v
11436 Maximum allowed value for each channel, and average over all
11442 movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
11443 [main][ref] psnr="stats_file=stats.log" [out]
11446 On this example the input file being processed is compared with the
11447 reference file @file{ref_movie.mpg}. The PSNR of each individual frame
11448 is stored in @file{stats.log}.
11453 Pulldown reversal (inverse telecine) filter, capable of handling mixed
11454 hard-telecine, 24000/1001 fps progressive, and 30000/1001 fps progressive
11457 The pullup filter is designed to take advantage of future context in making
11458 its decisions. This filter is stateless in the sense that it does not lock
11459 onto a pattern to follow, but it instead looks forward to the following
11460 fields in order to identify matches and rebuild progressive frames.
11462 To produce content with an even framerate, insert the fps filter after
11463 pullup, use @code{fps=24000/1001} if the input frame rate is 29.97fps,
11464 @code{fps=24} for 30fps and the (rare) telecined 25fps input.
11466 The filter accepts the following options:
11473 These options set the amount of "junk" to ignore at the left, right, top, and
11474 bottom of the image, respectively. Left and right are in units of 8 pixels,
11475 while top and bottom are in units of 2 lines.
11476 The default is 8 pixels on each side.
11479 Set the strict breaks. Setting this option to 1 will reduce the chances of
11480 filter generating an occasional mismatched frame, but it may also cause an
11481 excessive number of frames to be dropped during high motion sequences.
11482 Conversely, setting it to -1 will make filter match fields more easily.
11483 This may help processing of video where there is slight blurring between
11484 the fields, but may also cause there to be interlaced frames in the output.
11485 Default value is @code{0}.
11488 Set the metric plane to use. It accepts the following values:
11494 Use chroma blue plane.
11497 Use chroma red plane.
11500 This option may be set to use chroma plane instead of the default luma plane
11501 for doing filter's computations. This may improve accuracy on very clean
11502 source material, but more likely will decrease accuracy, especially if there
11503 is chroma noise (rainbow effect) or any grayscale video.
11504 The main purpose of setting @option{mp} to a chroma plane is to reduce CPU
11505 load and make pullup usable in realtime on slow machines.
11508 For best results (without duplicated frames in the output file) it is
11509 necessary to change the output frame rate. For example, to inverse
11510 telecine NTSC input:
11512 ffmpeg -i input -vf pullup -r 24000/1001 ...
11517 Change video quantization parameters (QP).
11519 The filter accepts the following option:
11523 Set expression for quantization parameter.
11526 The expression is evaluated through the eval API and can contain, among others,
11527 the following constants:
11531 1 if index is not 129, 0 otherwise.
11534 Sequentional index starting from -129 to 128.
11537 @subsection Examples
11541 Some equation like:
11549 Flush video frames from internal cache of frames into a random order.
11550 No frame is discarded.
11551 Inspired by @ref{frei0r} nervous filter.
11555 Set size in number of frames of internal cache, in range from @code{2} to
11556 @code{512}. Default is @code{30}.
11559 Set seed for random number generator, must be an integer included between
11560 @code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to
11561 less than @code{0}, the filter will try to use a good random seed on a
11565 @section readeia608
11567 Read closed captioning (EIA-608) information from the top lines of a video frame.
11569 This filter adds frame metadata for @code{lavfi.readeia608.X.cc} and
11570 @code{lavfi.readeia608.X.line}, where @code{X} is the number of the identified line
11571 with EIA-608 data (starting from 0). A description of each metadata value follows:
11574 @item lavfi.readeia608.X.cc
11575 The two bytes stored as EIA-608 data (printed in hexadecimal).
11577 @item lavfi.readeia608.X.line
11578 The number of the line on which the EIA-608 data was identified and read.
11581 This filter accepts the following options:
11585 Set the line to start scanning for EIA-608 data. Default is @code{0}.
11588 Set the line to end scanning for EIA-608 data. Default is @code{29}.
11591 Set minimal acceptable amplitude change for sync codes detection.
11592 Default is @code{0.2}. Allowed range is @code{[0.001 - 1]}.
11595 Set the ratio of width reserved for sync code detection.
11596 Default is @code{0.27}. Allowed range is @code{[0.01 - 0.7]}.
11599 Set the max peaks height difference for sync code detection.
11600 Default is @code{0.1}. Allowed range is @code{[0.0 - 0.5]}.
11603 Set max peaks period difference for sync code detection.
11604 Default is @code{0.1}. Allowed range is @code{[0.0 - 0.5]}.
11607 Set the first two max start code bits differences.
11608 Default is @code{0.02}. Allowed range is @code{[0.0 - 0.5]}.
11611 Set the minimum ratio of bits height compared to 3rd start code bit.
11612 Default is @code{0.75}. Allowed range is @code{[0.01 - 1]}.
11615 Set the white color threshold. Default is @code{0.35}. Allowed range is @code{[0.1 - 1]}.
11618 Set the black color threshold. Default is @code{0.15}. Allowed range is @code{[0.0 - 0.5]}.
11621 Enable checking the parity bit. In the event of a parity error, the filter will output
11622 @code{0x00} for that character. Default is false.
11625 @subsection Examples
11629 Output a csv with presentation time and the first two lines of identified EIA-608 captioning data.
11631 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
11637 Read vertical interval timecode (VITC) information from the top lines of a
11640 The filter adds frame metadata key @code{lavfi.readvitc.tc_str} with the
11641 timecode value, if a valid timecode has been detected. Further metadata key
11642 @code{lavfi.readvitc.found} is set to 0/1 depending on whether
11643 timecode data has been found or not.
11645 This filter accepts the following options:
11649 Set the maximum number of lines to scan for VITC data. If the value is set to
11650 @code{-1} the full video frame is scanned. Default is @code{45}.
11653 Set the luma threshold for black. Accepts float numbers in the range [0.0,1.0],
11654 default value is @code{0.2}. The value must be equal or less than @code{thr_w}.
11657 Set the luma threshold for white. Accepts float numbers in the range [0.0,1.0],
11658 default value is @code{0.6}. The value must be equal or greater than @code{thr_b}.
11661 @subsection Examples
11665 Detect and draw VITC data onto the video frame; if no valid VITC is detected,
11666 draw @code{--:--:--:--} as a placeholder:
11668 ffmpeg -i input.avi -filter:v 'readvitc,drawtext=fontfile=FreeMono.ttf:text=%@{metadata\\:lavfi.readvitc.tc_str\\:--\\\\\\:--\\\\\\:--\\\\\\:--@}:x=(w-tw)/2:y=400-ascent'
11674 Remap pixels using 2nd: Xmap and 3rd: Ymap input video stream.
11676 Destination pixel at position (X, Y) will be picked from source (x, y) position
11677 where x = Xmap(X, Y) and y = Ymap(X, Y). If mapping values are out of range, zero
11678 value for pixel will be used for destination pixel.
11680 Xmap and Ymap input video streams must be of same dimensions. Output video stream
11681 will have Xmap/Ymap video stream dimensions.
11682 Xmap and Ymap input video streams are 16bit depth, single channel.
11684 @section removegrain
11686 The removegrain filter is a spatial denoiser for progressive video.
11690 Set mode for the first plane.
11693 Set mode for the second plane.
11696 Set mode for the third plane.
11699 Set mode for the fourth plane.
11702 Range of mode is from 0 to 24. Description of each mode follows:
11706 Leave input plane unchanged. Default.
11709 Clips the pixel with the minimum and maximum of the 8 neighbour pixels.
11712 Clips the pixel with the second minimum and maximum of the 8 neighbour pixels.
11715 Clips the pixel with the third minimum and maximum of the 8 neighbour pixels.
11718 Clips the pixel with the fourth minimum and maximum of the 8 neighbour pixels.
11719 This is equivalent to a median filter.
11722 Line-sensitive clipping giving the minimal change.
11725 Line-sensitive clipping, intermediate.
11728 Line-sensitive clipping, intermediate.
11731 Line-sensitive clipping, intermediate.
11734 Line-sensitive clipping on a line where the neighbours pixels are the closest.
11737 Replaces the target pixel with the closest neighbour.
11740 [1 2 1] horizontal and vertical kernel blur.
11746 Bob mode, interpolates top field from the line where the neighbours
11747 pixels are the closest.
11750 Bob mode, interpolates bottom field from the line where the neighbours
11751 pixels are the closest.
11754 Bob mode, interpolates top field. Same as 13 but with a more complicated
11755 interpolation formula.
11758 Bob mode, interpolates bottom field. Same as 14 but with a more complicated
11759 interpolation formula.
11762 Clips the pixel with the minimum and maximum of respectively the maximum and
11763 minimum of each pair of opposite neighbour pixels.
11766 Line-sensitive clipping using opposite neighbours whose greatest distance from
11767 the current pixel is minimal.
11770 Replaces the pixel with the average of its 8 neighbours.
11773 Averages the 9 pixels ([1 1 1] horizontal and vertical blur).
11776 Clips pixels using the averages of opposite neighbour.
11779 Same as mode 21 but simpler and faster.
11782 Small edge and halo removal, but reputed useless.
11788 @section removelogo
11790 Suppress a TV station logo, using an image file to determine which
11791 pixels comprise the logo. It works by filling in the pixels that
11792 comprise the logo with neighboring pixels.
11794 The filter accepts the following options:
11798 Set the filter bitmap file, which can be any image format supported by
11799 libavformat. The width and height of the image file must match those of the
11800 video stream being processed.
11803 Pixels in the provided bitmap image with a value of zero are not
11804 considered part of the logo, non-zero pixels are considered part of
11805 the logo. If you use white (255) for the logo and black (0) for the
11806 rest, you will be safe. For making the filter bitmap, it is
11807 recommended to take a screen capture of a black frame with the logo
11808 visible, and then using a threshold filter followed by the erode
11809 filter once or twice.
11811 If needed, little splotches can be fixed manually. Remember that if
11812 logo pixels are not covered, the filter quality will be much
11813 reduced. Marking too many pixels as part of the logo does not hurt as
11814 much, but it will increase the amount of blurring needed to cover over
11815 the image and will destroy more information than necessary, and extra
11816 pixels will slow things down on a large logo.
11818 @section repeatfields
11820 This filter uses the repeat_field flag from the Video ES headers and hard repeats
11821 fields based on its value.
11825 Reverse a video clip.
11827 Warning: This filter requires memory to buffer the entire clip, so trimming
11830 @subsection Examples
11834 Take the first 5 seconds of a clip, and reverse it.
11842 Rotate video by an arbitrary angle expressed in radians.
11844 The filter accepts the following options:
11846 A description of the optional parameters follows.
11849 Set an expression for the angle by which to rotate the input video
11850 clockwise, expressed as a number of radians. A negative value will
11851 result in a counter-clockwise rotation. By default it is set to "0".
11853 This expression is evaluated for each frame.
11856 Set the output width expression, default value is "iw".
11857 This expression is evaluated just once during configuration.
11860 Set the output height expression, default value is "ih".
11861 This expression is evaluated just once during configuration.
11864 Enable bilinear interpolation if set to 1, a value of 0 disables
11865 it. Default value is 1.
11868 Set the color used to fill the output area not covered by the rotated
11869 image. For the general syntax of this option, check the "Color" section in the
11870 ffmpeg-utils manual. If the special value "none" is selected then no
11871 background is printed (useful for example if the background is never shown).
11873 Default value is "black".
11876 The expressions for the angle and the output size can contain the
11877 following constants and functions:
11881 sequential number of the input frame, starting from 0. It is always NAN
11882 before the first frame is filtered.
11885 time in seconds of the input frame, it is set to 0 when the filter is
11886 configured. It is always NAN before the first frame is filtered.
11890 horizontal and vertical chroma subsample values. For example for the
11891 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
11895 the input video width and height
11899 the output width and height, that is the size of the padded area as
11900 specified by the @var{width} and @var{height} expressions
11904 the minimal width/height required for completely containing the input
11905 video rotated by @var{a} radians.
11907 These are only available when computing the @option{out_w} and
11908 @option{out_h} expressions.
11911 @subsection Examples
11915 Rotate the input by PI/6 radians clockwise:
11921 Rotate the input by PI/6 radians counter-clockwise:
11927 Rotate the input by 45 degrees clockwise:
11933 Apply a constant rotation with period T, starting from an angle of PI/3:
11935 rotate=PI/3+2*PI*t/T
11939 Make the input video rotation oscillating with a period of T
11940 seconds and an amplitude of A radians:
11942 rotate=A*sin(2*PI/T*t)
11946 Rotate the video, output size is chosen so that the whole rotating
11947 input video is always completely contained in the output:
11949 rotate='2*PI*t:ow=hypot(iw,ih):oh=ow'
11953 Rotate the video, reduce the output size so that no background is ever
11956 rotate=2*PI*t:ow='min(iw,ih)/sqrt(2)':oh=ow:c=none
11960 @subsection Commands
11962 The filter supports the following commands:
11966 Set the angle expression.
11967 The command accepts the same syntax of the corresponding option.
11969 If the specified expression is not valid, it is kept at its current
11975 Apply Shape Adaptive Blur.
11977 The filter accepts the following options:
11980 @item luma_radius, lr
11981 Set luma blur filter strength, must be a value in range 0.1-4.0, default
11982 value is 1.0. A greater value will result in a more blurred image, and
11983 in slower processing.
11985 @item luma_pre_filter_radius, lpfr
11986 Set luma pre-filter radius, must be a value in the 0.1-2.0 range, default
11989 @item luma_strength, ls
11990 Set luma maximum difference between pixels to still be considered, must
11991 be a value in the 0.1-100.0 range, default value is 1.0.
11993 @item chroma_radius, cr
11994 Set chroma blur filter strength, must be a value in range -0.9-4.0. A
11995 greater value will result in a more blurred image, and in slower
11998 @item chroma_pre_filter_radius, cpfr
11999 Set chroma pre-filter radius, must be a value in the -0.9-2.0 range.
12001 @item chroma_strength, cs
12002 Set chroma maximum difference between pixels to still be considered,
12003 must be a value in the -0.9-100.0 range.
12006 Each chroma option value, if not explicitly specified, is set to the
12007 corresponding luma option value.
12012 Scale (resize) the input video, using the libswscale library.
12014 The scale filter forces the output display aspect ratio to be the same
12015 of the input, by changing the output sample aspect ratio.
12017 If the input image format is different from the format requested by
12018 the next filter, the scale filter will convert the input to the
12021 @subsection Options
12022 The filter accepts the following options, or any of the options
12023 supported by the libswscale scaler.
12025 See @ref{scaler_options,,the ffmpeg-scaler manual,ffmpeg-scaler} for
12026 the complete list of scaler options.
12031 Set the output video dimension expression. Default value is the input
12034 If the value is 0, the input width is used for the output.
12036 If one of the values is -1, the scale filter will use a value that
12037 maintains the aspect ratio of the input image, calculated from the
12038 other specified dimension. If both of them are -1, the input size is
12041 If one of the values is -n with n > 1, the scale filter will also use a value
12042 that maintains the aspect ratio of the input image, calculated from the other
12043 specified dimension. After that it will, however, make sure that the calculated
12044 dimension is divisible by n and adjust the value if necessary.
12046 See below for the list of accepted constants for use in the dimension
12050 Specify when to evaluate @var{width} and @var{height} expression. It accepts the following values:
12054 Only evaluate expressions once during the filter initialization or when a command is processed.
12057 Evaluate expressions for each incoming frame.
12061 Default value is @samp{init}.
12065 Set the interlacing mode. It accepts the following values:
12069 Force interlaced aware scaling.
12072 Do not apply interlaced scaling.
12075 Select interlaced aware scaling depending on whether the source frames
12076 are flagged as interlaced or not.
12079 Default value is @samp{0}.
12082 Set libswscale scaling flags. See
12083 @ref{sws_flags,,the ffmpeg-scaler manual,ffmpeg-scaler} for the
12084 complete list of values. If not explicitly specified the filter applies
12088 @item param0, param1
12089 Set libswscale input parameters for scaling algorithms that need them. See
12090 @ref{sws_params,,the ffmpeg-scaler manual,ffmpeg-scaler} for the
12091 complete documentation. If not explicitly specified the filter applies
12097 Set the video size. For the syntax of this option, check the
12098 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
12100 @item in_color_matrix
12101 @item out_color_matrix
12102 Set in/output YCbCr color space type.
12104 This allows the autodetected value to be overridden as well as allows forcing
12105 a specific value used for the output and encoder.
12107 If not specified, the color space type depends on the pixel format.
12113 Choose automatically.
12116 Format conforming to International Telecommunication Union (ITU)
12117 Recommendation BT.709.
12120 Set color space conforming to the United States Federal Communications
12121 Commission (FCC) Code of Federal Regulations (CFR) Title 47 (2003) 73.682 (a).
12124 Set color space conforming to:
12128 ITU Radiocommunication Sector (ITU-R) Recommendation BT.601
12131 ITU-R Rec. BT.470-6 (1998) Systems B, B1, and G
12134 Society of Motion Picture and Television Engineers (SMPTE) ST 170:2004
12139 Set color space conforming to SMPTE ST 240:1999.
12144 Set in/output YCbCr sample range.
12146 This allows the autodetected value to be overridden as well as allows forcing
12147 a specific value used for the output and encoder. If not specified, the
12148 range depends on the pixel format. Possible values:
12152 Choose automatically.
12155 Set full range (0-255 in case of 8-bit luma).
12158 Set "MPEG" range (16-235 in case of 8-bit luma).
12161 @item force_original_aspect_ratio
12162 Enable decreasing or increasing output video width or height if necessary to
12163 keep the original aspect ratio. Possible values:
12167 Scale the video as specified and disable this feature.
12170 The output video dimensions will automatically be decreased if needed.
12173 The output video dimensions will automatically be increased if needed.
12177 One useful instance of this option is that when you know a specific device's
12178 maximum allowed resolution, you can use this to limit the output video to
12179 that, while retaining the aspect ratio. For example, device A allows
12180 1280x720 playback, and your video is 1920x800. Using this option (set it to
12181 decrease) and specifying 1280x720 to the command line makes the output
12184 Please note that this is a different thing than specifying -1 for @option{w}
12185 or @option{h}, you still need to specify the output resolution for this option
12190 The values of the @option{w} and @option{h} options are expressions
12191 containing the following constants:
12196 The input width and height
12200 These are the same as @var{in_w} and @var{in_h}.
12204 The output (scaled) width and height
12208 These are the same as @var{out_w} and @var{out_h}
12211 The same as @var{iw} / @var{ih}
12214 input sample aspect ratio
12217 The input display aspect ratio. Calculated from @code{(iw / ih) * sar}.
12221 horizontal and vertical input chroma subsample values. For example for the
12222 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
12226 horizontal and vertical output chroma subsample values. For example for the
12227 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
12230 @subsection Examples
12234 Scale the input video to a size of 200x100
12239 This is equivalent to:
12250 Specify a size abbreviation for the output size:
12255 which can also be written as:
12261 Scale the input to 2x:
12263 scale=w=2*iw:h=2*ih
12267 The above is the same as:
12269 scale=2*in_w:2*in_h
12273 Scale the input to 2x with forced interlaced scaling:
12275 scale=2*iw:2*ih:interl=1
12279 Scale the input to half size:
12281 scale=w=iw/2:h=ih/2
12285 Increase the width, and set the height to the same size:
12291 Seek Greek harmony:
12298 Increase the height, and set the width to 3/2 of the height:
12300 scale=w=3/2*oh:h=3/5*ih
12304 Increase the size, making the size a multiple of the chroma
12307 scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub"
12311 Increase the width to a maximum of 500 pixels,
12312 keeping the same aspect ratio as the input:
12314 scale=w='min(500\, iw*3/2):h=-1'
12318 @subsection Commands
12320 This filter supports the following commands:
12324 Set the output video dimension expression.
12325 The command accepts the same syntax of the corresponding option.
12327 If the specified expression is not valid, it is kept at its current
12333 Use the NVIDIA Performance Primitives (libnpp) to perform scaling and/or pixel
12334 format conversion on CUDA video frames. Setting the output width and height
12335 works in the same way as for the @var{scale} filter.
12337 The following additional options are accepted:
12340 The pixel format of the output CUDA frames. If set to the string "same" (the
12341 default), the input format will be kept. Note that automatic format negotiation
12342 and conversion is not yet supported for hardware frames
12345 The interpolation algorithm used for resizing. One of the following:
12352 @item cubic2p_bspline
12353 2-parameter cubic (B=1, C=0)
12355 @item cubic2p_catmullrom
12356 2-parameter cubic (B=0, C=1/2)
12358 @item cubic2p_b05c03
12359 2-parameter cubic (B=1/2, C=3/10)
12371 Scale (resize) the input video, based on a reference video.
12373 See the scale filter for available options, scale2ref supports the same but
12374 uses the reference video instead of the main input as basis.
12376 @subsection Examples
12380 Scale a subtitle stream to match the main video in size before overlaying
12382 'scale2ref[b][a];[a][b]overlay'
12386 @anchor{selectivecolor}
12387 @section selectivecolor
12389 Adjust cyan, magenta, yellow and black (CMYK) to certain ranges of colors (such
12390 as "reds", "yellows", "greens", "cyans", ...). The adjustment range is defined
12391 by the "purity" of the color (that is, how saturated it already is).
12393 This filter is similar to the Adobe Photoshop Selective Color tool.
12395 The filter accepts the following options:
12398 @item correction_method
12399 Select color correction method.
12401 Available values are:
12404 Specified adjustments are applied "as-is" (added/subtracted to original pixel
12407 Specified adjustments are relative to the original component value.
12409 Default is @code{absolute}.
12411 Adjustments for red pixels (pixels where the red component is the maximum)
12413 Adjustments for yellow pixels (pixels where the blue component is the minimum)
12415 Adjustments for green pixels (pixels where the green component is the maximum)
12417 Adjustments for cyan pixels (pixels where the red component is the minimum)
12419 Adjustments for blue pixels (pixels where the blue component is the maximum)
12421 Adjustments for magenta pixels (pixels where the green component is the minimum)
12423 Adjustments for white pixels (pixels where all components are greater than 128)
12425 Adjustments for all pixels except pure black and pure white
12427 Adjustments for black pixels (pixels where all components are lesser than 128)
12429 Specify a Photoshop selective color file (@code{.asv}) to import the settings from.
12432 All the adjustment settings (@option{reds}, @option{yellows}, ...) accept up to
12433 4 space separated floating point adjustment values in the [-1,1] range,
12434 respectively to adjust the amount of cyan, magenta, yellow and black for the
12435 pixels of its range.
12437 @subsection Examples
12441 Increase cyan by 50% and reduce yellow by 33% in every green areas, and
12442 increase magenta by 27% in blue areas:
12444 selectivecolor=greens=.5 0 -.33 0:blues=0 .27
12448 Use a Photoshop selective color preset:
12450 selectivecolor=psfile=MySelectiveColorPresets/Misty.asv
12454 @anchor{separatefields}
12455 @section separatefields
12457 The @code{separatefields} takes a frame-based video input and splits
12458 each frame into its components fields, producing a new half height clip
12459 with twice the frame rate and twice the frame count.
12461 This filter use field-dominance information in frame to decide which
12462 of each pair of fields to place first in the output.
12463 If it gets it wrong use @ref{setfield} filter before @code{separatefields} filter.
12465 @section setdar, setsar
12467 The @code{setdar} filter sets the Display Aspect Ratio for the filter
12470 This is done by changing the specified Sample (aka Pixel) Aspect
12471 Ratio, according to the following equation:
12473 @var{DAR} = @var{HORIZONTAL_RESOLUTION} / @var{VERTICAL_RESOLUTION} * @var{SAR}
12476 Keep in mind that the @code{setdar} filter does not modify the pixel
12477 dimensions of the video frame. Also, the display aspect ratio set by
12478 this filter may be changed by later filters in the filterchain,
12479 e.g. in case of scaling or if another "setdar" or a "setsar" filter is
12482 The @code{setsar} filter sets the Sample (aka Pixel) Aspect Ratio for
12483 the filter output video.
12485 Note that as a consequence of the application of this filter, the
12486 output display aspect ratio will change according to the equation
12489 Keep in mind that the sample aspect ratio set by the @code{setsar}
12490 filter may be changed by later filters in the filterchain, e.g. if
12491 another "setsar" or a "setdar" filter is applied.
12493 It accepts the following parameters:
12496 @item r, ratio, dar (@code{setdar} only), sar (@code{setsar} only)
12497 Set the aspect ratio used by the filter.
12499 The parameter can be a floating point number string, an expression, or
12500 a string of the form @var{num}:@var{den}, where @var{num} and
12501 @var{den} are the numerator and denominator of the aspect ratio. If
12502 the parameter is not specified, it is assumed the value "0".
12503 In case the form "@var{num}:@var{den}" is used, the @code{:} character
12507 Set the maximum integer value to use for expressing numerator and
12508 denominator when reducing the expressed aspect ratio to a rational.
12509 Default value is @code{100}.
12513 The parameter @var{sar} is an expression containing
12514 the following constants:
12518 These are approximated values for the mathematical constants e
12519 (Euler's number), pi (Greek pi), and phi (the golden ratio).
12522 The input width and height.
12525 These are the same as @var{w} / @var{h}.
12528 The input sample aspect ratio.
12531 The input display aspect ratio. It is the same as
12532 (@var{w} / @var{h}) * @var{sar}.
12535 Horizontal and vertical chroma subsample values. For example, for the
12536 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
12539 @subsection Examples
12544 To change the display aspect ratio to 16:9, specify one of the following:
12551 To change the sample aspect ratio to 10:11, specify:
12557 To set a display aspect ratio of 16:9, and specify a maximum integer value of
12558 1000 in the aspect ratio reduction, use the command:
12560 setdar=ratio=16/9:max=1000
12568 Force field for the output video frame.
12570 The @code{setfield} filter marks the interlace type field for the
12571 output frames. It does not change the input frame, but only sets the
12572 corresponding property, which affects how the frame is treated by
12573 following filters (e.g. @code{fieldorder} or @code{yadif}).
12575 The filter accepts the following options:
12580 Available values are:
12584 Keep the same field property.
12587 Mark the frame as bottom-field-first.
12590 Mark the frame as top-field-first.
12593 Mark the frame as progressive.
12599 Show a line containing various information for each input video frame.
12600 The input video is not modified.
12602 The shown line contains a sequence of key/value pairs of the form
12603 @var{key}:@var{value}.
12605 The following values are shown in the output:
12609 The (sequential) number of the input frame, starting from 0.
12612 The Presentation TimeStamp of the input frame, expressed as a number of
12613 time base units. The time base unit depends on the filter input pad.
12616 The Presentation TimeStamp of the input frame, expressed as a number of
12620 The position of the frame in the input stream, or -1 if this information is
12621 unavailable and/or meaningless (for example in case of synthetic video).
12624 The pixel format name.
12627 The sample aspect ratio of the input frame, expressed in the form
12628 @var{num}/@var{den}.
12631 The size of the input frame. For the syntax of this option, check the
12632 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
12635 The type of interlaced mode ("P" for "progressive", "T" for top field first, "B"
12636 for bottom field first).
12639 This is 1 if the frame is a key frame, 0 otherwise.
12642 The picture type of the input frame ("I" for an I-frame, "P" for a
12643 P-frame, "B" for a B-frame, or "?" for an unknown type).
12644 Also refer to the documentation of the @code{AVPictureType} enum and of
12645 the @code{av_get_picture_type_char} function defined in
12646 @file{libavutil/avutil.h}.
12649 The Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame.
12651 @item plane_checksum
12652 The Adler-32 checksum (printed in hexadecimal) of each plane of the input frame,
12653 expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3}]".
12656 @section showpalette
12658 Displays the 256 colors palette of each frame. This filter is only relevant for
12659 @var{pal8} pixel format frames.
12661 It accepts the following option:
12665 Set the size of the box used to represent one palette color entry. Default is
12666 @code{30} (for a @code{30x30} pixel box).
12669 @section shuffleframes
12671 Reorder and/or duplicate and/or drop video frames.
12673 It accepts the following parameters:
12677 Set the destination indexes of input frames.
12678 This is space or '|' separated list of indexes that maps input frames to output
12679 frames. Number of indexes also sets maximal value that each index may have.
12680 '-1' index have special meaning and that is to drop frame.
12683 The first frame has the index 0. The default is to keep the input unchanged.
12685 @subsection Examples
12689 Swap second and third frame of every three frames of the input:
12691 ffmpeg -i INPUT -vf "shuffleframes=0 2 1" OUTPUT
12695 Swap 10th and 1st frame of every ten frames of the input:
12697 ffmpeg -i INPUT -vf "shuffleframes=9 1 2 3 4 5 6 7 8 0" OUTPUT
12701 @section shuffleplanes
12703 Reorder and/or duplicate video planes.
12705 It accepts the following parameters:
12710 The index of the input plane to be used as the first output plane.
12713 The index of the input plane to be used as the second output plane.
12716 The index of the input plane to be used as the third output plane.
12719 The index of the input plane to be used as the fourth output plane.
12723 The first plane has the index 0. The default is to keep the input unchanged.
12725 @subsection Examples
12729 Swap the second and third planes of the input:
12731 ffmpeg -i INPUT -vf shuffleplanes=0:2:1:3 OUTPUT
12735 @anchor{signalstats}
12736 @section signalstats
12737 Evaluate various visual metrics that assist in determining issues associated
12738 with the digitization of analog video media.
12740 By default the filter will log these metadata values:
12744 Display the minimal Y value contained within the input frame. Expressed in
12748 Display the Y value at the 10% percentile within the input frame. Expressed in
12752 Display the average Y value within the input frame. Expressed in range of
12756 Display the Y value at the 90% percentile within the input frame. Expressed in
12760 Display the maximum Y value contained within the input frame. Expressed in
12764 Display the minimal U value contained within the input frame. Expressed in
12768 Display the U value at the 10% percentile within the input frame. Expressed in
12772 Display the average U value within the input frame. Expressed in range of
12776 Display the U value at the 90% percentile within the input frame. Expressed in
12780 Display the maximum U value contained within the input frame. Expressed in
12784 Display the minimal V value contained within the input frame. Expressed in
12788 Display the V value at the 10% percentile within the input frame. Expressed in
12792 Display the average V value within the input frame. Expressed in range of
12796 Display the V value at the 90% percentile within the input frame. Expressed in
12800 Display the maximum V value contained within the input frame. Expressed in
12804 Display the minimal saturation value contained within the input frame.
12805 Expressed in range of [0-~181.02].
12808 Display the saturation value at the 10% percentile within the input frame.
12809 Expressed in range of [0-~181.02].
12812 Display the average saturation value within the input frame. Expressed in range
12816 Display the saturation value at the 90% percentile within the input frame.
12817 Expressed in range of [0-~181.02].
12820 Display the maximum saturation value contained within the input frame.
12821 Expressed in range of [0-~181.02].
12824 Display the median value for hue within the input frame. Expressed in range of
12828 Display the average value for hue within the input frame. Expressed in range of
12832 Display the average of sample value difference between all values of the Y
12833 plane in the current frame and corresponding values of the previous input frame.
12834 Expressed in range of [0-255].
12837 Display the average of sample value difference between all values of the U
12838 plane in the current frame and corresponding values of the previous input frame.
12839 Expressed in range of [0-255].
12842 Display the average of sample value difference between all values of the V
12843 plane in the current frame and corresponding values of the previous input frame.
12844 Expressed in range of [0-255].
12847 Display bit depth of Y plane in current frame.
12848 Expressed in range of [0-16].
12851 Display bit depth of U plane in current frame.
12852 Expressed in range of [0-16].
12855 Display bit depth of V plane in current frame.
12856 Expressed in range of [0-16].
12859 The filter accepts the following options:
12865 @option{stat} specify an additional form of image analysis.
12866 @option{out} output video with the specified type of pixel highlighted.
12868 Both options accept the following values:
12872 Identify @var{temporal outliers} pixels. A @var{temporal outlier} is a pixel
12873 unlike the neighboring pixels of the same field. Examples of temporal outliers
12874 include the results of video dropouts, head clogs, or tape tracking issues.
12877 Identify @var{vertical line repetition}. Vertical line repetition includes
12878 similar rows of pixels within a frame. In born-digital video vertical line
12879 repetition is common, but this pattern is uncommon in video digitized from an
12880 analog source. When it occurs in video that results from the digitization of an
12881 analog source it can indicate concealment from a dropout compensator.
12884 Identify pixels that fall outside of legal broadcast range.
12888 Set the highlight color for the @option{out} option. The default color is
12892 @subsection Examples
12896 Output data of various video metrics:
12898 ffprobe -f lavfi movie=example.mov,signalstats="stat=tout+vrep+brng" -show_frames
12902 Output specific data about the minimum and maximum values of the Y plane per frame:
12904 ffprobe -f lavfi movie=example.mov,signalstats -show_entries frame_tags=lavfi.signalstats.YMAX,lavfi.signalstats.YMIN
12908 Playback video while highlighting pixels that are outside of broadcast range in red.
12910 ffplay example.mov -vf signalstats="out=brng:color=red"
12914 Playback video with signalstats metadata drawn over the frame.
12916 ffplay example.mov -vf signalstats=stat=brng+vrep+tout,drawtext=fontfile=FreeSerif.ttf:textfile=signalstat_drawtext.txt
12919 The contents of signalstat_drawtext.txt used in the command are:
12922 Y (%@{metadata:lavfi.signalstats.YMIN@}-%@{metadata:lavfi.signalstats.YMAX@})
12923 U (%@{metadata:lavfi.signalstats.UMIN@}-%@{metadata:lavfi.signalstats.UMAX@})
12924 V (%@{metadata:lavfi.signalstats.VMIN@}-%@{metadata:lavfi.signalstats.VMAX@})
12925 saturation maximum: %@{metadata:lavfi.signalstats.SATMAX@}
12933 Calculates the MPEG-7 Video Signature. The filter can handle more than one
12934 input. In this case the matching between the inputs can be calculated additionally.
12935 The filter always passes through the first input. The signature of each stream can
12936 be written into a file.
12938 It accepts the following options:
12942 Enable or disable the matching process.
12944 Available values are:
12948 Disable the calculation of a matching (default).
12950 Calculate the matching for the whole video and output whether the whole video
12951 matches or only parts.
12953 Calculate only until a matching is found or the video ends. Should be faster in
12958 Set the number of inputs. The option value must be a non negative integer.
12959 Default value is 1.
12962 Set the path to which the output is written. If there is more than one input,
12963 the path must be a prototype, i.e. must contain %d or %0nd (where n is a positive
12964 integer), that will be replaced with the input number. If no filename is
12965 specified, no output will be written. This is the default.
12968 Choose the output format.
12970 Available values are:
12974 Use the specified binary representation (default).
12976 Use the specified xml representation.
12980 Set threshold to detect one word as similar. The option value must be an integer
12981 greater than zero. The default value is 9000.
12984 Set threshold to detect all words as similar. The option value must be an integer
12985 greater than zero. The default value is 60000.
12988 Set threshold to detect frames as similar. The option value must be an integer
12989 greater than zero. The default value is 116.
12992 Set the minimum length of a sequence in frames to recognize it as matching
12993 sequence. The option value must be a non negative integer value.
12994 The default value is 0.
12997 Set the minimum relation, that matching frames to all frames must have.
12998 The option value must be a double value between 0 and 1. The default value is 0.5.
13001 @subsection Examples
13005 To calculate the signature of an input video and store it in signature.bin:
13007 ffmpeg -i input.mkv -vf signature=filename=signature.bin -map 0:v -f null -
13011 To detect whether two videos match and store the signatures in XML format in
13012 signature0.xml and signature1.xml:
13014 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 -
13022 Blur the input video without impacting the outlines.
13024 It accepts the following options:
13027 @item luma_radius, lr
13028 Set the luma radius. The option value must be a float number in
13029 the range [0.1,5.0] that specifies the variance of the gaussian filter
13030 used to blur the image (slower if larger). Default value is 1.0.
13032 @item luma_strength, ls
13033 Set the luma strength. The option value must be a float number
13034 in the range [-1.0,1.0] that configures the blurring. A value included
13035 in [0.0,1.0] will blur the image whereas a value included in
13036 [-1.0,0.0] will sharpen the image. Default value is 1.0.
13038 @item luma_threshold, lt
13039 Set the luma threshold used as a coefficient to determine
13040 whether a pixel should be blurred or not. The option value must be an
13041 integer in the range [-30,30]. A value of 0 will filter all the image,
13042 a value included in [0,30] will filter flat areas and a value included
13043 in [-30,0] will filter edges. Default value is 0.
13045 @item chroma_radius, cr
13046 Set the chroma radius. The option value must be a float number in
13047 the range [0.1,5.0] that specifies the variance of the gaussian filter
13048 used to blur the image (slower if larger). Default value is @option{luma_radius}.
13050 @item chroma_strength, cs
13051 Set the chroma strength. The option value must be a float number
13052 in the range [-1.0,1.0] that configures the blurring. A value included
13053 in [0.0,1.0] will blur the image whereas a value included in
13054 [-1.0,0.0] will sharpen the image. Default value is @option{luma_strength}.
13056 @item chroma_threshold, ct
13057 Set the chroma threshold used as a coefficient to determine
13058 whether a pixel should be blurred or not. The option value must be an
13059 integer in the range [-30,30]. A value of 0 will filter all the image,
13060 a value included in [0,30] will filter flat areas and a value included
13061 in [-30,0] will filter edges. Default value is @option{luma_threshold}.
13064 If a chroma option is not explicitly set, the corresponding luma value
13069 Obtain the SSIM (Structural SImilarity Metric) between two input videos.
13071 This filter takes in input two input videos, the first input is
13072 considered the "main" source and is passed unchanged to the
13073 output. The second input is used as a "reference" video for computing
13076 Both video inputs must have the same resolution and pixel format for
13077 this filter to work correctly. Also it assumes that both inputs
13078 have the same number of frames, which are compared one by one.
13080 The filter stores the calculated SSIM of each frame.
13082 The description of the accepted parameters follows.
13085 @item stats_file, f
13086 If specified the filter will use the named file to save the SSIM of
13087 each individual frame. When filename equals "-" the data is sent to
13091 The file printed if @var{stats_file} is selected, contains a sequence of
13092 key/value pairs of the form @var{key}:@var{value} for each compared
13095 A description of each shown parameter follows:
13099 sequential number of the input frame, starting from 1
13101 @item Y, U, V, R, G, B
13102 SSIM of the compared frames for the component specified by the suffix.
13105 SSIM of the compared frames for the whole frame.
13108 Same as above but in dB representation.
13113 movie=ref_movie.mpg, setpts=PTS-STARTPTS [main];
13114 [main][ref] ssim="stats_file=stats.log" [out]
13117 On this example the input file being processed is compared with the
13118 reference file @file{ref_movie.mpg}. The SSIM of each individual frame
13119 is stored in @file{stats.log}.
13121 Another example with both psnr and ssim at same time:
13123 ffmpeg -i main.mpg -i ref.mpg -lavfi "ssim;[0:v][1:v]psnr" -f null -
13128 Convert between different stereoscopic image formats.
13130 The filters accept the following options:
13134 Set stereoscopic image format of input.
13136 Available values for input image formats are:
13139 side by side parallel (left eye left, right eye right)
13142 side by side crosseye (right eye left, left eye right)
13145 side by side parallel with half width resolution
13146 (left eye left, right eye right)
13149 side by side crosseye with half width resolution
13150 (right eye left, left eye right)
13153 above-below (left eye above, right eye below)
13156 above-below (right eye above, left eye below)
13159 above-below with half height resolution
13160 (left eye above, right eye below)
13163 above-below with half height resolution
13164 (right eye above, left eye below)
13167 alternating frames (left eye first, right eye second)
13170 alternating frames (right eye first, left eye second)
13173 interleaved rows (left eye has top row, right eye starts on next row)
13176 interleaved rows (right eye has top row, left eye starts on next row)
13179 interleaved columns, left eye first
13182 interleaved columns, right eye first
13184 Default value is @samp{sbsl}.
13188 Set stereoscopic image format of output.
13192 side by side parallel (left eye left, right eye right)
13195 side by side crosseye (right eye left, left eye right)
13198 side by side parallel with half width resolution
13199 (left eye left, right eye right)
13202 side by side crosseye with half width resolution
13203 (right eye left, left eye right)
13206 above-below (left eye above, right eye below)
13209 above-below (right eye above, left eye below)
13212 above-below with half height resolution
13213 (left eye above, right eye below)
13216 above-below with half height resolution
13217 (right eye above, left eye below)
13220 alternating frames (left eye first, right eye second)
13223 alternating frames (right eye first, left eye second)
13226 interleaved rows (left eye has top row, right eye starts on next row)
13229 interleaved rows (right eye has top row, left eye starts on next row)
13232 anaglyph red/blue gray
13233 (red filter on left eye, blue filter on right eye)
13236 anaglyph red/green gray
13237 (red filter on left eye, green filter on right eye)
13240 anaglyph red/cyan gray
13241 (red filter on left eye, cyan filter on right eye)
13244 anaglyph red/cyan half colored
13245 (red filter on left eye, cyan filter on right eye)
13248 anaglyph red/cyan color
13249 (red filter on left eye, cyan filter on right eye)
13252 anaglyph red/cyan color optimized with the least squares projection of dubois
13253 (red filter on left eye, cyan filter on right eye)
13256 anaglyph green/magenta gray
13257 (green filter on left eye, magenta filter on right eye)
13260 anaglyph green/magenta half colored
13261 (green filter on left eye, magenta filter on right eye)
13264 anaglyph green/magenta colored
13265 (green filter on left eye, magenta filter on right eye)
13268 anaglyph green/magenta color optimized with the least squares projection of dubois
13269 (green filter on left eye, magenta filter on right eye)
13272 anaglyph yellow/blue gray
13273 (yellow filter on left eye, blue filter on right eye)
13276 anaglyph yellow/blue half colored
13277 (yellow filter on left eye, blue filter on right eye)
13280 anaglyph yellow/blue colored
13281 (yellow filter on left eye, blue filter on right eye)
13284 anaglyph yellow/blue color optimized with the least squares projection of dubois
13285 (yellow filter on left eye, blue filter on right eye)
13288 mono output (left eye only)
13291 mono output (right eye only)
13294 checkerboard, left eye first
13297 checkerboard, right eye first
13300 interleaved columns, left eye first
13303 interleaved columns, right eye first
13309 Default value is @samp{arcd}.
13312 @subsection Examples
13316 Convert input video from side by side parallel to anaglyph yellow/blue dubois:
13322 Convert input video from above below (left eye above, right eye below) to side by side crosseye.
13328 @section streamselect, astreamselect
13329 Select video or audio streams.
13331 The filter accepts the following options:
13335 Set number of inputs. Default is 2.
13338 Set input indexes to remap to outputs.
13341 @subsection Commands
13343 The @code{streamselect} and @code{astreamselect} filter supports the following
13348 Set input indexes to remap to outputs.
13351 @subsection Examples
13355 Select first 5 seconds 1st stream and rest of time 2nd stream:
13357 sendcmd='5.0 streamselect map 1',streamselect=inputs=2:map=0
13361 Same as above, but for audio:
13363 asendcmd='5.0 astreamselect map 1',astreamselect=inputs=2:map=0
13368 Apply sobel operator to input video stream.
13370 The filter accepts the following option:
13374 Set which planes will be processed, unprocessed planes will be copied.
13375 By default value 0xf, all planes will be processed.
13378 Set value which will be multiplied with filtered result.
13381 Set value which will be added to filtered result.
13387 Apply a simple postprocessing filter that compresses and decompresses the image
13388 at several (or - in the case of @option{quality} level @code{6} - all) shifts
13389 and average the results.
13391 The filter accepts the following options:
13395 Set quality. This option defines the number of levels for averaging. It accepts
13396 an integer in the range 0-6. If set to @code{0}, the filter will have no
13397 effect. A value of @code{6} means the higher quality. For each increment of
13398 that value the speed drops by a factor of approximately 2. Default value is
13402 Force a constant quantization parameter. If not set, the filter will use the QP
13403 from the video stream (if available).
13406 Set thresholding mode. Available modes are:
13410 Set hard thresholding (default).
13412 Set soft thresholding (better de-ringing effect, but likely blurrier).
13415 @item use_bframe_qp
13416 Enable the use of the QP from the B-Frames if set to @code{1}. Using this
13417 option may cause flicker since the B-Frames have often larger QP. Default is
13418 @code{0} (not enabled).
13424 Draw subtitles on top of input video using the libass library.
13426 To enable compilation of this filter you need to configure FFmpeg with
13427 @code{--enable-libass}. This filter also requires a build with libavcodec and
13428 libavformat to convert the passed subtitles file to ASS (Advanced Substation
13429 Alpha) subtitles format.
13431 The filter accepts the following options:
13435 Set the filename of the subtitle file to read. It must be specified.
13437 @item original_size
13438 Specify the size of the original video, the video for which the ASS file
13439 was composed. For the syntax of this option, check the
13440 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
13441 Due to a misdesign in ASS aspect ratio arithmetic, this is necessary to
13442 correctly scale the fonts if the aspect ratio has been changed.
13445 Set a directory path containing fonts that can be used by the filter.
13446 These fonts will be used in addition to whatever the font provider uses.
13449 Set subtitles input character encoding. @code{subtitles} filter only. Only
13450 useful if not UTF-8.
13452 @item stream_index, si
13453 Set subtitles stream index. @code{subtitles} filter only.
13456 Override default style or script info parameters of the subtitles. It accepts a
13457 string containing ASS style format @code{KEY=VALUE} couples separated by ",".
13460 If the first key is not specified, it is assumed that the first value
13461 specifies the @option{filename}.
13463 For example, to render the file @file{sub.srt} on top of the input
13464 video, use the command:
13469 which is equivalent to:
13471 subtitles=filename=sub.srt
13474 To render the default subtitles stream from file @file{video.mkv}, use:
13476 subtitles=video.mkv
13479 To render the second subtitles stream from that file, use:
13481 subtitles=video.mkv:si=1
13484 To make the subtitles stream from @file{sub.srt} appear in transparent green
13485 @code{DejaVu Serif}, use:
13487 subtitles=sub.srt:force_style='FontName=DejaVu Serif,PrimaryColour=&HAA00FF00'
13490 @section super2xsai
13492 Scale the input by 2x and smooth using the Super2xSaI (Scale and
13493 Interpolate) pixel art scaling algorithm.
13495 Useful for enlarging pixel art images without reducing sharpness.
13499 Swap two rectangular objects in video.
13501 This filter accepts the following options:
13511 Set 1st rect x coordinate.
13514 Set 1st rect y coordinate.
13517 Set 2nd rect x coordinate.
13520 Set 2nd rect y coordinate.
13522 All expressions are evaluated once for each frame.
13525 The all options are expressions containing the following constants:
13530 The input width and height.
13533 same as @var{w} / @var{h}
13536 input sample aspect ratio
13539 input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
13542 The number of the input frame, starting from 0.
13545 The timestamp expressed in seconds. It's NAN if the input timestamp is unknown.
13548 the position in the file of the input frame, NAN if unknown
13556 Apply telecine process to the video.
13558 This filter accepts the following options:
13567 The default value is @code{top}.
13571 A string of numbers representing the pulldown pattern you wish to apply.
13572 The default value is @code{23}.
13576 Some typical patterns:
13581 24p: 2332 (preferred)
13588 24p: 222222222223 ("Euro pulldown")
13595 Apply threshold effect to video stream.
13597 This filter needs four video streams to perform thresholding.
13598 First stream is stream we are filtering.
13599 Second stream is holding threshold values, third stream is holding min values,
13600 and last, fourth stream is holding max values.
13602 The filter accepts the following option:
13606 Set which planes will be processed, unprocessed planes will be copied.
13607 By default value 0xf, all planes will be processed.
13610 For example if first stream pixel's component value is less then threshold value
13611 of pixel component from 2nd threshold stream, third stream value will picked,
13612 otherwise fourth stream pixel component value will be picked.
13614 Using color source filter one can perform various types of thresholding:
13616 @subsection Examples
13620 Binary threshold, using gray color as threshold:
13622 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=black -f lavfi -i color=white -lavfi threshold output.avi
13626 Inverted binary threshold, using gray color as threshold:
13628 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -f lavfi -i color=black -lavfi threshold output.avi
13632 Truncate binary threshold, using gray color as threshold:
13634 ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=gray -lavfi threshold output.avi
13638 Threshold to zero, using gray color as threshold:
13640 ffmpeg -i 320x240.avi -f lavfi -i color=gray -f lavfi -i color=white -i 320x240.avi -lavfi threshold output.avi
13644 Inverted threshold to zero, using gray color as threshold:
13646 ffmpeg -i 320x240.avi -f lavfi -i color=gray -i 320x240.avi -f lavfi -i color=white -lavfi threshold output.avi
13651 Select the most representative frame in a given sequence of consecutive frames.
13653 The filter accepts the following options:
13657 Set the frames batch size to analyze; in a set of @var{n} frames, the filter
13658 will pick one of them, and then handle the next batch of @var{n} frames until
13659 the end. Default is @code{100}.
13662 Since the filter keeps track of the whole frames sequence, a bigger @var{n}
13663 value will result in a higher memory usage, so a high value is not recommended.
13665 @subsection Examples
13669 Extract one picture each 50 frames:
13675 Complete example of a thumbnail creation with @command{ffmpeg}:
13677 ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png
13683 Tile several successive frames together.
13685 The filter accepts the following options:
13690 Set the grid size (i.e. the number of lines and columns). For the syntax of
13691 this option, check the
13692 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
13695 Set the maximum number of frames to render in the given area. It must be less
13696 than or equal to @var{w}x@var{h}. The default value is @code{0}, meaning all
13697 the area will be used.
13700 Set the outer border margin in pixels.
13703 Set the inner border thickness (i.e. the number of pixels between frames). For
13704 more advanced padding options (such as having different values for the edges),
13705 refer to the pad video filter.
13708 Specify the color of the unused area. For the syntax of this option, check the
13709 "Color" section in the ffmpeg-utils manual. The default value of @var{color}
13713 @subsection Examples
13717 Produce 8x8 PNG tiles of all keyframes (@option{-skip_frame nokey}) in a movie:
13719 ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -vsync 0 keyframes%03d.png
13721 The @option{-vsync 0} is necessary to prevent @command{ffmpeg} from
13722 duplicating each output frame to accommodate the originally detected frame
13726 Display @code{5} pictures in an area of @code{3x2} frames,
13727 with @code{7} pixels between them, and @code{2} pixels of initial margin, using
13728 mixed flat and named options:
13730 tile=3x2:nb_frames=5:padding=7:margin=2
13734 @section tinterlace
13736 Perform various types of temporal field interlacing.
13738 Frames are counted starting from 1, so the first input frame is
13741 The filter accepts the following options:
13746 Specify the mode of the interlacing. This option can also be specified
13747 as a value alone. See below for a list of values for this option.
13749 Available values are:
13753 Move odd frames into the upper field, even into the lower field,
13754 generating a double height frame at half frame rate.
13758 Frame 1 Frame 2 Frame 3 Frame 4
13760 11111 22222 33333 44444
13761 11111 22222 33333 44444
13762 11111 22222 33333 44444
13763 11111 22222 33333 44444
13777 Only output odd frames, even frames are dropped, generating a frame with
13778 unchanged height at half frame rate.
13783 Frame 1 Frame 2 Frame 3 Frame 4
13785 11111 22222 33333 44444
13786 11111 22222 33333 44444
13787 11111 22222 33333 44444
13788 11111 22222 33333 44444
13798 Only output even frames, odd frames are dropped, generating a frame with
13799 unchanged height at half frame rate.
13804 Frame 1 Frame 2 Frame 3 Frame 4
13806 11111 22222 33333 44444
13807 11111 22222 33333 44444
13808 11111 22222 33333 44444
13809 11111 22222 33333 44444
13819 Expand each frame to full height, but pad alternate lines with black,
13820 generating a frame with double height at the same input frame rate.
13825 Frame 1 Frame 2 Frame 3 Frame 4
13827 11111 22222 33333 44444
13828 11111 22222 33333 44444
13829 11111 22222 33333 44444
13830 11111 22222 33333 44444
13833 11111 ..... 33333 .....
13834 ..... 22222 ..... 44444
13835 11111 ..... 33333 .....
13836 ..... 22222 ..... 44444
13837 11111 ..... 33333 .....
13838 ..... 22222 ..... 44444
13839 11111 ..... 33333 .....
13840 ..... 22222 ..... 44444
13844 @item interleave_top, 4
13845 Interleave the upper field from odd frames with the lower field from
13846 even frames, generating a frame with unchanged height at half frame rate.
13851 Frame 1 Frame 2 Frame 3 Frame 4
13853 11111<- 22222 33333<- 44444
13854 11111 22222<- 33333 44444<-
13855 11111<- 22222 33333<- 44444
13856 11111 22222<- 33333 44444<-
13866 @item interleave_bottom, 5
13867 Interleave the lower field from odd frames with the upper field from
13868 even frames, generating a frame with unchanged height at half frame rate.
13873 Frame 1 Frame 2 Frame 3 Frame 4
13875 11111 22222<- 33333 44444<-
13876 11111<- 22222 33333<- 44444
13877 11111 22222<- 33333 44444<-
13878 11111<- 22222 33333<- 44444
13888 @item interlacex2, 6
13889 Double frame rate with unchanged height. Frames are inserted each
13890 containing the second temporal field from the previous input frame and
13891 the first temporal field from the next input frame. This mode relies on
13892 the top_field_first flag. Useful for interlaced video displays with no
13893 field synchronisation.
13898 Frame 1 Frame 2 Frame 3 Frame 4
13900 11111 22222 33333 44444
13901 11111 22222 33333 44444
13902 11111 22222 33333 44444
13903 11111 22222 33333 44444
13906 11111 22222 22222 33333 33333 44444 44444
13907 11111 11111 22222 22222 33333 33333 44444
13908 11111 22222 22222 33333 33333 44444 44444
13909 11111 11111 22222 22222 33333 33333 44444
13914 Move odd frames into the upper field, even into the lower field,
13915 generating a double height frame at same frame rate.
13920 Frame 1 Frame 2 Frame 3 Frame 4
13922 11111 22222 33333 44444
13923 11111 22222 33333 44444
13924 11111 22222 33333 44444
13925 11111 22222 33333 44444
13928 11111 33333 33333 55555
13929 22222 22222 44444 44444
13930 11111 33333 33333 55555
13931 22222 22222 44444 44444
13932 11111 33333 33333 55555
13933 22222 22222 44444 44444
13934 11111 33333 33333 55555
13935 22222 22222 44444 44444
13940 Numeric values are deprecated but are accepted for backward
13941 compatibility reasons.
13943 Default mode is @code{merge}.
13946 Specify flags influencing the filter process.
13948 Available value for @var{flags} is:
13951 @item low_pass_filter, vlfp
13952 Enable linear vertical low-pass filtering in the filter.
13953 Vertical low-pass filtering is required when creating an interlaced
13954 destination from a progressive source which contains high-frequency
13955 vertical detail. Filtering will reduce interlace 'twitter' and Moire
13958 @item complex_filter, cvlfp
13959 Enable complex vertical low-pass filtering.
13960 This will slightly less reduce interlace 'twitter' and Moire
13961 patterning but better retain detail and subjective sharpness impression.
13965 Vertical low-pass filtering can only be enabled for @option{mode}
13966 @var{interleave_top} and @var{interleave_bottom}.
13972 Transpose rows with columns in the input video and optionally flip it.
13974 It accepts the following parameters:
13979 Specify the transposition direction.
13981 Can assume the following values:
13983 @item 0, 4, cclock_flip
13984 Rotate by 90 degrees counterclockwise and vertically flip (default), that is:
13992 Rotate by 90 degrees clockwise, that is:
14000 Rotate by 90 degrees counterclockwise, that is:
14007 @item 3, 7, clock_flip
14008 Rotate by 90 degrees clockwise and vertically flip, that is:
14016 For values between 4-7, the transposition is only done if the input
14017 video geometry is portrait and not landscape. These values are
14018 deprecated, the @code{passthrough} option should be used instead.
14020 Numerical values are deprecated, and should be dropped in favor of
14021 symbolic constants.
14024 Do not apply the transposition if the input geometry matches the one
14025 specified by the specified value. It accepts the following values:
14028 Always apply transposition.
14030 Preserve portrait geometry (when @var{height} >= @var{width}).
14032 Preserve landscape geometry (when @var{width} >= @var{height}).
14035 Default value is @code{none}.
14038 For example to rotate by 90 degrees clockwise and preserve portrait
14041 transpose=dir=1:passthrough=portrait
14044 The command above can also be specified as:
14046 transpose=1:portrait
14050 Trim the input so that the output contains one continuous subpart of the input.
14052 It accepts the following parameters:
14055 Specify the time of the start of the kept section, i.e. the frame with the
14056 timestamp @var{start} will be the first frame in the output.
14059 Specify the time of the first frame that will be dropped, i.e. the frame
14060 immediately preceding the one with the timestamp @var{end} will be the last
14061 frame in the output.
14064 This is the same as @var{start}, except this option sets the start timestamp
14065 in timebase units instead of seconds.
14068 This is the same as @var{end}, except this option sets the end timestamp
14069 in timebase units instead of seconds.
14072 The maximum duration of the output in seconds.
14075 The number of the first frame that should be passed to the output.
14078 The number of the first frame that should be dropped.
14081 @option{start}, @option{end}, and @option{duration} are expressed as time
14082 duration specifications; see
14083 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
14084 for the accepted syntax.
14086 Note that the first two sets of the start/end options and the @option{duration}
14087 option look at the frame timestamp, while the _frame variants simply count the
14088 frames that pass through the filter. Also note that this filter does not modify
14089 the timestamps. If you wish for the output timestamps to start at zero, insert a
14090 setpts filter after the trim filter.
14092 If multiple start or end options are set, this filter tries to be greedy and
14093 keep all the frames that match at least one of the specified constraints. To keep
14094 only the part that matches all the constraints at once, chain multiple trim
14097 The defaults are such that all the input is kept. So it is possible to set e.g.
14098 just the end values to keep everything before the specified time.
14103 Drop everything except the second minute of input:
14105 ffmpeg -i INPUT -vf trim=60:120
14109 Keep only the first second:
14111 ffmpeg -i INPUT -vf trim=duration=1
14120 Sharpen or blur the input video.
14122 It accepts the following parameters:
14125 @item luma_msize_x, lx
14126 Set the luma matrix horizontal size. It must be an odd integer between
14127 3 and 23. The default value is 5.
14129 @item luma_msize_y, ly
14130 Set the luma matrix vertical size. It must be an odd integer between 3
14131 and 23. The default value is 5.
14133 @item luma_amount, la
14134 Set the luma effect strength. It must be a floating point number, reasonable
14135 values lay between -1.5 and 1.5.
14137 Negative values will blur the input video, while positive values will
14138 sharpen it, a value of zero will disable the effect.
14140 Default value is 1.0.
14142 @item chroma_msize_x, cx
14143 Set the chroma matrix horizontal size. It must be an odd integer
14144 between 3 and 23. The default value is 5.
14146 @item chroma_msize_y, cy
14147 Set the chroma matrix vertical size. It must be an odd integer
14148 between 3 and 23. The default value is 5.
14150 @item chroma_amount, ca
14151 Set the chroma effect strength. It must be a floating point number, reasonable
14152 values lay between -1.5 and 1.5.
14154 Negative values will blur the input video, while positive values will
14155 sharpen it, a value of zero will disable the effect.
14157 Default value is 0.0.
14160 If set to 1, specify using OpenCL capabilities, only available if
14161 FFmpeg was configured with @code{--enable-opencl}. Default value is 0.
14165 All parameters are optional and default to the equivalent of the
14166 string '5:5:1.0:5:5:0.0'.
14168 @subsection Examples
14172 Apply strong luma sharpen effect:
14174 unsharp=luma_msize_x=7:luma_msize_y=7:luma_amount=2.5
14178 Apply a strong blur of both luma and chroma parameters:
14180 unsharp=7:7:-2:7:7:-2
14186 Apply ultra slow/simple postprocessing filter that compresses and decompresses
14187 the image at several (or - in the case of @option{quality} level @code{8} - all)
14188 shifts and average the results.
14190 The way this differs from the behavior of spp is that uspp actually encodes &
14191 decodes each case with libavcodec Snow, whereas spp uses a simplified intra only 8x8
14192 DCT similar to MJPEG.
14194 The filter accepts the following options:
14198 Set quality. This option defines the number of levels for averaging. It accepts
14199 an integer in the range 0-8. If set to @code{0}, the filter will have no
14200 effect. A value of @code{8} means the higher quality. For each increment of
14201 that value the speed drops by a factor of approximately 2. Default value is
14205 Force a constant quantization parameter. If not set, the filter will use the QP
14206 from the video stream (if available).
14209 @section vaguedenoiser
14211 Apply a wavelet based denoiser.
14213 It transforms each frame from the video input into the wavelet domain,
14214 using Cohen-Daubechies-Feauveau 9/7. Then it applies some filtering to
14215 the obtained coefficients. It does an inverse wavelet transform after.
14216 Due to wavelet properties, it should give a nice smoothed result, and
14217 reduced noise, without blurring picture features.
14219 This filter accepts the following options:
14223 The filtering strength. The higher, the more filtered the video will be.
14224 Hard thresholding can use a higher threshold than soft thresholding
14225 before the video looks overfiltered.
14228 The filtering method the filter will use.
14230 It accepts the following values:
14233 All values under the threshold will be zeroed.
14236 All values under the threshold will be zeroed. All values above will be
14237 reduced by the threshold.
14240 Scales or nullifies coefficients - intermediary between (more) soft and
14241 (less) hard thresholding.
14245 Number of times, the wavelet will decompose the picture. Picture can't
14246 be decomposed beyond a particular point (typically, 8 for a 640x480
14247 frame - as 2^9 = 512 > 480)
14250 Partial of full denoising (limited coefficients shrinking), from 0 to 100.
14253 A list of the planes to process. By default all planes are processed.
14256 @section vectorscope
14258 Display 2 color component values in the two dimensional graph (which is called
14261 This filter accepts the following options:
14265 Set vectorscope mode.
14267 It accepts the following values:
14270 Gray values are displayed on graph, higher brightness means more pixels have
14271 same component color value on location in graph. This is the default mode.
14274 Gray values are displayed on graph. Surrounding pixels values which are not
14275 present in video frame are drawn in gradient of 2 color components which are
14276 set by option @code{x} and @code{y}. The 3rd color component is static.
14279 Actual color components values present in video frame are displayed on graph.
14282 Similar as color2 but higher frequency of same values @code{x} and @code{y}
14283 on graph increases value of another color component, which is luminance by
14284 default values of @code{x} and @code{y}.
14287 Actual colors present in video frame are displayed on graph. If two different
14288 colors map to same position on graph then color with higher value of component
14289 not present in graph is picked.
14292 Gray values are displayed on graph. Similar to @code{color} but with 3rd color
14293 component picked from radial gradient.
14297 Set which color component will be represented on X-axis. Default is @code{1}.
14300 Set which color component will be represented on Y-axis. Default is @code{2}.
14303 Set intensity, used by modes: gray, color, color3 and color5 for increasing brightness
14304 of color component which represents frequency of (X, Y) location in graph.
14309 No envelope, this is default.
14312 Instant envelope, even darkest single pixel will be clearly highlighted.
14315 Hold maximum and minimum values presented in graph over time. This way you
14316 can still spot out of range values without constantly looking at vectorscope.
14319 Peak and instant envelope combined together.
14323 Set what kind of graticule to draw.
14331 Set graticule opacity.
14334 Set graticule flags.
14338 Draw graticule for white point.
14341 Draw graticule for black point.
14344 Draw color points short names.
14348 Set background opacity.
14350 @item lthreshold, l
14351 Set low threshold for color component not represented on X or Y axis.
14352 Values lower than this value will be ignored. Default is 0.
14353 Note this value is multiplied with actual max possible value one pixel component
14354 can have. So for 8-bit input and low threshold value of 0.1 actual threshold
14357 @item hthreshold, h
14358 Set high threshold for color component not represented on X or Y axis.
14359 Values higher than this value will be ignored. Default is 1.
14360 Note this value is multiplied with actual max possible value one pixel component
14361 can have. So for 8-bit input and high threshold value of 0.9 actual threshold
14362 is 0.9 * 255 = 230.
14364 @item colorspace, c
14365 Set what kind of colorspace to use when drawing graticule.
14374 @anchor{vidstabdetect}
14375 @section vidstabdetect
14377 Analyze video stabilization/deshaking. Perform pass 1 of 2, see
14378 @ref{vidstabtransform} for pass 2.
14380 This filter generates a file with relative translation and rotation
14381 transform information about subsequent frames, which is then used by
14382 the @ref{vidstabtransform} filter.
14384 To enable compilation of this filter you need to configure FFmpeg with
14385 @code{--enable-libvidstab}.
14387 This filter accepts the following options:
14391 Set the path to the file used to write the transforms information.
14392 Default value is @file{transforms.trf}.
14395 Set how shaky the video is and how quick the camera is. It accepts an
14396 integer in the range 1-10, a value of 1 means little shakiness, a
14397 value of 10 means strong shakiness. Default value is 5.
14400 Set the accuracy of the detection process. It must be a value in the
14401 range 1-15. A value of 1 means low accuracy, a value of 15 means high
14402 accuracy. Default value is 15.
14405 Set stepsize of the search process. The region around minimum is
14406 scanned with 1 pixel resolution. Default value is 6.
14409 Set minimum contrast. Below this value a local measurement field is
14410 discarded. Must be a floating point value in the range 0-1. Default
14414 Set reference frame number for tripod mode.
14416 If enabled, the motion of the frames is compared to a reference frame
14417 in the filtered stream, identified by the specified number. The idea
14418 is to compensate all movements in a more-or-less static scene and keep
14419 the camera view absolutely still.
14421 If set to 0, it is disabled. The frames are counted starting from 1.
14424 Show fields and transforms in the resulting frames. It accepts an
14425 integer in the range 0-2. Default value is 0, which disables any
14429 @subsection Examples
14433 Use default values:
14439 Analyze strongly shaky movie and put the results in file
14440 @file{mytransforms.trf}:
14442 vidstabdetect=shakiness=10:accuracy=15:result="mytransforms.trf"
14446 Visualize the result of internal transformations in the resulting
14449 vidstabdetect=show=1
14453 Analyze a video with medium shakiness using @command{ffmpeg}:
14455 ffmpeg -i input -vf vidstabdetect=shakiness=5:show=1 dummy.avi
14459 @anchor{vidstabtransform}
14460 @section vidstabtransform
14462 Video stabilization/deshaking: pass 2 of 2,
14463 see @ref{vidstabdetect} for pass 1.
14465 Read a file with transform information for each frame and
14466 apply/compensate them. Together with the @ref{vidstabdetect}
14467 filter this can be used to deshake videos. See also
14468 @url{http://public.hronopik.de/vid.stab}. It is important to also use
14469 the @ref{unsharp} filter, see below.
14471 To enable compilation of this filter you need to configure FFmpeg with
14472 @code{--enable-libvidstab}.
14474 @subsection Options
14478 Set path to the file used to read the transforms. Default value is
14479 @file{transforms.trf}.
14482 Set the number of frames (value*2 + 1) used for lowpass filtering the
14483 camera movements. Default value is 10.
14485 For example a number of 10 means that 21 frames are used (10 in the
14486 past and 10 in the future) to smoothen the motion in the video. A
14487 larger value leads to a smoother video, but limits the acceleration of
14488 the camera (pan/tilt movements). 0 is a special case where a static
14489 camera is simulated.
14492 Set the camera path optimization algorithm.
14494 Accepted values are:
14497 gaussian kernel low-pass filter on camera motion (default)
14499 averaging on transformations
14503 Set maximal number of pixels to translate frames. Default value is -1,
14507 Set maximal angle in radians (degree*PI/180) to rotate frames. Default
14508 value is -1, meaning no limit.
14511 Specify how to deal with borders that may be visible due to movement
14514 Available values are:
14517 keep image information from previous frame (default)
14519 fill the border black
14523 Invert transforms if set to 1. Default value is 0.
14526 Consider transforms as relative to previous frame if set to 1,
14527 absolute if set to 0. Default value is 0.
14530 Set percentage to zoom. A positive value will result in a zoom-in
14531 effect, a negative value in a zoom-out effect. Default value is 0 (no
14535 Set optimal zooming to avoid borders.
14537 Accepted values are:
14542 optimal static zoom value is determined (only very strong movements
14543 will lead to visible borders) (default)
14545 optimal adaptive zoom value is determined (no borders will be
14546 visible), see @option{zoomspeed}
14549 Note that the value given at zoom is added to the one calculated here.
14552 Set percent to zoom maximally each frame (enabled when
14553 @option{optzoom} is set to 2). Range is from 0 to 5, default value is
14557 Specify type of interpolation.
14559 Available values are:
14564 linear only horizontal
14566 linear in both directions (default)
14568 cubic in both directions (slow)
14572 Enable virtual tripod mode if set to 1, which is equivalent to
14573 @code{relative=0:smoothing=0}. Default value is 0.
14575 Use also @code{tripod} option of @ref{vidstabdetect}.
14578 Increase log verbosity if set to 1. Also the detected global motions
14579 are written to the temporary file @file{global_motions.trf}. Default
14583 @subsection Examples
14587 Use @command{ffmpeg} for a typical stabilization with default values:
14589 ffmpeg -i inp.mpeg -vf vidstabtransform,unsharp=5:5:0.8:3:3:0.4 inp_stabilized.mpeg
14592 Note the use of the @ref{unsharp} filter which is always recommended.
14595 Zoom in a bit more and load transform data from a given file:
14597 vidstabtransform=zoom=5:input="mytransforms.trf"
14601 Smoothen the video even more:
14603 vidstabtransform=smoothing=30
14609 Flip the input video vertically.
14611 For example, to vertically flip a video with @command{ffmpeg}:
14613 ffmpeg -i in.avi -vf "vflip" out.avi
14619 Make or reverse a natural vignetting effect.
14621 The filter accepts the following options:
14625 Set lens angle expression as a number of radians.
14627 The value is clipped in the @code{[0,PI/2]} range.
14629 Default value: @code{"PI/5"}
14633 Set center coordinates expressions. Respectively @code{"w/2"} and @code{"h/2"}
14637 Set forward/backward mode.
14639 Available modes are:
14642 The larger the distance from the central point, the darker the image becomes.
14645 The larger the distance from the central point, the brighter the image becomes.
14646 This can be used to reverse a vignette effect, though there is no automatic
14647 detection to extract the lens @option{angle} and other settings (yet). It can
14648 also be used to create a burning effect.
14651 Default value is @samp{forward}.
14654 Set evaluation mode for the expressions (@option{angle}, @option{x0}, @option{y0}).
14656 It accepts the following values:
14659 Evaluate expressions only once during the filter initialization.
14662 Evaluate expressions for each incoming frame. This is way slower than the
14663 @samp{init} mode since it requires all the scalers to be re-computed, but it
14664 allows advanced dynamic expressions.
14667 Default value is @samp{init}.
14670 Set dithering to reduce the circular banding effects. Default is @code{1}
14674 Set vignette aspect. This setting allows one to adjust the shape of the vignette.
14675 Setting this value to the SAR of the input will make a rectangular vignetting
14676 following the dimensions of the video.
14678 Default is @code{1/1}.
14681 @subsection Expressions
14683 The @option{alpha}, @option{x0} and @option{y0} expressions can contain the
14684 following parameters.
14689 input width and height
14692 the number of input frame, starting from 0
14695 the PTS (Presentation TimeStamp) time of the filtered video frame, expressed in
14696 @var{TB} units, NAN if undefined
14699 frame rate of the input video, NAN if the input frame rate is unknown
14702 the PTS (Presentation TimeStamp) of the filtered video frame,
14703 expressed in seconds, NAN if undefined
14706 time base of the input video
14710 @subsection Examples
14714 Apply simple strong vignetting effect:
14720 Make a flickering vignetting:
14722 vignette='PI/4+random(1)*PI/50':eval=frame
14728 Stack input videos vertically.
14730 All streams must be of same pixel format and of same width.
14732 Note that this filter is faster than using @ref{overlay} and @ref{pad} filter
14733 to create same output.
14735 The filter accept the following option:
14739 Set number of input streams. Default is 2.
14742 If set to 1, force the output to terminate when the shortest input
14743 terminates. Default value is 0.
14748 Deinterlace the input video ("w3fdif" stands for "Weston 3 Field
14749 Deinterlacing Filter").
14751 Based on the process described by Martin Weston for BBC R&D, and
14752 implemented based on the de-interlace algorithm written by Jim
14753 Easterbrook for BBC R&D, the Weston 3 field deinterlacing filter
14754 uses filter coefficients calculated by BBC R&D.
14756 There are two sets of filter coefficients, so called "simple":
14757 and "complex". Which set of filter coefficients is used can
14758 be set by passing an optional parameter:
14762 Set the interlacing filter coefficients. Accepts one of the following values:
14766 Simple filter coefficient set.
14768 More-complex filter coefficient set.
14770 Default value is @samp{complex}.
14773 Specify which frames to deinterlace. Accept one of the following values:
14777 Deinterlace all frames,
14779 Only deinterlace frames marked as interlaced.
14782 Default value is @samp{all}.
14786 Video waveform monitor.
14788 The waveform monitor plots color component intensity. By default luminance
14789 only. Each column of the waveform corresponds to a column of pixels in the
14792 It accepts the following options:
14796 Can be either @code{row}, or @code{column}. Default is @code{column}.
14797 In row mode, the graph on the left side represents color component value 0 and
14798 the right side represents value = 255. In column mode, the top side represents
14799 color component value = 0 and bottom side represents value = 255.
14802 Set intensity. Smaller values are useful to find out how many values of the same
14803 luminance are distributed across input rows/columns.
14804 Default value is @code{0.04}. Allowed range is [0, 1].
14807 Set mirroring mode. @code{0} means unmirrored, @code{1} means mirrored.
14808 In mirrored mode, higher values will be represented on the left
14809 side for @code{row} mode and at the top for @code{column} mode. Default is
14810 @code{1} (mirrored).
14814 It accepts the following values:
14817 Presents information identical to that in the @code{parade}, except
14818 that the graphs representing color components are superimposed directly
14821 This display mode makes it easier to spot relative differences or similarities
14822 in overlapping areas of the color components that are supposed to be identical,
14823 such as neutral whites, grays, or blacks.
14826 Display separate graph for the color components side by side in
14827 @code{row} mode or one below the other in @code{column} mode.
14830 Display separate graph for the color components side by side in
14831 @code{column} mode or one below the other in @code{row} mode.
14833 Using this display mode makes it easy to spot color casts in the highlights
14834 and shadows of an image, by comparing the contours of the top and the bottom
14835 graphs of each waveform. Since whites, grays, and blacks are characterized
14836 by exactly equal amounts of red, green, and blue, neutral areas of the picture
14837 should display three waveforms of roughly equal width/height. If not, the
14838 correction is easy to perform by making level adjustments the three waveforms.
14840 Default is @code{stack}.
14842 @item components, c
14843 Set which color components to display. Default is 1, which means only luminance
14844 or red color component if input is in RGB colorspace. If is set for example to
14845 7 it will display all 3 (if) available color components.
14850 No envelope, this is default.
14853 Instant envelope, minimum and maximum values presented in graph will be easily
14854 visible even with small @code{step} value.
14857 Hold minimum and maximum values presented in graph across time. This way you
14858 can still spot out of range values without constantly looking at waveforms.
14861 Peak and instant envelope combined together.
14867 No filtering, this is default.
14870 Luma and chroma combined together.
14873 Similar as above, but shows difference between blue and red chroma.
14876 Displays only chroma.
14879 Displays actual color value on waveform.
14882 Similar as above, but with luma showing frequency of chroma values.
14886 Set which graticule to display.
14890 Do not display graticule.
14893 Display green graticule showing legal broadcast ranges.
14897 Set graticule opacity.
14900 Set graticule flags.
14904 Draw numbers above lines. By default enabled.
14907 Draw dots instead of lines.
14911 Set scale used for displaying graticule.
14918 Default is digital.
14921 Set background opacity.
14924 @section weave, doubleweave
14926 The @code{weave} takes a field-based video input and join
14927 each two sequential fields into single frame, producing a new double
14928 height clip with half the frame rate and half the frame count.
14930 The @code{doubleweave} works same as @code{weave} but without
14931 halving frame rate and frame count.
14933 It accepts the following option:
14937 Set first field. Available values are:
14941 Set the frame as top-field-first.
14944 Set the frame as bottom-field-first.
14948 @subsection Examples
14952 Interlace video using @ref{select} and @ref{separatefields} filter:
14954 separatefields,select=eq(mod(n,4),0)+eq(mod(n,4),3),weave
14959 Apply the xBR high-quality magnification filter which is designed for pixel
14960 art. It follows a set of edge-detection rules, see
14961 @url{http://www.libretro.com/forums/viewtopic.php?f=6&t=134}.
14963 It accepts the following option:
14967 Set the scaling dimension: @code{2} for @code{2xBR}, @code{3} for
14968 @code{3xBR} and @code{4} for @code{4xBR}.
14969 Default is @code{3}.
14975 Deinterlace the input video ("yadif" means "yet another deinterlacing
14978 It accepts the following parameters:
14984 The interlacing mode to adopt. It accepts one of the following values:
14987 @item 0, send_frame
14988 Output one frame for each frame.
14989 @item 1, send_field
14990 Output one frame for each field.
14991 @item 2, send_frame_nospatial
14992 Like @code{send_frame}, but it skips the spatial interlacing check.
14993 @item 3, send_field_nospatial
14994 Like @code{send_field}, but it skips the spatial interlacing check.
14997 The default value is @code{send_frame}.
15000 The picture field parity assumed for the input interlaced video. It accepts one
15001 of the following values:
15005 Assume the top field is first.
15007 Assume the bottom field is first.
15009 Enable automatic detection of field parity.
15012 The default value is @code{auto}.
15013 If the interlacing is unknown or the decoder does not export this information,
15014 top field first will be assumed.
15017 Specify which frames to deinterlace. Accept one of the following
15022 Deinterlace all frames.
15023 @item 1, interlaced
15024 Only deinterlace frames marked as interlaced.
15027 The default value is @code{all}.
15032 Apply Zoom & Pan effect.
15034 This filter accepts the following options:
15038 Set the zoom expression. Default is 1.
15042 Set the x and y expression. Default is 0.
15045 Set the duration expression in number of frames.
15046 This sets for how many number of frames effect will last for
15047 single input image.
15050 Set the output image size, default is 'hd720'.
15053 Set the output frame rate, default is '25'.
15056 Each expression can contain the following constants:
15075 Output frame count.
15079 Last calculated 'x' and 'y' position from 'x' and 'y' expression
15080 for current input frame.
15084 'x' and 'y' of last output frame of previous input frame or 0 when there was
15085 not yet such frame (first input frame).
15088 Last calculated zoom from 'z' expression for current input frame.
15091 Last calculated zoom of last output frame of previous input frame.
15094 Number of output frames for current input frame. Calculated from 'd' expression
15095 for each input frame.
15098 number of output frames created for previous input frame
15101 Rational number: input width / input height
15104 sample aspect ratio
15107 display aspect ratio
15111 @subsection Examples
15115 Zoom-in up to 1.5 and pan at same time to some spot near center of picture:
15117 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
15121 Zoom-in up to 1.5 and pan always at center of picture:
15123 zoompan=z='min(zoom+0.0015,1.5)':d=700:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
15127 Same as above but without pausing:
15129 zoompan=z='min(max(zoom,pzoom)+0.0015,1.5)':d=1:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)'
15134 Scale (resize) the input video, using the z.lib library:
15135 https://github.com/sekrit-twc/zimg.
15137 The zscale filter forces the output display aspect ratio to be the same
15138 as the input, by changing the output sample aspect ratio.
15140 If the input image format is different from the format requested by
15141 the next filter, the zscale filter will convert the input to the
15144 @subsection Options
15145 The filter accepts the following options.
15150 Set the output video dimension expression. Default value is the input
15153 If the @var{width} or @var{w} is 0, the input width is used for the output.
15154 If the @var{height} or @var{h} is 0, the input height is used for the output.
15156 If one of the values is -1, the zscale filter will use a value that
15157 maintains the aspect ratio of the input image, calculated from the
15158 other specified dimension. If both of them are -1, the input size is
15161 If one of the values is -n with n > 1, the zscale filter will also use a value
15162 that maintains the aspect ratio of the input image, calculated from the other
15163 specified dimension. After that it will, however, make sure that the calculated
15164 dimension is divisible by n and adjust the value if necessary.
15166 See below for the list of accepted constants for use in the dimension
15170 Set the video size. For the syntax of this option, check the
15171 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
15174 Set the dither type.
15176 Possible values are:
15181 @item error_diffusion
15187 Set the resize filter type.
15189 Possible values are:
15199 Default is bilinear.
15202 Set the color range.
15204 Possible values are:
15211 Default is same as input.
15214 Set the color primaries.
15216 Possible values are:
15226 Default is same as input.
15229 Set the transfer characteristics.
15231 Possible values are:
15245 Default is same as input.
15248 Set the colorspace matrix.
15250 Possible value are:
15261 Default is same as input.
15264 Set the input color range.
15266 Possible values are:
15273 Default is same as input.
15275 @item primariesin, pin
15276 Set the input color primaries.
15278 Possible values are:
15288 Default is same as input.
15290 @item transferin, tin
15291 Set the input transfer characteristics.
15293 Possible values are:
15304 Default is same as input.
15306 @item matrixin, min
15307 Set the input colorspace matrix.
15309 Possible value are:
15321 Set the output chroma location.
15323 Possible values are:
15334 @item chromalin, cin
15335 Set the input chroma location.
15337 Possible values are:
15349 Set the nominal peak luminance.
15352 The values of the @option{w} and @option{h} options are expressions
15353 containing the following constants:
15358 The input width and height
15362 These are the same as @var{in_w} and @var{in_h}.
15366 The output (scaled) width and height
15370 These are the same as @var{out_w} and @var{out_h}
15373 The same as @var{iw} / @var{ih}
15376 input sample aspect ratio
15379 The input display aspect ratio. Calculated from @code{(iw / ih) * sar}.
15383 horizontal and vertical input chroma subsample values. For example for the
15384 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
15388 horizontal and vertical output chroma subsample values. For example for the
15389 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
15395 @c man end VIDEO FILTERS
15397 @chapter Video Sources
15398 @c man begin VIDEO SOURCES
15400 Below is a description of the currently available video sources.
15404 Buffer video frames, and make them available to the filter chain.
15406 This source is mainly intended for a programmatic use, in particular
15407 through the interface defined in @file{libavfilter/vsrc_buffer.h}.
15409 It accepts the following parameters:
15414 Specify the size (width and height) of the buffered video frames. For the
15415 syntax of this option, check the
15416 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
15419 The input video width.
15422 The input video height.
15425 A string representing the pixel format of the buffered video frames.
15426 It may be a number corresponding to a pixel format, or a pixel format
15430 Specify the timebase assumed by the timestamps of the buffered frames.
15433 Specify the frame rate expected for the video stream.
15435 @item pixel_aspect, sar
15436 The sample (pixel) aspect ratio of the input video.
15439 Specify the optional parameters to be used for the scale filter which
15440 is automatically inserted when an input change is detected in the
15441 input size or format.
15443 @item hw_frames_ctx
15444 When using a hardware pixel format, this should be a reference to an
15445 AVHWFramesContext describing input frames.
15450 buffer=width=320:height=240:pix_fmt=yuv410p:time_base=1/24:sar=1
15453 will instruct the source to accept video frames with size 320x240 and
15454 with format "yuv410p", assuming 1/24 as the timestamps timebase and
15455 square pixels (1:1 sample aspect ratio).
15456 Since the pixel format with name "yuv410p" corresponds to the number 6
15457 (check the enum AVPixelFormat definition in @file{libavutil/pixfmt.h}),
15458 this example corresponds to:
15460 buffer=size=320x240:pixfmt=6:time_base=1/24:pixel_aspect=1/1
15463 Alternatively, the options can be specified as a flat string, but this
15464 syntax is deprecated:
15466 @var{width}:@var{height}:@var{pix_fmt}:@var{time_base.num}:@var{time_base.den}:@var{pixel_aspect.num}:@var{pixel_aspect.den}[:@var{sws_param}]
15470 Create a pattern generated by an elementary cellular automaton.
15472 The initial state of the cellular automaton can be defined through the
15473 @option{filename} and @option{pattern} options. If such options are
15474 not specified an initial state is created randomly.
15476 At each new frame a new row in the video is filled with the result of
15477 the cellular automaton next generation. The behavior when the whole
15478 frame is filled is defined by the @option{scroll} option.
15480 This source accepts the following options:
15484 Read the initial cellular automaton state, i.e. the starting row, from
15485 the specified file.
15486 In the file, each non-whitespace character is considered an alive
15487 cell, a newline will terminate the row, and further characters in the
15488 file will be ignored.
15491 Read the initial cellular automaton state, i.e. the starting row, from
15492 the specified string.
15494 Each non-whitespace character in the string is considered an alive
15495 cell, a newline will terminate the row, and further characters in the
15496 string will be ignored.
15499 Set the video rate, that is the number of frames generated per second.
15502 @item random_fill_ratio, ratio
15503 Set the random fill ratio for the initial cellular automaton row. It
15504 is a floating point number value ranging from 0 to 1, defaults to
15507 This option is ignored when a file or a pattern is specified.
15509 @item random_seed, seed
15510 Set the seed for filling randomly the initial row, must be an integer
15511 included between 0 and UINT32_MAX. If not specified, or if explicitly
15512 set to -1, the filter will try to use a good random seed on a best
15516 Set the cellular automaton rule, it is a number ranging from 0 to 255.
15517 Default value is 110.
15520 Set the size of the output video. For the syntax of this option, check the
15521 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
15523 If @option{filename} or @option{pattern} is specified, the size is set
15524 by default to the width of the specified initial state row, and the
15525 height is set to @var{width} * PHI.
15527 If @option{size} is set, it must contain the width of the specified
15528 pattern string, and the specified pattern will be centered in the
15531 If a filename or a pattern string is not specified, the size value
15532 defaults to "320x518" (used for a randomly generated initial state).
15535 If set to 1, scroll the output upward when all the rows in the output
15536 have been already filled. If set to 0, the new generated row will be
15537 written over the top row just after the bottom row is filled.
15540 @item start_full, full
15541 If set to 1, completely fill the output with generated rows before
15542 outputting the first frame.
15543 This is the default behavior, for disabling set the value to 0.
15546 If set to 1, stitch the left and right row edges together.
15547 This is the default behavior, for disabling set the value to 0.
15550 @subsection Examples
15554 Read the initial state from @file{pattern}, and specify an output of
15557 cellauto=f=pattern:s=200x400
15561 Generate a random initial row with a width of 200 cells, with a fill
15564 cellauto=ratio=2/3:s=200x200
15568 Create a pattern generated by rule 18 starting by a single alive cell
15569 centered on an initial row with width 100:
15571 cellauto=p=@@:s=100x400:full=0:rule=18
15575 Specify a more elaborated initial pattern:
15577 cellauto=p='@@@@ @@ @@@@':s=100x400:full=0:rule=18
15582 @anchor{coreimagesrc}
15583 @section coreimagesrc
15584 Video source generated on GPU using Apple's CoreImage API on OSX.
15586 This video source is a specialized version of the @ref{coreimage} video filter.
15587 Use a core image generator at the beginning of the applied filterchain to
15588 generate the content.
15590 The coreimagesrc video source accepts the following options:
15592 @item list_generators
15593 List all available generators along with all their respective options as well as
15594 possible minimum and maximum values along with the default values.
15596 list_generators=true
15600 Specify the size of the sourced video. For the syntax of this option, check the
15601 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
15602 The default value is @code{320x240}.
15605 Specify the frame rate of the sourced video, as the number of frames
15606 generated per second. It has to be a string in the format
15607 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
15608 number or a valid video frame rate abbreviation. The default value is
15612 Set the sample aspect ratio of the sourced video.
15615 Set the duration of the sourced video. See
15616 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
15617 for the accepted syntax.
15619 If not specified, or the expressed duration is negative, the video is
15620 supposed to be generated forever.
15623 Additionally, all options of the @ref{coreimage} video filter are accepted.
15624 A complete filterchain can be used for further processing of the
15625 generated input without CPU-HOST transfer. See @ref{coreimage} documentation
15626 and examples for details.
15628 @subsection Examples
15633 Use CIQRCodeGenerator to create a QR code for the FFmpeg homepage,
15634 given as complete and escaped command-line for Apple's standard bash shell:
15636 ffmpeg -f lavfi -i coreimagesrc=s=100x100:filter=CIQRCodeGenerator@@inputMessage=https\\\\\://FFmpeg.org/@@inputCorrectionLevel=H -frames:v 1 QRCode.png
15638 This example is equivalent to the QRCode example of @ref{coreimage} without the
15639 need for a nullsrc video source.
15643 @section mandelbrot
15645 Generate a Mandelbrot set fractal, and progressively zoom towards the
15646 point specified with @var{start_x} and @var{start_y}.
15648 This source accepts the following options:
15653 Set the terminal pts value. Default value is 400.
15656 Set the terminal scale value.
15657 Must be a floating point value. Default value is 0.3.
15660 Set the inner coloring mode, that is the algorithm used to draw the
15661 Mandelbrot fractal internal region.
15663 It shall assume one of the following values:
15668 Show time until convergence.
15670 Set color based on point closest to the origin of the iterations.
15675 Default value is @var{mincol}.
15678 Set the bailout value. Default value is 10.0.
15681 Set the maximum of iterations performed by the rendering
15682 algorithm. Default value is 7189.
15685 Set outer coloring mode.
15686 It shall assume one of following values:
15688 @item iteration_count
15689 Set iteration cound mode.
15690 @item normalized_iteration_count
15691 set normalized iteration count mode.
15693 Default value is @var{normalized_iteration_count}.
15696 Set frame rate, expressed as number of frames per second. Default
15700 Set frame size. For the syntax of this option, check the "Video
15701 size" section in the ffmpeg-utils manual. Default value is "640x480".
15704 Set the initial scale value. Default value is 3.0.
15707 Set the initial x position. Must be a floating point value between
15708 -100 and 100. Default value is -0.743643887037158704752191506114774.
15711 Set the initial y position. Must be a floating point value between
15712 -100 and 100. Default value is -0.131825904205311970493132056385139.
15717 Generate various test patterns, as generated by the MPlayer test filter.
15719 The size of the generated video is fixed, and is 256x256.
15720 This source is useful in particular for testing encoding features.
15722 This source accepts the following options:
15727 Specify the frame rate of the sourced video, as the number of frames
15728 generated per second. It has to be a string in the format
15729 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
15730 number or a valid video frame rate abbreviation. The default value is
15734 Set the duration of the sourced video. See
15735 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
15736 for the accepted syntax.
15738 If not specified, or the expressed duration is negative, the video is
15739 supposed to be generated forever.
15743 Set the number or the name of the test to perform. Supported tests are:
15759 Default value is "all", which will cycle through the list of all tests.
15764 mptestsrc=t=dc_luma
15767 will generate a "dc_luma" test pattern.
15769 @section frei0r_src
15771 Provide a frei0r source.
15773 To enable compilation of this filter you need to install the frei0r
15774 header and configure FFmpeg with @code{--enable-frei0r}.
15776 This source accepts the following parameters:
15781 The size of the video to generate. For the syntax of this option, check the
15782 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
15785 The framerate of the generated video. It may be a string of the form
15786 @var{num}/@var{den} or a frame rate abbreviation.
15789 The name to the frei0r source to load. For more information regarding frei0r and
15790 how to set the parameters, read the @ref{frei0r} section in the video filters
15793 @item filter_params
15794 A '|'-separated list of parameters to pass to the frei0r source.
15798 For example, to generate a frei0r partik0l source with size 200x200
15799 and frame rate 10 which is overlaid on the overlay filter main input:
15801 frei0r_src=size=200x200:framerate=10:filter_name=partik0l:filter_params=1234 [overlay]; [in][overlay] overlay
15806 Generate a life pattern.
15808 This source is based on a generalization of John Conway's life game.
15810 The sourced input represents a life grid, each pixel represents a cell
15811 which can be in one of two possible states, alive or dead. Every cell
15812 interacts with its eight neighbours, which are the cells that are
15813 horizontally, vertically, or diagonally adjacent.
15815 At each interaction the grid evolves according to the adopted rule,
15816 which specifies the number of neighbor alive cells which will make a
15817 cell stay alive or born. The @option{rule} option allows one to specify
15820 This source accepts the following options:
15824 Set the file from which to read the initial grid state. In the file,
15825 each non-whitespace character is considered an alive cell, and newline
15826 is used to delimit the end of each row.
15828 If this option is not specified, the initial grid is generated
15832 Set the video rate, that is the number of frames generated per second.
15835 @item random_fill_ratio, ratio
15836 Set the random fill ratio for the initial random grid. It is a
15837 floating point number value ranging from 0 to 1, defaults to 1/PHI.
15838 It is ignored when a file is specified.
15840 @item random_seed, seed
15841 Set the seed for filling the initial random grid, must be an integer
15842 included between 0 and UINT32_MAX. If not specified, or if explicitly
15843 set to -1, the filter will try to use a good random seed on a best
15849 A rule can be specified with a code of the kind "S@var{NS}/B@var{NB}",
15850 where @var{NS} and @var{NB} are sequences of numbers in the range 0-8,
15851 @var{NS} specifies the number of alive neighbor cells which make a
15852 live cell stay alive, and @var{NB} the number of alive neighbor cells
15853 which make a dead cell to become alive (i.e. to "born").
15854 "s" and "b" can be used in place of "S" and "B", respectively.
15856 Alternatively a rule can be specified by an 18-bits integer. The 9
15857 high order bits are used to encode the next cell state if it is alive
15858 for each number of neighbor alive cells, the low order bits specify
15859 the rule for "borning" new cells. Higher order bits encode for an
15860 higher number of neighbor cells.
15861 For example the number 6153 = @code{(12<<9)+9} specifies a stay alive
15862 rule of 12 and a born rule of 9, which corresponds to "S23/B03".
15864 Default value is "S23/B3", which is the original Conway's game of life
15865 rule, and will keep a cell alive if it has 2 or 3 neighbor alive
15866 cells, and will born a new cell if there are three alive cells around
15870 Set the size of the output video. For the syntax of this option, check the
15871 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
15873 If @option{filename} is specified, the size is set by default to the
15874 same size of the input file. If @option{size} is set, it must contain
15875 the size specified in the input file, and the initial grid defined in
15876 that file is centered in the larger resulting area.
15878 If a filename is not specified, the size value defaults to "320x240"
15879 (used for a randomly generated initial grid).
15882 If set to 1, stitch the left and right grid edges together, and the
15883 top and bottom edges also. Defaults to 1.
15886 Set cell mold speed. If set, a dead cell will go from @option{death_color} to
15887 @option{mold_color} with a step of @option{mold}. @option{mold} can have a
15888 value from 0 to 255.
15891 Set the color of living (or new born) cells.
15894 Set the color of dead cells. If @option{mold} is set, this is the first color
15895 used to represent a dead cell.
15898 Set mold color, for definitely dead and moldy cells.
15900 For the syntax of these 3 color options, check the "Color" section in the
15901 ffmpeg-utils manual.
15904 @subsection Examples
15908 Read a grid from @file{pattern}, and center it on a grid of size
15911 life=f=pattern:s=300x300
15915 Generate a random grid of size 200x200, with a fill ratio of 2/3:
15917 life=ratio=2/3:s=200x200
15921 Specify a custom rule for evolving a randomly generated grid:
15927 Full example with slow death effect (mold) using @command{ffplay}:
15929 ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16
15936 @anchor{haldclutsrc}
15938 @anchor{rgbtestsrc}
15940 @anchor{smptehdbars}
15943 @anchor{yuvtestsrc}
15944 @section allrgb, allyuv, color, haldclutsrc, nullsrc, rgbtestsrc, smptebars, smptehdbars, testsrc, testsrc2, yuvtestsrc
15946 The @code{allrgb} source returns frames of size 4096x4096 of all rgb colors.
15948 The @code{allyuv} source returns frames of size 4096x4096 of all yuv colors.
15950 The @code{color} source provides an uniformly colored input.
15952 The @code{haldclutsrc} source provides an identity Hald CLUT. See also
15953 @ref{haldclut} filter.
15955 The @code{nullsrc} source returns unprocessed video frames. It is
15956 mainly useful to be employed in analysis / debugging tools, or as the
15957 source for filters which ignore the input data.
15959 The @code{rgbtestsrc} source generates an RGB test pattern useful for
15960 detecting RGB vs BGR issues. You should see a red, green and blue
15961 stripe from top to bottom.
15963 The @code{smptebars} source generates a color bars pattern, based on
15964 the SMPTE Engineering Guideline EG 1-1990.
15966 The @code{smptehdbars} source generates a color bars pattern, based on
15967 the SMPTE RP 219-2002.
15969 The @code{testsrc} source generates a test video pattern, showing a
15970 color pattern, a scrolling gradient and a timestamp. This is mainly
15971 intended for testing purposes.
15973 The @code{testsrc2} source is similar to testsrc, but supports more
15974 pixel formats instead of just @code{rgb24}. This allows using it as an
15975 input for other tests without requiring a format conversion.
15977 The @code{yuvtestsrc} source generates an YUV test pattern. You should
15978 see a y, cb and cr stripe from top to bottom.
15980 The sources accept the following parameters:
15985 Specify the color of the source, only available in the @code{color}
15986 source. For the syntax of this option, check the "Color" section in the
15987 ffmpeg-utils manual.
15990 Specify the level of the Hald CLUT, only available in the @code{haldclutsrc}
15991 source. A level of @code{N} generates a picture of @code{N*N*N} by @code{N*N*N}
15992 pixels to be used as identity matrix for 3D lookup tables. Each component is
15993 coded on a @code{1/(N*N)} scale.
15996 Specify the size of the sourced video. For the syntax of this option, check the
15997 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
15998 The default value is @code{320x240}.
16000 This option is not available with the @code{haldclutsrc} filter.
16003 Specify the frame rate of the sourced video, as the number of frames
16004 generated per second. It has to be a string in the format
16005 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a floating point
16006 number or a valid video frame rate abbreviation. The default value is
16010 Set the sample aspect ratio of the sourced video.
16013 Set the duration of the sourced video. See
16014 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
16015 for the accepted syntax.
16017 If not specified, or the expressed duration is negative, the video is
16018 supposed to be generated forever.
16021 Set the number of decimals to show in the timestamp, only available in the
16022 @code{testsrc} source.
16024 The displayed timestamp value will correspond to the original
16025 timestamp value multiplied by the power of 10 of the specified
16026 value. Default value is 0.
16029 For example the following:
16031 testsrc=duration=5.3:size=qcif:rate=10
16034 will generate a video with a duration of 5.3 seconds, with size
16035 176x144 and a frame rate of 10 frames per second.
16037 The following graph description will generate a red source
16038 with an opacity of 0.2, with size "qcif" and a frame rate of 10
16041 color=c=red@@0.2:s=qcif:r=10
16044 If the input content is to be ignored, @code{nullsrc} can be used. The
16045 following command generates noise in the luminance plane by employing
16046 the @code{geq} filter:
16048 nullsrc=s=256x256, geq=random(1)*255:128:128
16051 @subsection Commands
16053 The @code{color} source supports the following commands:
16057 Set the color of the created image. Accepts the same syntax of the
16058 corresponding @option{color} option.
16061 @c man end VIDEO SOURCES
16063 @chapter Video Sinks
16064 @c man begin VIDEO SINKS
16066 Below is a description of the currently available video sinks.
16068 @section buffersink
16070 Buffer video frames, and make them available to the end of the filter
16073 This sink is mainly intended for programmatic use, in particular
16074 through the interface defined in @file{libavfilter/buffersink.h}
16075 or the options system.
16077 It accepts a pointer to an AVBufferSinkContext structure, which
16078 defines the incoming buffers' formats, to be passed as the opaque
16079 parameter to @code{avfilter_init_filter} for initialization.
16083 Null video sink: do absolutely nothing with the input video. It is
16084 mainly useful as a template and for use in analysis / debugging
16087 @c man end VIDEO SINKS
16089 @chapter Multimedia Filters
16090 @c man begin MULTIMEDIA FILTERS
16092 Below is a description of the currently available multimedia filters.
16096 Convert input audio to a video output, displaying the audio bit scope.
16098 The filter accepts the following options:
16102 Set frame rate, expressed as number of frames per second. Default
16106 Specify the video size for the output. For the syntax of this option, check the
16107 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
16108 Default value is @code{1024x256}.
16111 Specify list of colors separated by space or by '|' which will be used to
16112 draw channels. Unrecognized or missing colors will be replaced
16116 @section ahistogram
16118 Convert input audio to a video output, displaying the volume histogram.
16120 The filter accepts the following options:
16124 Specify how histogram is calculated.
16126 It accepts the following values:
16129 Use single histogram for all channels.
16131 Use separate histogram for each channel.
16133 Default is @code{single}.
16136 Set frame rate, expressed as number of frames per second. Default
16140 Specify the video size for the output. For the syntax of this option, check the
16141 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
16142 Default value is @code{hd720}.
16147 It accepts the following values:
16158 reverse logarithmic
16160 Default is @code{log}.
16163 Set amplitude scale.
16165 It accepts the following values:
16172 Default is @code{log}.
16175 Set how much frames to accumulate in histogram.
16176 Defauls is 1. Setting this to -1 accumulates all frames.
16179 Set histogram ratio of window height.
16182 Set sonogram sliding.
16184 It accepts the following values:
16187 replace old rows with new ones.
16189 scroll from top to bottom.
16191 Default is @code{replace}.
16194 @section aphasemeter
16196 Convert input audio to a video output, displaying the audio phase.
16198 The filter accepts the following options:
16202 Set the output frame rate. Default value is @code{25}.
16205 Set the video size for the output. For the syntax of this option, check the
16206 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
16207 Default value is @code{800x400}.
16212 Specify the red, green, blue contrast. Default values are @code{2},
16213 @code{7} and @code{1}.
16214 Allowed range is @code{[0, 255]}.
16217 Set color which will be used for drawing median phase. If color is
16218 @code{none} which is default, no median phase value will be drawn.
16221 Enable video output. Default is enabled.
16224 The filter also exports the frame metadata @code{lavfi.aphasemeter.phase} which
16225 represents mean phase of current audio frame. Value is in range @code{[-1, 1]}.
16226 The @code{-1} means left and right channels are completely out of phase and
16227 @code{1} means channels are in phase.
16229 @section avectorscope
16231 Convert input audio to a video output, representing the audio vector
16234 The filter is used to measure the difference between channels of stereo
16235 audio stream. A monoaural signal, consisting of identical left and right
16236 signal, results in straight vertical line. Any stereo separation is visible
16237 as a deviation from this line, creating a Lissajous figure.
16238 If the straight (or deviation from it) but horizontal line appears this
16239 indicates that the left and right channels are out of phase.
16241 The filter accepts the following options:
16245 Set the vectorscope mode.
16247 Available values are:
16250 Lissajous rotated by 45 degrees.
16253 Same as above but not rotated.
16256 Shape resembling half of circle.
16259 Default value is @samp{lissajous}.
16262 Set the video size for the output. For the syntax of this option, check the
16263 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
16264 Default value is @code{400x400}.
16267 Set the output frame rate. Default value is @code{25}.
16273 Specify the red, green, blue and alpha contrast. Default values are @code{40},
16274 @code{160}, @code{80} and @code{255}.
16275 Allowed range is @code{[0, 255]}.
16281 Specify the red, green, blue and alpha fade. Default values are @code{15},
16282 @code{10}, @code{5} and @code{5}.
16283 Allowed range is @code{[0, 255]}.
16286 Set the zoom factor. Default value is @code{1}. Allowed range is @code{[1, 10]}.
16289 Set the vectorscope drawing mode.
16291 Available values are:
16294 Draw dot for each sample.
16297 Draw line between previous and current sample.
16300 Default value is @samp{dot}.
16303 Specify amplitude scale of audio samples.
16305 Available values are:
16322 @subsection Examples
16326 Complete example using @command{ffplay}:
16328 ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
16329 [a] avectorscope=zoom=1.3:rc=2:gc=200:bc=10:rf=1:gf=8:bf=7 [out0]'
16333 @section bench, abench
16335 Benchmark part of a filtergraph.
16337 The filter accepts the following options:
16341 Start or stop a timer.
16343 Available values are:
16346 Get the current time, set it as frame metadata (using the key
16347 @code{lavfi.bench.start_time}), and forward the frame to the next filter.
16350 Get the current time and fetch the @code{lavfi.bench.start_time} metadata from
16351 the input frame metadata to get the time difference. Time difference, average,
16352 maximum and minimum time (respectively @code{t}, @code{avg}, @code{max} and
16353 @code{min}) are then printed. The timestamps are expressed in seconds.
16357 @subsection Examples
16361 Benchmark @ref{selectivecolor} filter:
16363 bench=start,selectivecolor=reds=-.2 .12 -.49,bench=stop
16369 Concatenate audio and video streams, joining them together one after the
16372 The filter works on segments of synchronized video and audio streams. All
16373 segments must have the same number of streams of each type, and that will
16374 also be the number of streams at output.
16376 The filter accepts the following options:
16381 Set the number of segments. Default is 2.
16384 Set the number of output video streams, that is also the number of video
16385 streams in each segment. Default is 1.
16388 Set the number of output audio streams, that is also the number of audio
16389 streams in each segment. Default is 0.
16392 Activate unsafe mode: do not fail if segments have a different format.
16396 The filter has @var{v}+@var{a} outputs: first @var{v} video outputs, then
16397 @var{a} audio outputs.
16399 There are @var{n}x(@var{v}+@var{a}) inputs: first the inputs for the first
16400 segment, in the same order as the outputs, then the inputs for the second
16403 Related streams do not always have exactly the same duration, for various
16404 reasons including codec frame size or sloppy authoring. For that reason,
16405 related synchronized streams (e.g. a video and its audio track) should be
16406 concatenated at once. The concat filter will use the duration of the longest
16407 stream in each segment (except the last one), and if necessary pad shorter
16408 audio streams with silence.
16410 For this filter to work correctly, all segments must start at timestamp 0.
16412 All corresponding streams must have the same parameters in all segments; the
16413 filtering system will automatically select a common pixel format for video
16414 streams, and a common sample format, sample rate and channel layout for
16415 audio streams, but other settings, such as resolution, must be converted
16416 explicitly by the user.
16418 Different frame rates are acceptable but will result in variable frame rate
16419 at output; be sure to configure the output file to handle it.
16421 @subsection Examples
16425 Concatenate an opening, an episode and an ending, all in bilingual version
16426 (video in stream 0, audio in streams 1 and 2):
16428 ffmpeg -i opening.mkv -i episode.mkv -i ending.mkv -filter_complex \
16429 '[0:0] [0:1] [0:2] [1:0] [1:1] [1:2] [2:0] [2:1] [2:2]
16430 concat=n=3:v=1:a=2 [v] [a1] [a2]' \
16431 -map '[v]' -map '[a1]' -map '[a2]' output.mkv
16435 Concatenate two parts, handling audio and video separately, using the
16436 (a)movie sources, and adjusting the resolution:
16438 movie=part1.mp4, scale=512:288 [v1] ; amovie=part1.mp4 [a1] ;
16439 movie=part2.mp4, scale=512:288 [v2] ; amovie=part2.mp4 [a2] ;
16440 [v1] [v2] concat [outv] ; [a1] [a2] concat=v=0:a=1 [outa]
16442 Note that a desync will happen at the stitch if the audio and video streams
16443 do not have exactly the same duration in the first file.
16447 @section drawgraph, adrawgraph
16449 Draw a graph using input video or audio metadata.
16451 It accepts the following parameters:
16455 Set 1st frame metadata key from which metadata values will be used to draw a graph.
16458 Set 1st foreground color expression.
16461 Set 2nd frame metadata key from which metadata values will be used to draw a graph.
16464 Set 2nd foreground color expression.
16467 Set 3rd frame metadata key from which metadata values will be used to draw a graph.
16470 Set 3rd foreground color expression.
16473 Set 4th frame metadata key from which metadata values will be used to draw a graph.
16476 Set 4th foreground color expression.
16479 Set minimal value of metadata value.
16482 Set maximal value of metadata value.
16485 Set graph background color. Default is white.
16490 Available values for mode is:
16497 Default is @code{line}.
16502 Available values for slide is:
16505 Draw new frame when right border is reached.
16508 Replace old columns with new ones.
16511 Scroll from right to left.
16514 Scroll from left to right.
16517 Draw single picture.
16520 Default is @code{frame}.
16523 Set size of graph video. For the syntax of this option, check the
16524 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
16525 The default value is @code{900x256}.
16527 The foreground color expressions can use the following variables:
16530 Minimal value of metadata value.
16533 Maximal value of metadata value.
16536 Current metadata key value.
16539 The color is defined as 0xAABBGGRR.
16542 Example using metadata from @ref{signalstats} filter:
16544 signalstats,drawgraph=lavfi.signalstats.YAVG:min=0:max=255
16547 Example using metadata from @ref{ebur128} filter:
16549 ebur128=metadata=1,adrawgraph=lavfi.r128.M:min=-120:max=5
16555 EBU R128 scanner filter. This filter takes an audio stream as input and outputs
16556 it unchanged. By default, it logs a message at a frequency of 10Hz with the
16557 Momentary loudness (identified by @code{M}), Short-term loudness (@code{S}),
16558 Integrated loudness (@code{I}) and Loudness Range (@code{LRA}).
16560 The filter also has a video output (see the @var{video} option) with a real
16561 time graph to observe the loudness evolution. The graphic contains the logged
16562 message mentioned above, so it is not printed anymore when this option is set,
16563 unless the verbose logging is set. The main graphing area contains the
16564 short-term loudness (3 seconds of analysis), and the gauge on the right is for
16565 the momentary loudness (400 milliseconds).
16567 More information about the Loudness Recommendation EBU R128 on
16568 @url{http://tech.ebu.ch/loudness}.
16570 The filter accepts the following options:
16575 Activate the video output. The audio stream is passed unchanged whether this
16576 option is set or no. The video stream will be the first output stream if
16577 activated. Default is @code{0}.
16580 Set the video size. This option is for video only. For the syntax of this
16582 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
16583 Default and minimum resolution is @code{640x480}.
16586 Set the EBU scale meter. Default is @code{9}. Common values are @code{9} and
16587 @code{18}, respectively for EBU scale meter +9 and EBU scale meter +18. Any
16588 other integer value between this range is allowed.
16591 Set metadata injection. If set to @code{1}, the audio input will be segmented
16592 into 100ms output frames, each of them containing various loudness information
16593 in metadata. All the metadata keys are prefixed with @code{lavfi.r128.}.
16595 Default is @code{0}.
16598 Force the frame logging level.
16600 Available values are:
16603 information logging level
16605 verbose logging level
16608 By default, the logging level is set to @var{info}. If the @option{video} or
16609 the @option{metadata} options are set, it switches to @var{verbose}.
16614 Available modes can be cumulated (the option is a @code{flag} type). Possible
16618 Disable any peak mode (default).
16620 Enable sample-peak mode.
16622 Simple peak mode looking for the higher sample value. It logs a message
16623 for sample-peak (identified by @code{SPK}).
16625 Enable true-peak mode.
16627 If enabled, the peak lookup is done on an over-sampled version of the input
16628 stream for better peak accuracy. It logs a message for true-peak.
16629 (identified by @code{TPK}) and true-peak per frame (identified by @code{FTPK}).
16630 This mode requires a build with @code{libswresample}.
16634 Treat mono input files as "dual mono". If a mono file is intended for playback
16635 on a stereo system, its EBU R128 measurement will be perceptually incorrect.
16636 If set to @code{true}, this option will compensate for this effect.
16637 Multi-channel input files are not affected by this option.
16640 Set a specific pan law to be used for the measurement of dual mono files.
16641 This parameter is optional, and has a default value of -3.01dB.
16644 @subsection Examples
16648 Real-time graph using @command{ffplay}, with a EBU scale meter +18:
16650 ffplay -f lavfi -i "amovie=input.mp3,ebur128=video=1:meter=18 [out0][out1]"
16654 Run an analysis with @command{ffmpeg}:
16656 ffmpeg -nostats -i input.mp3 -filter_complex ebur128 -f null -
16660 @section interleave, ainterleave
16662 Temporally interleave frames from several inputs.
16664 @code{interleave} works with video inputs, @code{ainterleave} with audio.
16666 These filters read frames from several inputs and send the oldest
16667 queued frame to the output.
16669 Input streams must have well defined, monotonically increasing frame
16672 In order to submit one frame to output, these filters need to enqueue
16673 at least one frame for each input, so they cannot work in case one
16674 input is not yet terminated and will not receive incoming frames.
16676 For example consider the case when one input is a @code{select} filter
16677 which always drops input frames. The @code{interleave} filter will keep
16678 reading from that input, but it will never be able to send new frames
16679 to output until the input sends an end-of-stream signal.
16681 Also, depending on inputs synchronization, the filters will drop
16682 frames in case one input receives more frames than the other ones, and
16683 the queue is already filled.
16685 These filters accept the following options:
16689 Set the number of different inputs, it is 2 by default.
16692 @subsection Examples
16696 Interleave frames belonging to different streams using @command{ffmpeg}:
16698 ffmpeg -i bambi.avi -i pr0n.mkv -filter_complex "[0:v][1:v] interleave" out.avi
16702 Add flickering blur effect:
16704 select='if(gt(random(0), 0.2), 1, 2)':n=2 [tmp], boxblur=2:2, [tmp] interleave
16708 @section metadata, ametadata
16710 Manipulate frame metadata.
16712 This filter accepts the following options:
16716 Set mode of operation of the filter.
16718 Can be one of the following:
16722 If both @code{value} and @code{key} is set, select frames
16723 which have such metadata. If only @code{key} is set, select
16724 every frame that has such key in metadata.
16727 Add new metadata @code{key} and @code{value}. If key is already available
16731 Modify value of already present key.
16734 If @code{value} is set, delete only keys that have such value.
16735 Otherwise, delete key. If @code{key} is not set, delete all metadata values in
16739 Print key and its value if metadata was found. If @code{key} is not set print all
16740 metadata values available in frame.
16744 Set key used with all modes. Must be set for all modes except @code{print} and @code{delete}.
16747 Set metadata value which will be used. This option is mandatory for
16748 @code{modify} and @code{add} mode.
16751 Which function to use when comparing metadata value and @code{value}.
16753 Can be one of following:
16757 Values are interpreted as strings, returns true if metadata value is same as @code{value}.
16760 Values are interpreted as strings, returns true if metadata value starts with
16761 the @code{value} option string.
16764 Values are interpreted as floats, returns true if metadata value is less than @code{value}.
16767 Values are interpreted as floats, returns true if @code{value} is equal with metadata value.
16770 Values are interpreted as floats, returns true if metadata value is greater than @code{value}.
16773 Values are interpreted as floats, returns true if expression from option @code{expr}
16778 Set expression which is used when @code{function} is set to @code{expr}.
16779 The expression is evaluated through the eval API and can contain the following
16784 Float representation of @code{value} from metadata key.
16787 Float representation of @code{value} as supplied by user in @code{value} option.
16791 If specified in @code{print} mode, output is written to the named file. Instead of
16792 plain filename any writable url can be specified. Filename ``-'' is a shorthand
16793 for standard output. If @code{file} option is not set, output is written to the log
16794 with AV_LOG_INFO loglevel.
16798 @subsection Examples
16802 Print all metadata values for frames with key @code{lavfi.singnalstats.YDIF} with values
16805 signalstats,metadata=print:key=lavfi.signalstats.YDIF:value=0:function=expr:expr='between(VALUE1,0,1)'
16808 Print silencedetect output to file @file{metadata.txt}.
16810 silencedetect,ametadata=mode=print:file=metadata.txt
16813 Direct all metadata to a pipe with file descriptor 4.
16815 metadata=mode=print:file='pipe\:4'
16819 @section perms, aperms
16821 Set read/write permissions for the output frames.
16823 These filters are mainly aimed at developers to test direct path in the
16824 following filter in the filtergraph.
16826 The filters accept the following options:
16830 Select the permissions mode.
16832 It accepts the following values:
16835 Do nothing. This is the default.
16837 Set all the output frames read-only.
16839 Set all the output frames directly writable.
16841 Make the frame read-only if writable, and writable if read-only.
16843 Set each output frame read-only or writable randomly.
16847 Set the seed for the @var{random} mode, must be an integer included between
16848 @code{0} and @code{UINT32_MAX}. If not specified, or if explicitly set to
16849 @code{-1}, the filter will try to use a good random seed on a best effort
16853 Note: in case of auto-inserted filter between the permission filter and the
16854 following one, the permission might not be received as expected in that
16855 following filter. Inserting a @ref{format} or @ref{aformat} filter before the
16856 perms/aperms filter can avoid this problem.
16858 @section realtime, arealtime
16860 Slow down filtering to match real time approximatively.
16862 These filters will pause the filtering for a variable amount of time to
16863 match the output rate with the input timestamps.
16864 They are similar to the @option{re} option to @code{ffmpeg}.
16866 They accept the following options:
16870 Time limit for the pauses. Any pause longer than that will be considered
16871 a timestamp discontinuity and reset the timer. Default is 2 seconds.
16875 @section select, aselect
16877 Select frames to pass in output.
16879 This filter accepts the following options:
16884 Set expression, which is evaluated for each input frame.
16886 If the expression is evaluated to zero, the frame is discarded.
16888 If the evaluation result is negative or NaN, the frame is sent to the
16889 first output; otherwise it is sent to the output with index
16890 @code{ceil(val)-1}, assuming that the input index starts from 0.
16892 For example a value of @code{1.2} corresponds to the output with index
16893 @code{ceil(1.2)-1 = 2-1 = 1}, that is the second output.
16896 Set the number of outputs. The output to which to send the selected
16897 frame is based on the result of the evaluation. Default value is 1.
16900 The expression can contain the following constants:
16904 The (sequential) number of the filtered frame, starting from 0.
16907 The (sequential) number of the selected frame, starting from 0.
16909 @item prev_selected_n
16910 The sequential number of the last selected frame. It's NAN if undefined.
16913 The timebase of the input timestamps.
16916 The PTS (Presentation TimeStamp) of the filtered video frame,
16917 expressed in @var{TB} units. It's NAN if undefined.
16920 The PTS of the filtered video frame,
16921 expressed in seconds. It's NAN if undefined.
16924 The PTS of the previously filtered video frame. It's NAN if undefined.
16926 @item prev_selected_pts
16927 The PTS of the last previously filtered video frame. It's NAN if undefined.
16929 @item prev_selected_t
16930 The PTS of the last previously selected video frame. It's NAN if undefined.
16933 The PTS of the first video frame in the video. It's NAN if undefined.
16936 The time of the first video frame in the video. It's NAN if undefined.
16938 @item pict_type @emph{(video only)}
16939 The type of the filtered frame. It can assume one of the following
16951 @item interlace_type @emph{(video only)}
16952 The frame interlace type. It can assume one of the following values:
16955 The frame is progressive (not interlaced).
16957 The frame is top-field-first.
16959 The frame is bottom-field-first.
16962 @item consumed_sample_n @emph{(audio only)}
16963 the number of selected samples before the current frame
16965 @item samples_n @emph{(audio only)}
16966 the number of samples in the current frame
16968 @item sample_rate @emph{(audio only)}
16969 the input sample rate
16972 This is 1 if the filtered frame is a key-frame, 0 otherwise.
16975 the position in the file of the filtered frame, -1 if the information
16976 is not available (e.g. for synthetic video)
16978 @item scene @emph{(video only)}
16979 value between 0 and 1 to indicate a new scene; a low value reflects a low
16980 probability for the current frame to introduce a new scene, while a higher
16981 value means the current frame is more likely to be one (see the example below)
16983 @item concatdec_select
16984 The concat demuxer can select only part of a concat input file by setting an
16985 inpoint and an outpoint, but the output packets may not be entirely contained
16986 in the selected interval. By using this variable, it is possible to skip frames
16987 generated by the concat demuxer which are not exactly contained in the selected
16990 This works by comparing the frame pts against the @var{lavf.concat.start_time}
16991 and the @var{lavf.concat.duration} packet metadata values which are also
16992 present in the decoded frames.
16994 The @var{concatdec_select} variable is -1 if the frame pts is at least
16995 start_time and either the duration metadata is missing or the frame pts is less
16996 than start_time + duration, 0 otherwise, and NaN if the start_time metadata is
16999 That basically means that an input frame is selected if its pts is within the
17000 interval set by the concat demuxer.
17004 The default value of the select expression is "1".
17006 @subsection Examples
17010 Select all frames in input:
17015 The example above is the same as:
17027 Select only I-frames:
17029 select='eq(pict_type\,I)'
17033 Select one frame every 100:
17035 select='not(mod(n\,100))'
17039 Select only frames contained in the 10-20 time interval:
17041 select=between(t\,10\,20)
17045 Select only I-frames contained in the 10-20 time interval:
17047 select=between(t\,10\,20)*eq(pict_type\,I)
17051 Select frames with a minimum distance of 10 seconds:
17053 select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)'
17057 Use aselect to select only audio frames with samples number > 100:
17059 aselect='gt(samples_n\,100)'
17063 Create a mosaic of the first scenes:
17065 ffmpeg -i video.avi -vf select='gt(scene\,0.4)',scale=160:120,tile -frames:v 1 preview.png
17068 Comparing @var{scene} against a value between 0.3 and 0.5 is generally a sane
17072 Send even and odd frames to separate outputs, and compose them:
17074 select=n=2:e='mod(n, 2)+1' [odd][even]; [odd] pad=h=2*ih [tmp]; [tmp][even] overlay=y=h
17078 Select useful frames from an ffconcat file which is using inpoints and
17079 outpoints but where the source files are not intra frame only.
17081 ffmpeg -copyts -vsync 0 -segment_time_metadata 1 -i input.ffconcat -vf select=concatdec_select -af aselect=concatdec_select output.avi
17085 @section sendcmd, asendcmd
17087 Send commands to filters in the filtergraph.
17089 These filters read commands to be sent to other filters in the
17092 @code{sendcmd} must be inserted between two video filters,
17093 @code{asendcmd} must be inserted between two audio filters, but apart
17094 from that they act the same way.
17096 The specification of commands can be provided in the filter arguments
17097 with the @var{commands} option, or in a file specified by the
17098 @var{filename} option.
17100 These filters accept the following options:
17103 Set the commands to be read and sent to the other filters.
17105 Set the filename of the commands to be read and sent to the other
17109 @subsection Commands syntax
17111 A commands description consists of a sequence of interval
17112 specifications, comprising a list of commands to be executed when a
17113 particular event related to that interval occurs. The occurring event
17114 is typically the current frame time entering or leaving a given time
17117 An interval is specified by the following syntax:
17119 @var{START}[-@var{END}] @var{COMMANDS};
17122 The time interval is specified by the @var{START} and @var{END} times.
17123 @var{END} is optional and defaults to the maximum time.
17125 The current frame time is considered within the specified interval if
17126 it is included in the interval [@var{START}, @var{END}), that is when
17127 the time is greater or equal to @var{START} and is lesser than
17130 @var{COMMANDS} consists of a sequence of one or more command
17131 specifications, separated by ",", relating to that interval. The
17132 syntax of a command specification is given by:
17134 [@var{FLAGS}] @var{TARGET} @var{COMMAND} @var{ARG}
17137 @var{FLAGS} is optional and specifies the type of events relating to
17138 the time interval which enable sending the specified command, and must
17139 be a non-null sequence of identifier flags separated by "+" or "|" and
17140 enclosed between "[" and "]".
17142 The following flags are recognized:
17145 The command is sent when the current frame timestamp enters the
17146 specified interval. In other words, the command is sent when the
17147 previous frame timestamp was not in the given interval, and the
17151 The command is sent when the current frame timestamp leaves the
17152 specified interval. In other words, the command is sent when the
17153 previous frame timestamp was in the given interval, and the
17157 If @var{FLAGS} is not specified, a default value of @code{[enter]} is
17160 @var{TARGET} specifies the target of the command, usually the name of
17161 the filter class or a specific filter instance name.
17163 @var{COMMAND} specifies the name of the command for the target filter.
17165 @var{ARG} is optional and specifies the optional list of argument for
17166 the given @var{COMMAND}.
17168 Between one interval specification and another, whitespaces, or
17169 sequences of characters starting with @code{#} until the end of line,
17170 are ignored and can be used to annotate comments.
17172 A simplified BNF description of the commands specification syntax
17175 @var{COMMAND_FLAG} ::= "enter" | "leave"
17176 @var{COMMAND_FLAGS} ::= @var{COMMAND_FLAG} [(+|"|")@var{COMMAND_FLAG}]
17177 @var{COMMAND} ::= ["[" @var{COMMAND_FLAGS} "]"] @var{TARGET} @var{COMMAND} [@var{ARG}]
17178 @var{COMMANDS} ::= @var{COMMAND} [,@var{COMMANDS}]
17179 @var{INTERVAL} ::= @var{START}[-@var{END}] @var{COMMANDS}
17180 @var{INTERVALS} ::= @var{INTERVAL}[;@var{INTERVALS}]
17183 @subsection Examples
17187 Specify audio tempo change at second 4:
17189 asendcmd=c='4.0 atempo tempo 1.5',atempo
17193 Specify a list of drawtext and hue commands in a file.
17195 # show text in the interval 5-10
17196 5.0-10.0 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=hello world',
17197 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=';
17199 # desaturate the image in the interval 15-20
17200 15.0-20.0 [enter] hue s 0,
17201 [enter] drawtext reinit 'fontfile=FreeSerif.ttf:text=nocolor',
17203 [leave] drawtext reinit 'fontfile=FreeSerif.ttf:text=color';
17205 # apply an exponential saturation fade-out effect, starting from time 25
17206 25 [enter] hue s exp(25-t)
17209 A filtergraph allowing to read and process the above command list
17210 stored in a file @file{test.cmd}, can be specified with:
17212 sendcmd=f=test.cmd,drawtext=fontfile=FreeSerif.ttf:text='',hue
17217 @section setpts, asetpts
17219 Change the PTS (presentation timestamp) of the input frames.
17221 @code{setpts} works on video frames, @code{asetpts} on audio frames.
17223 This filter accepts the following options:
17228 The expression which is evaluated for each frame to construct its timestamp.
17232 The expression is evaluated through the eval API and can contain the following
17237 frame rate, only defined for constant frame-rate video
17240 The presentation timestamp in input
17243 The count of the input frame for video or the number of consumed samples,
17244 not including the current frame for audio, starting from 0.
17246 @item NB_CONSUMED_SAMPLES
17247 The number of consumed samples, not including the current frame (only
17250 @item NB_SAMPLES, S
17251 The number of samples in the current frame (only audio)
17253 @item SAMPLE_RATE, SR
17254 The audio sample rate.
17257 The PTS of the first frame.
17260 the time in seconds of the first frame
17263 State whether the current frame is interlaced.
17266 the time in seconds of the current frame
17269 original position in the file of the frame, or undefined if undefined
17270 for the current frame
17273 The previous input PTS.
17276 previous input time in seconds
17279 The previous output PTS.
17282 previous output time in seconds
17285 The wallclock (RTC) time in microseconds. This is deprecated, use time(0)
17289 The wallclock (RTC) time at the start of the movie in microseconds.
17292 The timebase of the input timestamps.
17296 @subsection Examples
17300 Start counting PTS from zero
17302 setpts=PTS-STARTPTS
17306 Apply fast motion effect:
17312 Apply slow motion effect:
17318 Set fixed rate of 25 frames per second:
17324 Set fixed rate 25 fps with some jitter:
17326 setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
17330 Apply an offset of 10 seconds to the input PTS:
17336 Generate timestamps from a "live source" and rebase onto the current timebase:
17338 setpts='(RTCTIME - RTCSTART) / (TB * 1000000)'
17342 Generate timestamps by counting samples:
17349 @section settb, asettb
17351 Set the timebase to use for the output frames timestamps.
17352 It is mainly useful for testing timebase configuration.
17354 It accepts the following parameters:
17359 The expression which is evaluated into the output timebase.
17363 The value for @option{tb} is an arithmetic expression representing a
17364 rational. The expression can contain the constants "AVTB" (the default
17365 timebase), "intb" (the input timebase) and "sr" (the sample rate,
17366 audio only). Default value is "intb".
17368 @subsection Examples
17372 Set the timebase to 1/25:
17378 Set the timebase to 1/10:
17384 Set the timebase to 1001/1000:
17390 Set the timebase to 2*intb:
17396 Set the default timebase value:
17403 Convert input audio to a video output representing frequency spectrum
17404 logarithmically using Brown-Puckette constant Q transform algorithm with
17405 direct frequency domain coefficient calculation (but the transform itself
17406 is not really constant Q, instead the Q factor is actually variable/clamped),
17407 with musical tone scale, from E0 to D#10.
17409 The filter accepts the following options:
17413 Specify the video size for the output. It must be even. For the syntax of this option,
17414 check the @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
17415 Default value is @code{1920x1080}.
17418 Set the output frame rate. Default value is @code{25}.
17421 Set the bargraph height. It must be even. Default value is @code{-1} which
17422 computes the bargraph height automatically.
17425 Set the axis height. It must be even. Default value is @code{-1} which computes
17426 the axis height automatically.
17429 Set the sonogram height. It must be even. Default value is @code{-1} which
17430 computes the sonogram height automatically.
17433 Set the fullhd resolution. This option is deprecated, use @var{size}, @var{s}
17434 instead. Default value is @code{1}.
17436 @item sono_v, volume
17437 Specify the sonogram volume expression. It can contain variables:
17440 the @var{bar_v} evaluated expression
17441 @item frequency, freq, f
17442 the frequency where it is evaluated
17443 @item timeclamp, tc
17444 the value of @var{timeclamp} option
17448 @item a_weighting(f)
17449 A-weighting of equal loudness
17450 @item b_weighting(f)
17451 B-weighting of equal loudness
17452 @item c_weighting(f)
17453 C-weighting of equal loudness.
17455 Default value is @code{16}.
17457 @item bar_v, volume2
17458 Specify the bargraph volume expression. It can contain variables:
17461 the @var{sono_v} evaluated expression
17462 @item frequency, freq, f
17463 the frequency where it is evaluated
17464 @item timeclamp, tc
17465 the value of @var{timeclamp} option
17469 @item a_weighting(f)
17470 A-weighting of equal loudness
17471 @item b_weighting(f)
17472 B-weighting of equal loudness
17473 @item c_weighting(f)
17474 C-weighting of equal loudness.
17476 Default value is @code{sono_v}.
17478 @item sono_g, gamma
17479 Specify the sonogram gamma. Lower gamma makes the spectrum more contrast,
17480 higher gamma makes the spectrum having more range. Default value is @code{3}.
17481 Acceptable range is @code{[1, 7]}.
17483 @item bar_g, gamma2
17484 Specify the bargraph gamma. Default value is @code{1}. Acceptable range is
17488 Specify the bargraph transparency level. Lower value makes the bargraph sharper.
17489 Default value is @code{1}. Acceptable range is @code{[0, 1]}.
17491 @item timeclamp, tc
17492 Specify the transform timeclamp. At low frequency, there is trade-off between
17493 accuracy in time domain and frequency domain. If timeclamp is lower,
17494 event in time domain is represented more accurately (such as fast bass drum),
17495 otherwise event in frequency domain is represented more accurately
17496 (such as bass guitar). Acceptable range is @code{[0.002, 1]}. Default value is @code{0.17}.
17499 Set attack time in seconds. The default is @code{0} (disabled). Otherwise, it
17500 limits future samples by applying asymmetric windowing in time domain, useful
17501 when low latency is required. Accepted range is @code{[0, 1]}.
17504 Specify the transform base frequency. Default value is @code{20.01523126408007475},
17505 which is frequency 50 cents below E0. Acceptable range is @code{[10, 100000]}.
17508 Specify the transform end frequency. Default value is @code{20495.59681441799654},
17509 which is frequency 50 cents above D#10. Acceptable range is @code{[10, 100000]}.
17512 This option is deprecated and ignored.
17515 Specify the transform length in time domain. Use this option to control accuracy
17516 trade-off between time domain and frequency domain at every frequency sample.
17517 It can contain variables:
17519 @item frequency, freq, f
17520 the frequency where it is evaluated
17521 @item timeclamp, tc
17522 the value of @var{timeclamp} option.
17524 Default value is @code{384*tc/(384+tc*f)}.
17527 Specify the transform count for every video frame. Default value is @code{6}.
17528 Acceptable range is @code{[1, 30]}.
17531 Specify the transform count for every single pixel. Default value is @code{0},
17532 which makes it computed automatically. Acceptable range is @code{[0, 10]}.
17535 Specify font file for use with freetype to draw the axis. If not specified,
17536 use embedded font. Note that drawing with font file or embedded font is not
17537 implemented with custom @var{basefreq} and @var{endfreq}, use @var{axisfile}
17541 Specify fontconfig pattern. This has lower priority than @var{fontfile}.
17542 The : in the pattern may be replaced by | to avoid unnecessary escaping.
17545 Specify font color expression. This is arithmetic expression that should return
17546 integer value 0xRRGGBB. It can contain variables:
17548 @item frequency, freq, f
17549 the frequency where it is evaluated
17550 @item timeclamp, tc
17551 the value of @var{timeclamp} option
17556 midi number of frequency f, some midi numbers: E0(16), C1(24), C2(36), A4(69)
17557 @item r(x), g(x), b(x)
17558 red, green, and blue value of intensity x.
17560 Default value is @code{st(0, (midi(f)-59.5)/12);
17561 st(1, if(between(ld(0),0,1), 0.5-0.5*cos(2*PI*ld(0)), 0));
17562 r(1-ld(1)) + b(ld(1))}.
17565 Specify image file to draw the axis. This option override @var{fontfile} and
17566 @var{fontcolor} option.
17569 Enable/disable drawing text to the axis. If it is set to @code{0}, drawing to
17570 the axis is disabled, ignoring @var{fontfile} and @var{axisfile} option.
17571 Default value is @code{1}.
17574 Set colorspace. The accepted values are:
17577 Unspecified (default)
17586 BT.470BG or BT.601-6 625
17589 SMPTE-170M or BT.601-6 525
17595 BT.2020 with non-constant luminance
17600 Set spectrogram color scheme. This is list of floating point values with format
17601 @code{left_r|left_g|left_b|right_r|right_g|right_b}.
17602 The default is @code{1|0.5|0|0|0.5|1}.
17606 @subsection Examples
17610 Playing audio while showing the spectrum:
17612 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt [out0]'
17616 Same as above, but with frame rate 30 fps:
17618 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=fps=30:count=5 [out0]'
17622 Playing at 1280x720:
17624 ffplay -f lavfi 'amovie=a.mp3, asplit [a][out1]; [a] showcqt=s=1280x720:count=4 [out0]'
17628 Disable sonogram display:
17634 A1 and its harmonics: A1, A2, (near)E3, A3:
17636 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),
17637 asplit[a][out1]; [a] showcqt [out0]'
17641 Same as above, but with more accuracy in frequency domain:
17643 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),
17644 asplit[a][out1]; [a] showcqt=timeclamp=0.5 [out0]'
17650 bar_v=10:sono_v=bar_v*a_weighting(f)
17654 Custom gamma, now spectrum is linear to the amplitude.
17660 Custom tlength equation:
17662 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)))'
17666 Custom fontcolor and fontfile, C-note is colored green, others are colored blue:
17668 fontcolor='if(mod(floor(midi(f)+0.5),12), 0x0000FF, g(1))':fontfile=myfont.ttf
17672 Custom font using fontconfig:
17674 font='Courier New,Monospace,mono|bold'
17678 Custom frequency range with custom axis using image file:
17680 axisfile=myaxis.png:basefreq=40:endfreq=10000
17686 Convert input audio to video output representing the audio power spectrum.
17687 Audio amplitude is on Y-axis while frequency is on X-axis.
17689 The filter accepts the following options:
17693 Specify size of video. For the syntax of this option, check the
17694 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
17695 Default is @code{1024x512}.
17699 This set how each frequency bin will be represented.
17701 It accepts the following values:
17707 Default is @code{bar}.
17710 Set amplitude scale.
17712 It accepts the following values:
17726 Default is @code{log}.
17729 Set frequency scale.
17731 It accepts the following values:
17740 Reverse logarithmic scale.
17742 Default is @code{lin}.
17747 It accepts the following values:
17763 Default is @code{w2048}
17766 Set windowing function.
17768 It accepts the following values:
17790 Default is @code{hanning}.
17793 Set window overlap. In range @code{[0, 1]}. Default is @code{1},
17794 which means optimal overlap for selected window function will be picked.
17797 Set time averaging. Setting this to 0 will display current maximal peaks.
17798 Default is @code{1}, which means time averaging is disabled.
17801 Specify list of colors separated by space or by '|' which will be used to
17802 draw channel frequencies. Unrecognized or missing colors will be replaced
17806 Set channel display mode.
17808 It accepts the following values:
17813 Default is @code{combined}.
17816 Set minimum amplitude used in @code{log} amplitude scaler.
17820 @anchor{showspectrum}
17821 @section showspectrum
17823 Convert input audio to a video output, representing the audio frequency
17826 The filter accepts the following options:
17830 Specify the video size for the output. For the syntax of this option, check the
17831 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
17832 Default value is @code{640x512}.
17835 Specify how the spectrum should slide along the window.
17837 It accepts the following values:
17840 the samples start again on the left when they reach the right
17842 the samples scroll from right to left
17844 frames are only produced when the samples reach the right
17846 the samples scroll from left to right
17849 Default value is @code{replace}.
17852 Specify display mode.
17854 It accepts the following values:
17857 all channels are displayed in the same row
17859 all channels are displayed in separate rows
17862 Default value is @samp{combined}.
17865 Specify display color mode.
17867 It accepts the following values:
17870 each channel is displayed in a separate color
17872 each channel is displayed using the same color scheme
17874 each channel is displayed using the rainbow color scheme
17876 each channel is displayed using the moreland color scheme
17878 each channel is displayed using the nebulae color scheme
17880 each channel is displayed using the fire color scheme
17882 each channel is displayed using the fiery color scheme
17884 each channel is displayed using the fruit color scheme
17886 each channel is displayed using the cool color scheme
17889 Default value is @samp{channel}.
17892 Specify scale used for calculating intensity color values.
17894 It accepts the following values:
17899 square root, default
17910 Default value is @samp{sqrt}.
17913 Set saturation modifier for displayed colors. Negative values provide
17914 alternative color scheme. @code{0} is no saturation at all.
17915 Saturation must be in [-10.0, 10.0] range.
17916 Default value is @code{1}.
17919 Set window function.
17921 It accepts the following values:
17945 Default value is @code{hann}.
17948 Set orientation of time vs frequency axis. Can be @code{vertical} or
17949 @code{horizontal}. Default is @code{vertical}.
17952 Set ratio of overlap window. Default value is @code{0}.
17953 When value is @code{1} overlap is set to recommended size for specific
17954 window function currently used.
17957 Set scale gain for calculating intensity color values.
17958 Default value is @code{1}.
17961 Set which data to display. Can be @code{magnitude}, default or @code{phase}.
17964 Set color rotation, must be in [-1.0, 1.0] range.
17965 Default value is @code{0}.
17968 The usage is very similar to the showwaves filter; see the examples in that
17971 @subsection Examples
17975 Large window with logarithmic color scaling:
17977 showspectrum=s=1280x480:scale=log
17981 Complete example for a colored and sliding spectrum per channel using @command{ffplay}:
17983 ffplay -f lavfi 'amovie=input.mp3, asplit [a][out1];
17984 [a] showspectrum=mode=separate:color=intensity:slide=1:scale=cbrt [out0]'
17988 @section showspectrumpic
17990 Convert input audio to a single video frame, representing the audio frequency
17993 The filter accepts the following options:
17997 Specify the video size for the output. For the syntax of this option, check the
17998 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
17999 Default value is @code{4096x2048}.
18002 Specify display mode.
18004 It accepts the following values:
18007 all channels are displayed in the same row
18009 all channels are displayed in separate rows
18011 Default value is @samp{combined}.
18014 Specify display color mode.
18016 It accepts the following values:
18019 each channel is displayed in a separate color
18021 each channel is displayed using the same color scheme
18023 each channel is displayed using the rainbow color scheme
18025 each channel is displayed using the moreland color scheme
18027 each channel is displayed using the nebulae color scheme
18029 each channel is displayed using the fire color scheme
18031 each channel is displayed using the fiery color scheme
18033 each channel is displayed using the fruit color scheme
18035 each channel is displayed using the cool color scheme
18037 Default value is @samp{intensity}.
18040 Specify scale used for calculating intensity color values.
18042 It accepts the following values:
18047 square root, default
18057 Default value is @samp{log}.
18060 Set saturation modifier for displayed colors. Negative values provide
18061 alternative color scheme. @code{0} is no saturation at all.
18062 Saturation must be in [-10.0, 10.0] range.
18063 Default value is @code{1}.
18066 Set window function.
18068 It accepts the following values:
18091 Default value is @code{hann}.
18094 Set orientation of time vs frequency axis. Can be @code{vertical} or
18095 @code{horizontal}. Default is @code{vertical}.
18098 Set scale gain for calculating intensity color values.
18099 Default value is @code{1}.
18102 Draw time and frequency axes and legends. Default is enabled.
18105 Set color rotation, must be in [-1.0, 1.0] range.
18106 Default value is @code{0}.
18109 @subsection Examples
18113 Extract an audio spectrogram of a whole audio track
18114 in a 1024x1024 picture using @command{ffmpeg}:
18116 ffmpeg -i audio.flac -lavfi showspectrumpic=s=1024x1024 spectrogram.png
18120 @section showvolume
18122 Convert input audio volume to a video output.
18124 The filter accepts the following options:
18131 Set border width, allowed range is [0, 5]. Default is 1.
18134 Set channel width, allowed range is [80, 8192]. Default is 400.
18137 Set channel height, allowed range is [1, 900]. Default is 20.
18140 Set fade, allowed range is [0.001, 1]. Default is 0.95.
18143 Set volume color expression.
18145 The expression can use the following variables:
18149 Current max volume of channel in dB.
18155 Current channel number, starting from 0.
18159 If set, displays channel names. Default is enabled.
18162 If set, displays volume values. Default is enabled.
18165 Set orientation, can be @code{horizontal} or @code{vertical},
18166 default is @code{horizontal}.
18169 Set step size, allowed range s [0, 5]. Default is 0, which means
18175 Convert input audio to a video output, representing the samples waves.
18177 The filter accepts the following options:
18181 Specify the video size for the output. For the syntax of this option, check the
18182 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
18183 Default value is @code{600x240}.
18188 Available values are:
18191 Draw a point for each sample.
18194 Draw a vertical line for each sample.
18197 Draw a point for each sample and a line between them.
18200 Draw a centered vertical line for each sample.
18203 Default value is @code{point}.
18206 Set the number of samples which are printed on the same column. A
18207 larger value will decrease the frame rate. Must be a positive
18208 integer. This option can be set only if the value for @var{rate}
18209 is not explicitly specified.
18212 Set the (approximate) output frame rate. This is done by setting the
18213 option @var{n}. Default value is "25".
18215 @item split_channels
18216 Set if channels should be drawn separately or overlap. Default value is 0.
18219 Set colors separated by '|' which are going to be used for drawing of each channel.
18222 Set amplitude scale.
18224 Available values are:
18242 @subsection Examples
18246 Output the input file audio and the corresponding video representation
18249 amovie=a.mp3,asplit[out0],showwaves[out1]
18253 Create a synthetic signal and show it with showwaves, forcing a
18254 frame rate of 30 frames per second:
18256 aevalsrc=sin(1*2*PI*t)*sin(880*2*PI*t):cos(2*PI*200*t),asplit[out0],showwaves=r=30[out1]
18260 @section showwavespic
18262 Convert input audio to a single video frame, representing the samples waves.
18264 The filter accepts the following options:
18268 Specify the video size for the output. For the syntax of this option, check the
18269 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
18270 Default value is @code{600x240}.
18272 @item split_channels
18273 Set if channels should be drawn separately or overlap. Default value is 0.
18276 Set colors separated by '|' which are going to be used for drawing of each channel.
18279 Set amplitude scale.
18281 Available values are:
18299 @subsection Examples
18303 Extract a channel split representation of the wave form of a whole audio track
18304 in a 1024x800 picture using @command{ffmpeg}:
18306 ffmpeg -i audio.flac -lavfi showwavespic=split_channels=1:s=1024x800 waveform.png
18310 @section sidedata, asidedata
18312 Delete frame side data, or select frames based on it.
18314 This filter accepts the following options:
18318 Set mode of operation of the filter.
18320 Can be one of the following:
18324 Select every frame with side data of @code{type}.
18327 Delete side data of @code{type}. If @code{type} is not set, delete all side
18333 Set side data type used with all modes. Must be set for @code{select} mode. For
18334 the list of frame side data types, refer to the @code{AVFrameSideDataType} enum
18335 in @file{libavutil/frame.h}. For example, to choose
18336 @code{AV_FRAME_DATA_PANSCAN} side data, you must specify @code{PANSCAN}.
18340 @section spectrumsynth
18342 Sythesize audio from 2 input video spectrums, first input stream represents
18343 magnitude across time and second represents phase across time.
18344 The filter will transform from frequency domain as displayed in videos back
18345 to time domain as presented in audio output.
18347 This filter is primarily created for reversing processed @ref{showspectrum}
18348 filter outputs, but can synthesize sound from other spectrograms too.
18349 But in such case results are going to be poor if the phase data is not
18350 available, because in such cases phase data need to be recreated, usually
18351 its just recreated from random noise.
18352 For best results use gray only output (@code{channel} color mode in
18353 @ref{showspectrum} filter) and @code{log} scale for magnitude video and
18354 @code{lin} scale for phase video. To produce phase, for 2nd video, use
18355 @code{data} option. Inputs videos should generally use @code{fullframe}
18356 slide mode as that saves resources needed for decoding video.
18358 The filter accepts the following options:
18362 Specify sample rate of output audio, the sample rate of audio from which
18363 spectrum was generated may differ.
18366 Set number of channels represented in input video spectrums.
18369 Set scale which was used when generating magnitude input spectrum.
18370 Can be @code{lin} or @code{log}. Default is @code{log}.
18373 Set slide which was used when generating inputs spectrums.
18374 Can be @code{replace}, @code{scroll}, @code{fullframe} or @code{rscroll}.
18375 Default is @code{fullframe}.
18378 Set window function used for resynthesis.
18381 Set window overlap. In range @code{[0, 1]}. Default is @code{1},
18382 which means optimal overlap for selected window function will be picked.
18385 Set orientation of input videos. Can be @code{vertical} or @code{horizontal}.
18386 Default is @code{vertical}.
18389 @subsection Examples
18393 First create magnitude and phase videos from audio, assuming audio is stereo with 44100 sample rate,
18394 then resynthesize videos back to audio with spectrumsynth:
18396 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
18397 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
18398 ffmpeg -i magnitude.nut -i phase.nut -lavfi spectrumsynth=channels=2:sample_rate=44100:win_func=hann:overlap=0.875:slide=fullframe output.flac
18402 @section split, asplit
18404 Split input into several identical outputs.
18406 @code{asplit} works with audio input, @code{split} with video.
18408 The filter accepts a single parameter which specifies the number of outputs. If
18409 unspecified, it defaults to 2.
18411 @subsection Examples
18415 Create two separate outputs from the same input:
18417 [in] split [out0][out1]
18421 To create 3 or more outputs, you need to specify the number of
18424 [in] asplit=3 [out0][out1][out2]
18428 Create two separate outputs from the same input, one cropped and
18431 [in] split [splitout1][splitout2];
18432 [splitout1] crop=100:100:0:0 [cropout];
18433 [splitout2] pad=200:200:100:100 [padout];
18437 Create 5 copies of the input audio with @command{ffmpeg}:
18439 ffmpeg -i INPUT -filter_complex asplit=5 OUTPUT
18445 Receive commands sent through a libzmq client, and forward them to
18446 filters in the filtergraph.
18448 @code{zmq} and @code{azmq} work as a pass-through filters. @code{zmq}
18449 must be inserted between two video filters, @code{azmq} between two
18452 To enable these filters you need to install the libzmq library and
18453 headers and configure FFmpeg with @code{--enable-libzmq}.
18455 For more information about libzmq see:
18456 @url{http://www.zeromq.org/}
18458 The @code{zmq} and @code{azmq} filters work as a libzmq server, which
18459 receives messages sent through a network interface defined by the
18460 @option{bind_address} option.
18462 The received message must be in the form:
18464 @var{TARGET} @var{COMMAND} [@var{ARG}]
18467 @var{TARGET} specifies the target of the command, usually the name of
18468 the filter class or a specific filter instance name.
18470 @var{COMMAND} specifies the name of the command for the target filter.
18472 @var{ARG} is optional and specifies the optional argument list for the
18473 given @var{COMMAND}.
18475 Upon reception, the message is processed and the corresponding command
18476 is injected into the filtergraph. Depending on the result, the filter
18477 will send a reply to the client, adopting the format:
18479 @var{ERROR_CODE} @var{ERROR_REASON}
18483 @var{MESSAGE} is optional.
18485 @subsection Examples
18487 Look at @file{tools/zmqsend} for an example of a zmq client which can
18488 be used to send commands processed by these filters.
18490 Consider the following filtergraph generated by @command{ffplay}
18492 ffplay -dumpgraph 1 -f lavfi "
18493 color=s=100x100:c=red [l];
18494 color=s=100x100:c=blue [r];
18495 nullsrc=s=200x100, zmq [bg];
18496 [bg][l] overlay [bg+l];
18497 [bg+l][r] overlay=x=100 "
18500 To change the color of the left side of the video, the following
18501 command can be used:
18503 echo Parsed_color_0 c yellow | tools/zmqsend
18506 To change the right side:
18508 echo Parsed_color_1 c pink | tools/zmqsend
18511 @c man end MULTIMEDIA FILTERS
18513 @chapter Multimedia Sources
18514 @c man begin MULTIMEDIA SOURCES
18516 Below is a description of the currently available multimedia sources.
18520 This is the same as @ref{movie} source, except it selects an audio
18526 Read audio and/or video stream(s) from a movie container.
18528 It accepts the following parameters:
18532 The name of the resource to read (not necessarily a file; it can also be a
18533 device or a stream accessed through some protocol).
18535 @item format_name, f
18536 Specifies the format assumed for the movie to read, and can be either
18537 the name of a container or an input device. If not specified, the
18538 format is guessed from @var{movie_name} or by probing.
18540 @item seek_point, sp
18541 Specifies the seek point in seconds. The frames will be output
18542 starting from this seek point. The parameter is evaluated with
18543 @code{av_strtod}, so the numerical value may be suffixed by an IS
18544 postfix. The default value is "0".
18547 Specifies the streams to read. Several streams can be specified,
18548 separated by "+". The source will then have as many outputs, in the
18549 same order. The syntax is explained in the ``Stream specifiers''
18550 section in the ffmpeg manual. Two special names, "dv" and "da" specify
18551 respectively the default (best suited) video and audio stream. Default
18552 is "dv", or "da" if the filter is called as "amovie".
18554 @item stream_index, si
18555 Specifies the index of the video stream to read. If the value is -1,
18556 the most suitable video stream will be automatically selected. The default
18557 value is "-1". Deprecated. If the filter is called "amovie", it will select
18558 audio instead of video.
18561 Specifies how many times to read the stream in sequence.
18562 If the value is 0, the stream will be looped infinitely.
18563 Default value is "1".
18565 Note that when the movie is looped the source timestamps are not
18566 changed, so it will generate non monotonically increasing timestamps.
18568 @item discontinuity
18569 Specifies the time difference between frames above which the point is
18570 considered a timestamp discontinuity which is removed by adjusting the later
18574 It allows overlaying a second video on top of the main input of
18575 a filtergraph, as shown in this graph:
18577 input -----------> deltapts0 --> overlay --> output
18580 movie --> scale--> deltapts1 -------+
18582 @subsection Examples
18586 Skip 3.2 seconds from the start of the AVI file in.avi, and overlay it
18587 on top of the input labelled "in":
18589 movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [over];
18590 [in] setpts=PTS-STARTPTS [main];
18591 [main][over] overlay=16:16 [out]
18595 Read from a video4linux2 device, and overlay it on top of the input
18598 movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [over];
18599 [in] setpts=PTS-STARTPTS [main];
18600 [main][over] overlay=16:16 [out]
18604 Read the first video stream and the audio stream with id 0x81 from
18605 dvd.vob; the video is connected to the pad named "video" and the audio is
18606 connected to the pad named "audio":
18608 movie=dvd.vob:s=v:0+#0x81 [video] [audio]
18612 @subsection Commands
18614 Both movie and amovie support the following commands:
18617 Perform seek using "av_seek_frame".
18618 The syntax is: seek @var{stream_index}|@var{timestamp}|@var{flags}
18621 @var{stream_index}: If stream_index is -1, a default
18622 stream is selected, and @var{timestamp} is automatically converted
18623 from AV_TIME_BASE units to the stream specific time_base.
18625 @var{timestamp}: Timestamp in AVStream.time_base units
18626 or, if no stream is specified, in AV_TIME_BASE units.
18628 @var{flags}: Flags which select direction and seeking mode.
18632 Get movie duration in AV_TIME_BASE units.
18636 @c man end MULTIMEDIA SOURCES