56c722da7e1d9592604cdd5006960f33905961bf
[ffmpeg.git] / doc / filters.texi
1 @chapter Filtering Introduction
2 @c man begin FILTERING INTRODUCTION
3
4 Filtering in FFmpeg is enabled through the libavfilter library.
5
6 In libavfilter, a filter can have multiple inputs and multiple
7 outputs.
8 To illustrate the sorts of things that are possible, we consider the
9 following filtergraph.
10
11 @example
12 input --> split ---------------------> overlay --> output
13             |                             ^
14             |                             |
15             +-----> crop --> vflip -------+
16 @end example
17
18 This filtergraph splits the input stream in two streams, sends one
19 stream through the crop filter and the vflip filter before merging it
20 back with the other stream by overlaying it on top. You can use the
21 following command to achieve this:
22
23 @example
24 ffmpeg -i INPUT -vf "split [main][tmp]; [tmp] crop=iw:ih/2:0:0, vflip [flip]; [main][flip] overlay=0:H/2" OUTPUT
25 @end example
26
27 The result will be that in output the top half of the video is mirrored
28 onto the bottom half.
29
30 Filters in the same linear chain are separated by commas, and distinct
31 linear chains of filters are separated by semicolons. In our example,
32 @var{crop,vflip} are in one linear chain, @var{split} and
33 @var{overlay} are separately in another. The points where the linear
34 chains join are labelled by names enclosed in square brackets. In the
35 example, the split filter generates two outputs that are associated to
36 the labels @var{[main]} and @var{[tmp]}.
37
38 The stream sent to the second output of @var{split}, labelled as
39 @var{[tmp]}, is processed through the @var{crop} filter, which crops
40 away the lower half part of the video, and then vertically flipped. The
41 @var{overlay} filter takes in input the first unchanged output of the
42 split filter (which was labelled as @var{[main]}), and overlay on its
43 lower half the output generated by the @var{crop,vflip} filterchain.
44
45 Some filters take in input a list of parameters: they are specified
46 after the filter name and an equal sign, and are separated from each other
47 by a colon.
48
49 There exist so-called @var{source filters} that do not have an
50 audio/video input, and @var{sink filters} that will not have audio/video
51 output.
52
53 @c man end FILTERING INTRODUCTION
54
55 @chapter graph2dot
56 @c man begin GRAPH2DOT
57
58 The @file{graph2dot} program included in the FFmpeg @file{tools}
59 directory can be used to parse a filtergraph description and issue a
60 corresponding textual representation in the dot language.
61
62 Invoke the command:
63 @example
64 graph2dot -h
65 @end example
66
67 to see how to use @file{graph2dot}.
68
69 You can then pass the dot description to the @file{dot} program (from
70 the graphviz suite of programs) and obtain a graphical representation
71 of the filtergraph.
72
73 For example the sequence of commands:
74 @example
75 echo @var{GRAPH_DESCRIPTION} | \
76 tools/graph2dot -o graph.tmp && \
77 dot -Tpng graph.tmp -o graph.png && \
78 display graph.png
79 @end example
80
81 can be used to create and display an image representing the graph
82 described by the @var{GRAPH_DESCRIPTION} string. Note that this string must be
83 a complete self-contained graph, with its inputs and outputs explicitly defined.
84 For example if your command line is of the form:
85 @example
86 ffmpeg -i infile -vf scale=640:360 outfile
87 @end example
88 your @var{GRAPH_DESCRIPTION} string will need to be of the form:
89 @example
90 nullsrc,scale=640:360,nullsink
91 @end example
92 you may also need to set the @var{nullsrc} parameters and add a @var{format}
93 filter in order to simulate a specific input file.
94
95 @c man end GRAPH2DOT
96
97 @chapter Filtergraph description
98 @c man begin FILTERGRAPH DESCRIPTION
99
100 A filtergraph is a directed graph of connected filters. It can contain
101 cycles, and there can be multiple links between a pair of
102 filters. Each link has one input pad on one side connecting it to one
103 filter from which it takes its input, and one output pad on the other
104 side connecting it to the one filter accepting its output.
105
106 Each filter in a filtergraph is an instance of a filter class
107 registered in the application, which defines the features and the
108 number of input and output pads of the filter.
109
110 A filter with no input pads is called a "source", a filter with no
111 output pads is called a "sink".
112
113 @anchor{Filtergraph syntax}
114 @section Filtergraph syntax
115
116 A filtergraph can be represented using a textual representation, which is
117 recognized by the @option{-filter}/@option{-vf} and @option{-filter_complex}
118 options in @command{ffmpeg} and @option{-vf} in @command{ffplay}, and by the
119 @code{avfilter_graph_parse()}/@code{avfilter_graph_parse2()} function defined in
120 @file{libavfilter/avfilter.h}.
121
122 A filterchain consists of a sequence of connected filters, each one
123 connected to the previous one in the sequence. A filterchain is
124 represented by a list of ","-separated filter descriptions.
125
126 A filtergraph consists of a sequence of filterchains. A sequence of
127 filterchains is represented by a list of ";"-separated filterchain
128 descriptions.
129
130 A filter is represented by a string of the form:
131 [@var{in_link_1}]...[@var{in_link_N}]@var{filter_name}=@var{arguments}[@var{out_link_1}]...[@var{out_link_M}]
132
133 @var{filter_name} is the name of the filter class of which the
134 described filter is an instance of, and has to be the name of one of
135 the filter classes registered in the program.
136 The name of the filter class is optionally followed by a string
137 "=@var{arguments}".
138
139 @var{arguments} is a string which contains the parameters used to
140 initialize the filter instance. It may have one of the following forms:
141 @itemize
142
143 @item
144 A ':'-separated list of @var{key=value} pairs.
145
146 @item
147 A ':'-separated list of @var{value}. In this case, the keys are assumed to be
148 the option names in the order they are declared. E.g. the @code{fade} filter
149 declares three options in this order -- @option{type}, @option{start_frame} and
150 @option{nb_frames}. Then the parameter list @var{in:0:30} means that the value
151 @var{in} is assigned to the option @option{type}, @var{0} to
152 @option{start_frame} and @var{30} to @option{nb_frames}.
153
154 @item
155 A ':'-separated list of mixed direct @var{value} and long @var{key=value}
156 pairs. The direct @var{value} must precede the @var{key=value} pairs, and
157 follow the same constraints order of the previous point. The following
158 @var{key=value} pairs can be set in any preferred order.
159
160 @end itemize
161
162 If the option value itself is a list of items (e.g. the @code{format} filter
163 takes a list of pixel formats), the items in the list are usually separated by
164 '|'.
165
166 The list of arguments can be quoted using the character "'" as initial
167 and ending mark, and the character '\' for escaping the characters
168 within the quoted text; otherwise the argument string is considered
169 terminated when the next special character (belonging to the set
170 "[]=;,") is encountered.
171
172 The name and arguments of the filter are optionally preceded and
173 followed by a list of link labels.
174 A link label allows to name a link and associate it to a filter output
175 or input pad. The preceding labels @var{in_link_1}
176 ... @var{in_link_N}, are associated to the filter input pads,
177 the following labels @var{out_link_1} ... @var{out_link_M}, are
178 associated to the output pads.
179
180 When two link labels with the same name are found in the
181 filtergraph, a link between the corresponding input and output pad is
182 created.
183
184 If an output pad is not labelled, it is linked by default to the first
185 unlabelled input pad of the next filter in the filterchain.
186 For example in the filterchain:
187 @example
188 nullsrc, split[L1], [L2]overlay, nullsink
189 @end example
190 the split filter instance has two output pads, and the overlay filter
191 instance two input pads. The first output pad of split is labelled
192 "L1", the first input pad of overlay is labelled "L2", and the second
193 output pad of split is linked to the second input pad of overlay,
194 which are both unlabelled.
195
196 In a complete filterchain all the unlabelled filter input and output
197 pads must be connected. A filtergraph is considered valid if all the
198 filter input and output pads of all the filterchains are connected.
199
200 Libavfilter will automatically insert scale filters where format
201 conversion is required. It is possible to specify swscale flags
202 for those automatically inserted scalers by prepending
203 @code{sws_flags=@var{flags};}
204 to the filtergraph description.
205
206 Follows a BNF description for the filtergraph syntax:
207 @example
208 @var{NAME}             ::= sequence of alphanumeric characters and '_'
209 @var{LINKLABEL}        ::= "[" @var{NAME} "]"
210 @var{LINKLABELS}       ::= @var{LINKLABEL} [@var{LINKLABELS}]
211 @var{FILTER_ARGUMENTS} ::= sequence of chars (eventually quoted)
212 @var{FILTER}           ::= [@var{LINKLABELS}] @var{NAME} ["=" @var{FILTER_ARGUMENTS}] [@var{LINKLABELS}]
213 @var{FILTERCHAIN}      ::= @var{FILTER} [,@var{FILTERCHAIN}]
214 @var{FILTERGRAPH}      ::= [sws_flags=@var{flags};] @var{FILTERCHAIN} [;@var{FILTERGRAPH}]
215 @end example
216
217 @section Notes on filtergraph escaping
218
219 Some filter arguments require the use of special characters, typically
220 @code{:} to separate key=value pairs in a named options list. In this
221 case the user should perform a first level escaping when specifying
222 the filter arguments. For example, consider the following literal
223 string to be embedded in the @ref{drawtext} filter arguments:
224 @example
225 this is a 'string': may contain one, or more, special characters
226 @end example
227
228 Since @code{:} is special for the filter arguments syntax, it needs to
229 be escaped, so you get:
230 @example
231 text=this is a \'string\'\: may contain one, or more, special characters
232 @end example
233
234 A second level of escaping is required when embedding the filter
235 arguments in a filtergraph description, in order to escape all the
236 filtergraph special characters. Thus the example above becomes:
237 @example
238 drawtext=text=this is a \\\'string\\\'\\: may contain one\, or more\, special characters
239 @end example
240
241 Finally an additional level of escaping may be needed when writing the
242 filtergraph description in a shell command, which depends on the
243 escaping rules of the adopted shell. For example, assuming that
244 @code{\} is special and needs to be escaped with another @code{\}, the
245 previous string will finally result in:
246 @example
247 -vf "drawtext=text=this is a \\\\\\'string\\\\\\'\\\\: may contain one\\, or more\\, special characters"
248 @end example
249
250 Sometimes, it might be more convenient to employ quoting in place of
251 escaping. For example the string:
252 @example
253 Caesar: tu quoque, Brute, fili mi
254 @end example
255
256 Can be quoted in the filter arguments as:
257 @example
258 text='Caesar: tu quoque, Brute, fili mi'
259 @end example
260
261 And finally inserted in a filtergraph like:
262 @example
263 drawtext=text=\'Caesar: tu quoque\, Brute\, fili mi\'
264 @end example
265
266 See the ``Quoting and escaping'' section in the ffmpeg-utils manual
267 for more information about the escaping and quoting rules adopted by
268 FFmpeg.
269
270 @c man end FILTERGRAPH DESCRIPTION
271
272 @chapter Audio Filters
273 @c man begin AUDIO FILTERS
274
275 When you configure your FFmpeg build, you can disable any of the
276 existing filters using @code{--disable-filters}.
277 The configure output will show the audio filters included in your
278 build.
279
280 Below is a description of the currently available audio filters.
281
282 @section aconvert
283
284 Convert the input audio format to the specified formats.
285
286 @emph{This filter is deprecated. Use @ref{aformat} instead.}
287
288 The filter accepts a string of the form:
289 "@var{sample_format}:@var{channel_layout}".
290
291 @var{sample_format} specifies the sample format, and can be a string or the
292 corresponding numeric value defined in @file{libavutil/samplefmt.h}. Use 'p'
293 suffix for a planar sample format.
294
295 @var{channel_layout} specifies the channel layout, and can be a string
296 or the corresponding number value defined in @file{libavutil/channel_layout.h}.
297
298 The special parameter "auto", signifies that the filter will
299 automatically select the output format depending on the output filter.
300
301 @subsection Examples
302
303 @itemize
304 @item
305 Convert input to float, planar, stereo:
306 @example
307 aconvert=fltp:stereo
308 @end example
309
310 @item
311 Convert input to unsigned 8-bit, automatically select out channel layout:
312 @example
313 aconvert=u8:auto
314 @end example
315 @end itemize
316
317 @section allpass
318
319 Apply a two-pole all-pass filter with central frequency (in Hz)
320 @var{frequency}, and filter-width @var{width}.
321 An all-pass filter changes the audio's frequency to phase relationship
322 without changing its frequency to amplitude relationship.
323
324 The filter accepts the following options:
325
326 @table @option
327 @item frequency, f
328 Set frequency in Hz.
329
330 @item width_type
331 Set method to specify band-width of filter.
332 @table @option
333 @item h
334 Hz
335 @item q
336 Q-Factor
337 @item o
338 octave
339 @item s
340 slope
341 @end table
342
343 @item width, w
344 Specify the band-width of a filter in width_type units.
345 @end table
346
347 @section highpass
348
349 Apply a high-pass filter with 3dB point frequency.
350 The filter can be either single-pole, or double-pole (the default).
351 The filter roll off at 6dB per pole per octave (20dB per pole per decade).
352
353 The filter accepts the following options:
354
355 @table @option
356 @item frequency, f
357 Set frequency in Hz. Default is 3000.
358
359 @item poles, p
360 Set number of poles. Default is 2.
361
362 @item width_type
363 Set method to specify band-width of filter.
364 @table @option
365 @item h
366 Hz
367 @item q
368 Q-Factor
369 @item o
370 octave
371 @item s
372 slope
373 @end table
374
375 @item width, w
376 Specify the band-width of a filter in width_type units.
377 Applies only to double-pole filter.
378 The default is 0.707q and gives a Butterworth response.
379 @end table
380
381 @section lowpass
382
383 Apply a low-pass filter with 3dB point frequency.
384 The filter can be either single-pole or double-pole (the default).
385 The filter roll off at 6dB per pole per octave (20dB per pole per decade).
386
387 The filter accepts the following options:
388
389 @table @option
390 @item frequency, f
391 Set frequency in Hz. Default is 500.
392
393 @item poles, p
394 Set number of poles. Default is 2.
395
396 @item width_type
397 Set method to specify band-width of filter.
398 @table @option
399 @item h
400 Hz
401 @item q
402 Q-Factor
403 @item o
404 octave
405 @item s
406 slope
407 @end table
408
409 @item width, w
410 Specify the band-width of a filter in width_type units.
411 Applies only to double-pole filter.
412 The default is 0.707q and gives a Butterworth response.
413 @end table
414
415 @section bass
416
417 Boost or cut the bass (lower) frequencies of the audio using a two-pole
418 shelving filter with a response similar to that of a standard
419 hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
420
421 The filter accepts the following options:
422
423 @table @option
424 @item gain, g
425 Give the gain at 0 Hz. Its useful range is about -20
426 (for a large cut) to +20 (for a large boost).
427 Beware of clipping when using a positive gain.
428
429 @item frequency, f
430 Set the filter's central frequency and so can be used
431 to extend or reduce the frequency range to be boosted or cut.
432 The default value is @code{100} Hz.
433
434 @item width_type
435 Set method to specify band-width of filter.
436 @table @option
437 @item h
438 Hz
439 @item q
440 Q-Factor
441 @item o
442 octave
443 @item s
444 slope
445 @end table
446
447 @item width, w
448 Determine how steep is the filter's shelf transition.
449 @end table
450
451 @section treble
452
453 Boost or cut treble (upper) frequencies of the audio using a two-pole
454 shelving filter with a response similar to that of a standard
455 hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
456
457 The filter accepts the following options:
458
459 @table @option
460 @item gain, g
461 Give the gain at whichever is the lower of ~22 kHz and the
462 Nyquist frequency. Its useful range is about -20 (for a large cut)
463 to +20 (for a large boost). Beware of clipping when using a positive gain.
464
465 @item frequency, f
466 Set the filter's central frequency and so can be used
467 to extend or reduce the frequency range to be boosted or cut.
468 The default value is @code{3000} Hz.
469
470 @item width_type
471 Set method to specify band-width of filter.
472 @table @option
473 @item h
474 Hz
475 @item q
476 Q-Factor
477 @item o
478 octave
479 @item s
480 slope
481 @end table
482
483 @item width, w
484 Determine how steep is the filter's shelf transition.
485 @end table
486
487 @section bandpass
488
489 Apply a two-pole Butterworth band-pass filter with central
490 frequency @var{frequency}, and (3dB-point) band-width width.
491 The @var{csg} option selects a constant skirt gain (peak gain = Q)
492 instead of the default: constant 0dB peak gain.
493 The filter roll off at 6dB per octave (20dB per decade).
494
495 The filter accepts the following options:
496
497 @table @option
498 @item frequency, f
499 Set the filter's central frequency. Default is @code{3000}.
500
501 @item csg
502 Constant skirt gain if set to 1. Defaults to 0.
503
504 @item width_type
505 Set method to specify band-width of filter.
506 @table @option
507 @item h
508 Hz
509 @item q
510 Q-Factor
511 @item o
512 octave
513 @item s
514 slope
515 @end table
516
517 @item width, w
518 Specify the band-width of a filter in width_type units.
519 @end table
520
521 @section bandreject
522
523 Apply a two-pole Butterworth band-reject filter with central
524 frequency @var{frequency}, and (3dB-point) band-width @var{width}.
525 The filter roll off at 6dB per octave (20dB per decade).
526
527 The filter accepts the following options:
528
529 @table @option
530 @item frequency, f
531 Set the filter's central frequency. Default is @code{3000}.
532
533 @item width_type
534 Set method to specify band-width of filter.
535 @table @option
536 @item h
537 Hz
538 @item q
539 Q-Factor
540 @item o
541 octave
542 @item s
543 slope
544 @end table
545
546 @item width, w
547 Specify the band-width of a filter in width_type units.
548 @end table
549
550 @section biquad
551
552 Apply a biquad IIR filter with the given coefficients.
553 Where @var{b0}, @var{b1}, @var{b2} and @var{a0}, @var{a1}, @var{a2}
554 are the numerator and denominator coefficients respectively.
555
556 @section equalizer
557
558 Apply a two-pole peaking equalisation (EQ) filter. With this
559 filter, the signal-level at and around a selected frequency can
560 be increased or decreased, whilst (unlike bandpass and bandreject
561 filters) that at all other frequencies is unchanged.
562
563 In order to produce complex equalisation curves, this filter can
564 be given several times, each with a different central frequency.
565
566 The filter accepts the following options:
567
568 @table @option
569 @item frequency, f
570 Set the filter's central frequency in Hz.
571
572 @item width_type
573 Set method to specify band-width of filter.
574 @table @option
575 @item h
576 Hz
577 @item q
578 Q-Factor
579 @item o
580 octave
581 @item s
582 slope
583 @end table
584
585 @item width, w
586 Specify the band-width of a filter in width_type units.
587
588 @item gain, g
589 Set the required gain or attenuation in dB.
590 Beware of clipping when using a positive gain.
591 @end table
592
593 @section afade
594
595 Apply fade-in/out effect to input audio.
596
597 A description of the accepted parameters follows.
598
599 @table @option
600 @item type, t
601 Specify the effect type, can be either @code{in} for fade-in, or
602 @code{out} for a fade-out effect. Default is @code{in}.
603
604 @item start_sample, ss
605 Specify the number of the start sample for starting to apply the fade
606 effect. Default is 0.
607
608 @item nb_samples, ns
609 Specify the number of samples for which the fade effect has to last. At
610 the end of the fade-in effect the output audio will have the same
611 volume as the input audio, at the end of the fade-out transition
612 the output audio will be silence. Default is 44100.
613
614 @item start_time, st
615 Specify time in seconds for starting to apply the fade
616 effect. Default is 0.
617 If set this option is used instead of @var{start_sample} one.
618
619 @item duration, d
620 Specify the number of seconds for which the fade effect has to last. At
621 the end of the fade-in effect the output audio will have the same
622 volume as the input audio, at the end of the fade-out transition
623 the output audio will be silence. Default is 0.
624 If set this option is used instead of @var{nb_samples} one.
625
626 @item curve
627 Set curve for fade transition.
628
629 It accepts the following values:
630 @table @option
631 @item tri
632 select triangular, linear slope (default)
633 @item qsin
634 select quarter of sine wave
635 @item hsin
636 select half of sine wave
637 @item esin
638 select exponential sine wave
639 @item log
640 select logarithmic
641 @item par
642 select inverted parabola
643 @item qua
644 select quadratic
645 @item cub
646 select cubic
647 @item squ
648 select square root
649 @item cbr
650 select cubic root
651 @end table
652 @end table
653
654 @subsection Examples
655
656 @itemize
657 @item
658 Fade in first 15 seconds of audio:
659 @example
660 afade=t=in:ss=0:d=15
661 @end example
662
663 @item
664 Fade out last 25 seconds of a 900 seconds audio:
665 @example
666 afade=t=out:ss=875:d=25
667 @end example
668 @end itemize
669
670 @anchor{aformat}
671 @section aformat
672
673 Set output format constraints for the input audio. The framework will
674 negotiate the most appropriate format to minimize conversions.
675
676 The filter accepts the following named parameters:
677 @table @option
678
679 @item sample_fmts
680 A '|'-separated list of requested sample formats.
681
682 @item sample_rates
683 A '|'-separated list of requested sample rates.
684
685 @item channel_layouts
686 A '|'-separated list of requested channel layouts.
687
688 @end table
689
690 If a parameter is omitted, all values are allowed.
691
692 For example to force the output to either unsigned 8-bit or signed 16-bit stereo:
693 @example
694 aformat=sample_fmts=u8|s16:channel_layouts=stereo
695 @end example
696
697 @section amerge
698
699 Merge two or more audio streams into a single multi-channel stream.
700
701 The filter accepts the following options:
702
703 @table @option
704
705 @item inputs
706 Set the number of inputs. Default is 2.
707
708 @end table
709
710 If the channel layouts of the inputs are disjoint, and therefore compatible,
711 the channel layout of the output will be set accordingly and the channels
712 will be reordered as necessary. If the channel layouts of the inputs are not
713 disjoint, the output will have all the channels of the first input then all
714 the channels of the second input, in that order, and the channel layout of
715 the output will be the default value corresponding to the total number of
716 channels.
717
718 For example, if the first input is in 2.1 (FL+FR+LF) and the second input
719 is FC+BL+BR, then the output will be in 5.1, with the channels in the
720 following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the
721 first input, b1 is the first channel of the second input).
722
723 On the other hand, if both input are in stereo, the output channels will be
724 in the default order: a1, a2, b1, b2, and the channel layout will be
725 arbitrarily set to 4.0, which may or may not be the expected value.
726
727 All inputs must have the same sample rate, and format.
728
729 If inputs do not have the same duration, the output will stop with the
730 shortest.
731
732 @subsection Examples
733
734 @itemize
735 @item
736 Merge two mono files into a stereo stream:
737 @example
738 amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge
739 @end example
740
741 @item
742 Multiple merges assuming 1 video stream and 6 audio streams in @file{input.mkv}:
743 @example
744 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
745 @end example
746 @end itemize
747
748 @section amix
749
750 Mixes multiple audio inputs into a single output.
751
752 For example
753 @example
754 ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT
755 @end example
756 will mix 3 input audio streams to a single output with the same duration as the
757 first input and a dropout transition time of 3 seconds.
758
759 The filter accepts the following named parameters:
760 @table @option
761
762 @item inputs
763 Number of inputs. If unspecified, it defaults to 2.
764
765 @item duration
766 How to determine the end-of-stream.
767 @table @option
768
769 @item longest
770 Duration of longest input. (default)
771
772 @item shortest
773 Duration of shortest input.
774
775 @item first
776 Duration of first input.
777
778 @end table
779
780 @item dropout_transition
781 Transition time, in seconds, for volume renormalization when an input
782 stream ends. The default value is 2 seconds.
783
784 @end table
785
786 @section anull
787
788 Pass the audio source unchanged to the output.
789
790 @section apad
791
792 Pad the end of a audio stream with silence, this can be used together with
793 -shortest to extend audio streams to the same length as the video stream.
794
795 @section aphaser
796 Add a phasing effect to the input audio.
797
798 A phaser filter creates series of peaks and troughs in the frequency spectrum.
799 The position of the peaks and troughs are modulated so that they vary over time, creating a sweeping effect.
800
801 A description of the accepted parameters follows.
802
803 @table @option
804 @item in_gain
805 Set input gain. Default is 0.4.
806
807 @item out_gain
808 Set output gain. Default is 0.74
809
810 @item delay
811 Set delay in milliseconds. Default is 3.0.
812
813 @item decay
814 Set decay. Default is 0.4.
815
816 @item speed
817 Set modulation speed in Hz. Default is 0.5.
818
819 @item type
820 Set modulation type. Default is triangular.
821
822 It accepts the following values:
823 @table @samp
824 @item triangular, t
825 @item sinusoidal, s
826 @end table
827 @end table
828
829 @anchor{aresample}
830 @section aresample
831
832 Resample the input audio to the specified parameters, using the
833 libswresample library. If none are specified then the filter will
834 automatically convert between its input and output.
835
836 This filter is also able to stretch/squeeze the audio data to make it match
837 the timestamps or to inject silence / cut out audio to make it match the
838 timestamps, do a combination of both or do neither.
839
840 The filter accepts the syntax
841 [@var{sample_rate}:]@var{resampler_options}, where @var{sample_rate}
842 expresses a sample rate and @var{resampler_options} is a list of
843 @var{key}=@var{value} pairs, separated by ":". See the
844 ffmpeg-resampler manual for the complete list of supported options.
845
846 @subsection Examples
847
848 @itemize
849 @item
850 Resample the input audio to 44100Hz:
851 @example
852 aresample=44100
853 @end example
854
855 @item
856 Stretch/squeeze samples to the given timestamps, with a maximum of 1000
857 samples per second compensation:
858 @example
859 aresample=async=1000
860 @end example
861 @end itemize
862
863 @section asetnsamples
864
865 Set the number of samples per each output audio frame.
866
867 The last output packet may contain a different number of samples, as
868 the filter will flush all the remaining samples when the input audio
869 signal its end.
870
871 The filter accepts the following options:
872
873 @table @option
874
875 @item nb_out_samples, n
876 Set the number of frames per each output audio frame. The number is
877 intended as the number of samples @emph{per each channel}.
878 Default value is 1024.
879
880 @item pad, p
881 If set to 1, the filter will pad the last audio frame with zeroes, so
882 that the last frame will contain the same number of samples as the
883 previous ones. Default value is 1.
884 @end table
885
886 For example, to set the number of per-frame samples to 1234 and
887 disable padding for the last frame, use:
888 @example
889 asetnsamples=n=1234:p=0
890 @end example
891
892 @section ashowinfo
893
894 Show a line containing various information for each input audio frame.
895 The input audio is not modified.
896
897 The shown line contains a sequence of key/value pairs of the form
898 @var{key}:@var{value}.
899
900 A description of each shown parameter follows:
901
902 @table @option
903 @item n
904 sequential number of the input frame, starting from 0
905
906 @item pts
907 Presentation timestamp of the input frame, in time base units; the time base
908 depends on the filter input pad, and is usually 1/@var{sample_rate}.
909
910 @item pts_time
911 presentation timestamp of the input frame in seconds
912
913 @item pos
914 position of the frame in the input stream, -1 if this information in
915 unavailable and/or meaningless (for example in case of synthetic audio)
916
917 @item fmt
918 sample format
919
920 @item chlayout
921 channel layout
922
923 @item rate
924 sample rate for the audio frame
925
926 @item nb_samples
927 number of samples (per channel) in the frame
928
929 @item checksum
930 Adler-32 checksum (printed in hexadecimal) of the audio data. For planar audio
931 the data is treated as if all the planes were concatenated.
932
933 @item plane_checksums
934 A list of Adler-32 checksums for each data plane.
935 @end table
936
937 @section astreamsync
938
939 Forward two audio streams and control the order the buffers are forwarded.
940
941 The filter accepts the following options:
942
943 @table @option
944 @item expr, e
945 Set the expression deciding which stream should be
946 forwarded next: if the result is negative, the first stream is forwarded; if
947 the result is positive or zero, the second stream is forwarded. It can use
948 the following variables:
949
950 @table @var
951 @item b1 b2
952 number of buffers forwarded so far on each stream
953 @item s1 s2
954 number of samples forwarded so far on each stream
955 @item t1 t2
956 current timestamp of each stream
957 @end table
958
959 The default value is @code{t1-t2}, which means to always forward the stream
960 that has a smaller timestamp.
961 @end table
962
963 @subsection Examples
964
965 Stress-test @code{amerge} by randomly sending buffers on the wrong
966 input, while avoiding too much of a desynchronization:
967 @example
968 amovie=file.ogg [a] ; amovie=file.mp3 [b] ;
969 [a] [b] astreamsync=(2*random(1))-1+tanh(5*(t1-t2)) [a2] [b2] ;
970 [a2] [b2] amerge
971 @end example
972
973 @section atempo
974
975 Adjust audio tempo.
976
977 The filter accepts exactly one parameter, the audio tempo. If not
978 specified then the filter will assume nominal 1.0 tempo. Tempo must
979 be in the [0.5, 2.0] range.
980
981 @subsection Examples
982
983 @itemize
984 @item
985 Slow down audio to 80% tempo:
986 @example
987 atempo=0.8
988 @end example
989
990 @item
991 To speed up audio to 125% tempo:
992 @example
993 atempo=1.25
994 @end example
995 @end itemize
996
997 @section earwax
998
999 Make audio easier to listen to on headphones.
1000
1001 This filter adds `cues' to 44.1kHz stereo (i.e. audio CD format) audio
1002 so that when listened to on headphones the stereo image is moved from
1003 inside your head (standard for headphones) to outside and in front of
1004 the listener (standard for speakers).
1005
1006 Ported from SoX.
1007
1008 @section pan
1009
1010 Mix channels with specific gain levels. The filter accepts the output
1011 channel layout followed by a set of channels definitions.
1012
1013 This filter is also designed to remap efficiently the channels of an audio
1014 stream.
1015
1016 The filter accepts parameters of the form:
1017 "@var{l}:@var{outdef}:@var{outdef}:..."
1018
1019 @table @option
1020 @item l
1021 output channel layout or number of channels
1022
1023 @item outdef
1024 output channel specification, of the form:
1025 "@var{out_name}=[@var{gain}*]@var{in_name}[+[@var{gain}*]@var{in_name}...]"
1026
1027 @item out_name
1028 output channel to define, either a channel name (FL, FR, etc.) or a channel
1029 number (c0, c1, etc.)
1030
1031 @item gain
1032 multiplicative coefficient for the channel, 1 leaving the volume unchanged
1033
1034 @item in_name
1035 input channel to use, see out_name for details; it is not possible to mix
1036 named and numbered input channels
1037 @end table
1038
1039 If the `=' in a channel specification is replaced by `<', then the gains for
1040 that specification will be renormalized so that the total is 1, thus
1041 avoiding clipping noise.
1042
1043 @subsection Mixing examples
1044
1045 For example, if you want to down-mix from stereo to mono, but with a bigger
1046 factor for the left channel:
1047 @example
1048 pan=1:c0=0.9*c0+0.1*c1
1049 @end example
1050
1051 A customized down-mix to stereo that works automatically for 3-, 4-, 5- and
1052 7-channels surround:
1053 @example
1054 pan=stereo: FL < FL + 0.5*FC + 0.6*BL + 0.6*SL : FR < FR + 0.5*FC + 0.6*BR + 0.6*SR
1055 @end example
1056
1057 Note that @command{ffmpeg} integrates a default down-mix (and up-mix) system
1058 that should be preferred (see "-ac" option) unless you have very specific
1059 needs.
1060
1061 @subsection Remapping examples
1062
1063 The channel remapping will be effective if, and only if:
1064
1065 @itemize
1066 @item gain coefficients are zeroes or ones,
1067 @item only one input per channel output,
1068 @end itemize
1069
1070 If all these conditions are satisfied, the filter will notify the user ("Pure
1071 channel mapping detected"), and use an optimized and lossless method to do the
1072 remapping.
1073
1074 For example, if you have a 5.1 source and want a stereo audio stream by
1075 dropping the extra channels:
1076 @example
1077 pan="stereo: c0=FL : c1=FR"
1078 @end example
1079
1080 Given the same source, you can also switch front left and front right channels
1081 and keep the input channel layout:
1082 @example
1083 pan="5.1: c0=c1 : c1=c0 : c2=c2 : c3=c3 : c4=c4 : c5=c5"
1084 @end example
1085
1086 If the input is a stereo audio stream, you can mute the front left channel (and
1087 still keep the stereo channel layout) with:
1088 @example
1089 pan="stereo:c1=c1"
1090 @end example
1091
1092 Still with a stereo audio stream input, you can copy the right channel in both
1093 front left and right:
1094 @example
1095 pan="stereo: c0=FR : c1=FR"
1096 @end example
1097
1098 @section silencedetect
1099
1100 Detect silence in an audio stream.
1101
1102 This filter logs a message when it detects that the input audio volume is less
1103 or equal to a noise tolerance value for a duration greater or equal to the
1104 minimum detected noise duration.
1105
1106 The printed times and duration are expressed in seconds.
1107
1108 The filter accepts the following options:
1109
1110 @table @option
1111 @item duration, d
1112 Set silence duration until notification (default is 2 seconds).
1113
1114 @item noise, n
1115 Set noise tolerance. Can be specified in dB (in case "dB" is appended to the
1116 specified value) or amplitude ratio. Default is -60dB, or 0.001.
1117 @end table
1118
1119 @subsection Examples
1120
1121 @itemize
1122 @item
1123 Detect 5 seconds of silence with -50dB noise tolerance:
1124 @example
1125 silencedetect=n=-50dB:d=5
1126 @end example
1127
1128 @item
1129 Complete example with @command{ffmpeg} to detect silence with 0.0001 noise
1130 tolerance in @file{silence.mp3}:
1131 @example
1132 ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null -
1133 @end example
1134 @end itemize
1135
1136 @section asyncts
1137 Synchronize audio data with timestamps by squeezing/stretching it and/or
1138 dropping samples/adding silence when needed.
1139
1140 This filter is not built by default, please use @ref{aresample} to do squeezing/stretching.
1141
1142 The filter accepts the following named parameters:
1143 @table @option
1144
1145 @item compensate
1146 Enable stretching/squeezing the data to make it match the timestamps. Disabled
1147 by default. When disabled, time gaps are covered with silence.
1148
1149 @item min_delta
1150 Minimum difference between timestamps and audio data (in seconds) to trigger
1151 adding/dropping samples. Default value is 0.1. If you get non-perfect sync with
1152 this filter, try setting this parameter to 0.
1153
1154 @item max_comp
1155 Maximum compensation in samples per second. Relevant only with compensate=1.
1156 Default value 500.
1157
1158 @item first_pts
1159 Assume the first pts should be this value. The time base is 1 / sample rate.
1160 This allows for padding/trimming at the start of stream. By default, no
1161 assumption is made about the first frame's expected pts, so no padding or
1162 trimming is done. For example, this could be set to 0 to pad the beginning with
1163 silence if an audio stream starts after the video stream or to trim any samples
1164 with a negative pts due to encoder delay.
1165
1166 @end table
1167
1168 @section channelsplit
1169 Split each channel in input audio stream into a separate output stream.
1170
1171 This filter accepts the following named parameters:
1172 @table @option
1173 @item channel_layout
1174 Channel layout of the input stream. Default is "stereo".
1175 @end table
1176
1177 For example, assuming a stereo input MP3 file
1178 @example
1179 ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv
1180 @end example
1181 will create an output Matroska file with two audio streams, one containing only
1182 the left channel and the other the right channel.
1183
1184 To split a 5.1 WAV file into per-channel files
1185 @example
1186 ffmpeg -i in.wav -filter_complex
1187 'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]'
1188 -map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]'
1189 front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]'
1190 side_right.wav
1191 @end example
1192
1193 @section channelmap
1194 Remap input channels to new locations.
1195
1196 This filter accepts the following named parameters:
1197 @table @option
1198 @item channel_layout
1199 Channel layout of the output stream.
1200
1201 @item map
1202 Map channels from input to output. The argument is a '|'-separated list of
1203 mappings, each in the @code{@var{in_channel}-@var{out_channel}} or
1204 @var{in_channel} form. @var{in_channel} can be either the name of the input
1205 channel (e.g. FL for front left) or its index in the input channel layout.
1206 @var{out_channel} is the name of the output channel or its index in the output
1207 channel layout. If @var{out_channel} is not given then it is implicitly an
1208 index, starting with zero and increasing by one for each mapping.
1209 @end table
1210
1211 If no mapping is present, the filter will implicitly map input channels to
1212 output channels preserving index.
1213
1214 For example, assuming a 5.1+downmix input MOV file
1215 @example
1216 ffmpeg -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav
1217 @end example
1218 will create an output WAV file tagged as stereo from the downmix channels of
1219 the input.
1220
1221 To fix a 5.1 WAV improperly encoded in AAC's native channel order
1222 @example
1223 ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:channel_layout=5.1' out.wav
1224 @end example
1225
1226 @section join
1227 Join multiple input streams into one multi-channel stream.
1228
1229 The filter accepts the following named parameters:
1230 @table @option
1231
1232 @item inputs
1233 Number of input streams. Defaults to 2.
1234
1235 @item channel_layout
1236 Desired output channel layout. Defaults to stereo.
1237
1238 @item map
1239 Map channels from inputs to output. The argument is a '|'-separated list of
1240 mappings, each in the @code{@var{input_idx}.@var{in_channel}-@var{out_channel}}
1241 form. @var{input_idx} is the 0-based index of the input stream. @var{in_channel}
1242 can be either the name of the input channel (e.g. FL for front left) or its
1243 index in the specified input stream. @var{out_channel} is the name of the output
1244 channel.
1245 @end table
1246
1247 The filter will attempt to guess the mappings when those are not specified
1248 explicitly. It does so by first trying to find an unused matching input channel
1249 and if that fails it picks the first unused input channel.
1250
1251 E.g. to join 3 inputs (with properly set channel layouts)
1252 @example
1253 ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT
1254 @end example
1255
1256 To build a 5.1 output from 6 single-channel streams:
1257 @example
1258 ffmpeg -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex
1259 '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'
1260 out
1261 @end example
1262
1263 @section resample
1264 Convert the audio sample format, sample rate and channel layout. This filter is
1265 not meant to be used directly.
1266
1267 @section volume
1268
1269 Adjust the input audio volume.
1270
1271 The filter accepts the following options:
1272
1273 @table @option
1274
1275 @item volume
1276 Expresses how the audio volume will be increased or decreased.
1277
1278 Output values are clipped to the maximum value.
1279
1280 The output audio volume is given by the relation:
1281 @example
1282 @var{output_volume} = @var{volume} * @var{input_volume}
1283 @end example
1284
1285 Default value for @var{volume} is 1.0.
1286
1287 @item precision
1288 Set the mathematical precision.
1289
1290 This determines which input sample formats will be allowed, which affects the
1291 precision of the volume scaling.
1292
1293 @table @option
1294 @item fixed
1295 8-bit fixed-point; limits input sample format to U8, S16, and S32.
1296 @item float
1297 32-bit floating-point; limits input sample format to FLT. (default)
1298 @item double
1299 64-bit floating-point; limits input sample format to DBL.
1300 @end table
1301 @end table
1302
1303 @subsection Examples
1304
1305 @itemize
1306 @item
1307 Halve the input audio volume:
1308 @example
1309 volume=volume=0.5
1310 volume=volume=1/2
1311 volume=volume=-6.0206dB
1312 @end example
1313
1314 In all the above example the named key for @option{volume} can be
1315 omitted, for example like in:
1316 @example
1317 volume=0.5
1318 @end example
1319
1320 @item
1321 Increase input audio power by 6 decibels using fixed-point precision:
1322 @example
1323 volume=volume=6dB:precision=fixed
1324 @end example
1325 @end itemize
1326
1327 @section volumedetect
1328
1329 Detect the volume of the input video.
1330
1331 The filter has no parameters. The input is not modified. Statistics about
1332 the volume will be printed in the log when the input stream end is reached.
1333
1334 In particular it will show the mean volume (root mean square), maximum
1335 volume (on a per-sample basis), and the beginning of an histogram of the
1336 registered volume values (from the maximum value to a cumulated 1/1000 of
1337 the samples).
1338
1339 All volumes are in decibels relative to the maximum PCM value.
1340
1341 @subsection Examples
1342
1343 Here is an excerpt of the output:
1344 @example
1345 [Parsed_volumedetect_0 @ 0xa23120] mean_volume: -27 dB
1346 [Parsed_volumedetect_0 @ 0xa23120] max_volume: -4 dB
1347 [Parsed_volumedetect_0 @ 0xa23120] histogram_4db: 6
1348 [Parsed_volumedetect_0 @ 0xa23120] histogram_5db: 62
1349 [Parsed_volumedetect_0 @ 0xa23120] histogram_6db: 286
1350 [Parsed_volumedetect_0 @ 0xa23120] histogram_7db: 1042
1351 [Parsed_volumedetect_0 @ 0xa23120] histogram_8db: 2551
1352 [Parsed_volumedetect_0 @ 0xa23120] histogram_9db: 4609
1353 [Parsed_volumedetect_0 @ 0xa23120] histogram_10db: 8409
1354 @end example
1355
1356 It means that:
1357 @itemize
1358 @item
1359 The mean square energy is approximately -27 dB, or 10^-2.7.
1360 @item
1361 The largest sample is at -4 dB, or more precisely between -4 dB and -5 dB.
1362 @item
1363 There are 6 samples at -4 dB, 62 at -5 dB, 286 at -6 dB, etc.
1364 @end itemize
1365
1366 In other words, raising the volume by +4 dB does not cause any clipping,
1367 raising it by +5 dB causes clipping for 6 samples, etc.
1368
1369 @c man end AUDIO FILTERS
1370
1371 @chapter Audio Sources
1372 @c man begin AUDIO SOURCES
1373
1374 Below is a description of the currently available audio sources.
1375
1376 @section abuffer
1377
1378 Buffer audio frames, and make them available to the filter chain.
1379
1380 This source is mainly intended for a programmatic use, in particular
1381 through the interface defined in @file{libavfilter/asrc_abuffer.h}.
1382
1383 It accepts the following named parameters:
1384
1385 @table @option
1386
1387 @item time_base
1388 Timebase which will be used for timestamps of submitted frames. It must be
1389 either a floating-point number or in @var{numerator}/@var{denominator} form.
1390
1391 @item sample_rate
1392 The sample rate of the incoming audio buffers.
1393
1394 @item sample_fmt
1395 The sample format of the incoming audio buffers.
1396 Either a sample format name or its corresponging integer representation from
1397 the enum AVSampleFormat in @file{libavutil/samplefmt.h}
1398
1399 @item channel_layout
1400 The channel layout of the incoming audio buffers.
1401 Either a channel layout name from channel_layout_map in
1402 @file{libavutil/channel_layout.c} or its corresponding integer representation
1403 from the AV_CH_LAYOUT_* macros in @file{libavutil/channel_layout.h}
1404
1405 @item channels
1406 The number of channels of the incoming audio buffers.
1407 If both @var{channels} and @var{channel_layout} are specified, then they
1408 must be consistent.
1409
1410 @end table
1411
1412 @subsection Examples
1413
1414 @example
1415 abuffer=sample_rate=44100:sample_fmt=s16p:channel_layout=stereo
1416 @end example
1417
1418 will instruct the source to accept planar 16bit signed stereo at 44100Hz.
1419 Since the sample format with name "s16p" corresponds to the number
1420 6 and the "stereo" channel layout corresponds to the value 0x3, this is
1421 equivalent to:
1422 @example
1423 abuffer=sample_rate=44100:sample_fmt=6:channel_layout=0x3
1424 @end example
1425
1426 @section aevalsrc
1427
1428 Generate an audio signal specified by an expression.
1429
1430 This source accepts in input one or more expressions (one for each
1431 channel), which are evaluated and used to generate a corresponding
1432 audio signal.
1433
1434 This source accepts the following options:
1435
1436 @table @option
1437 @item exprs
1438 Set the '|'-separated expressions list for each separate channel. In case the
1439 @option{channel_layout} option is not specified, the selected channel layout
1440 depends on the number of provided expressions.
1441
1442 @item channel_layout, c
1443 Set the channel layout. The number of channels in the specified layout
1444 must be equal to the number of specified expressions.
1445
1446 @item duration, d
1447 Set the minimum duration of the sourced audio. See the function
1448 @code{av_parse_time()} for the accepted format.
1449 Note that the resulting duration may be greater than the specified
1450 duration, as the generated audio is always cut at the end of a
1451 complete frame.
1452
1453 If not specified, or the expressed duration is negative, the audio is
1454 supposed to be generated forever.
1455
1456 @item nb_samples, n
1457 Set the number of samples per channel per each output frame,
1458 default to 1024.
1459
1460 @item sample_rate, s
1461 Specify the sample rate, default to 44100.
1462 @end table
1463
1464 Each expression in @var{exprs} can contain the following constants:
1465
1466 @table @option
1467 @item n
1468 number of the evaluated sample, starting from 0
1469
1470 @item t
1471 time of the evaluated sample expressed in seconds, starting from 0
1472
1473 @item s
1474 sample rate
1475
1476 @end table
1477
1478 @subsection Examples
1479
1480 @itemize
1481 @item
1482 Generate silence:
1483 @example
1484 aevalsrc=0
1485 @end example
1486
1487 @item
1488 Generate a sin signal with frequency of 440 Hz, set sample rate to
1489 8000 Hz:
1490 @example
1491 aevalsrc="sin(440*2*PI*t):s=8000"
1492 @end example
1493
1494 @item
1495 Generate a two channels signal, specify the channel layout (Front
1496 Center + Back Center) explicitly:
1497 @example
1498 aevalsrc="sin(420*2*PI*t)|cos(430*2*PI*t):c=FC|BC"
1499 @end example
1500
1501 @item
1502 Generate white noise:
1503 @example
1504 aevalsrc="-2+random(0)"
1505 @end example
1506
1507 @item
1508 Generate an amplitude modulated signal:
1509 @example
1510 aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)"
1511 @end example
1512
1513 @item
1514 Generate 2.5 Hz binaural beats on a 360 Hz carrier:
1515 @example
1516 aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) | 0.1*sin(2*PI*(360+2.5/2)*t)"
1517 @end example
1518
1519 @end itemize
1520
1521 @section anullsrc
1522
1523 Null audio source, return unprocessed audio frames. It is mainly useful
1524 as a template and to be employed in analysis / debugging tools, or as
1525 the source for filters which ignore the input data (for example the sox
1526 synth filter).
1527
1528 This source accepts the following options:
1529
1530 @table @option
1531
1532 @item channel_layout, cl
1533
1534 Specify the channel layout, and can be either an integer or a string
1535 representing a channel layout. The default value of @var{channel_layout}
1536 is "stereo".
1537
1538 Check the channel_layout_map definition in
1539 @file{libavutil/channel_layout.c} for the mapping between strings and
1540 channel layout values.
1541
1542 @item sample_rate, r
1543 Specify the sample rate, and defaults to 44100.
1544
1545 @item nb_samples, n
1546 Set the number of samples per requested frames.
1547
1548 @end table
1549
1550 @subsection Examples
1551
1552 @itemize
1553 @item
1554 Set the sample rate to 48000 Hz and the channel layout to AV_CH_LAYOUT_MONO.
1555 @example
1556 anullsrc=r=48000:cl=4
1557 @end example
1558
1559 @item
1560 Do the same operation with a more obvious syntax:
1561 @example
1562 anullsrc=r=48000:cl=mono
1563 @end example
1564 @end itemize
1565
1566 @section abuffer
1567 Buffer audio frames, and make them available to the filter chain.
1568
1569 This source is not intended to be part of user-supplied graph descriptions but
1570 for insertion by calling programs through the interface defined in
1571 @file{libavfilter/buffersrc.h}.
1572
1573 It accepts the following named parameters:
1574 @table @option
1575
1576 @item time_base
1577 Timebase which will be used for timestamps of submitted frames. It must be
1578 either a floating-point number or in @var{numerator}/@var{denominator} form.
1579
1580 @item sample_rate
1581 Audio sample rate.
1582
1583 @item sample_fmt
1584 Name of the sample format, as returned by @code{av_get_sample_fmt_name()}.
1585
1586 @item channel_layout
1587 Channel layout of the audio data, in the form that can be accepted by
1588 @code{av_get_channel_layout()}.
1589 @end table
1590
1591 All the parameters need to be explicitly defined.
1592
1593 @section flite
1594
1595 Synthesize a voice utterance using the libflite library.
1596
1597 To enable compilation of this filter you need to configure FFmpeg with
1598 @code{--enable-libflite}.
1599
1600 Note that the flite library is not thread-safe.
1601
1602 The filter accepts the following options:
1603
1604 @table @option
1605
1606 @item list_voices
1607 If set to 1, list the names of the available voices and exit
1608 immediately. Default value is 0.
1609
1610 @item nb_samples, n
1611 Set the maximum number of samples per frame. Default value is 512.
1612
1613 @item textfile
1614 Set the filename containing the text to speak.
1615
1616 @item text
1617 Set the text to speak.
1618
1619 @item voice, v
1620 Set the voice to use for the speech synthesis. Default value is
1621 @code{kal}. See also the @var{list_voices} option.
1622 @end table
1623
1624 @subsection Examples
1625
1626 @itemize
1627 @item
1628 Read from file @file{speech.txt}, and synthetize the text using the
1629 standard flite voice:
1630 @example
1631 flite=textfile=speech.txt
1632 @end example
1633
1634 @item
1635 Read the specified text selecting the @code{slt} voice:
1636 @example
1637 flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
1638 @end example
1639
1640 @item
1641 Input text to ffmpeg:
1642 @example
1643 ffmpeg -f lavfi -i flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
1644 @end example
1645
1646 @item
1647 Make @file{ffplay} speak the specified text, using @code{flite} and
1648 the @code{lavfi} device:
1649 @example
1650 ffplay -f lavfi flite=text='No more be grieved for which that thou hast done.'
1651 @end example
1652 @end itemize
1653
1654 For more information about libflite, check:
1655 @url{http://www.speech.cs.cmu.edu/flite/}
1656
1657 @section sine
1658
1659 Generate an audio signal made of a sine wave with amplitude 1/8.
1660
1661 The audio signal is bit-exact.
1662
1663 The filter accepts the following options:
1664
1665 @table @option
1666
1667 @item frequency, f
1668 Set the carrier frequency. Default is 440 Hz.
1669
1670 @item beep_factor, b
1671 Enable a periodic beep every second with frequency @var{beep_factor} times
1672 the carrier frequency. Default is 0, meaning the beep is disabled.
1673
1674 @item sample_rate, s
1675 Specify the sample rate, default is 44100.
1676
1677 @item duration, d
1678 Specify the duration of the generated audio stream.
1679
1680 @item samples_per_frame
1681 Set the number of samples per output frame, default is 1024.
1682 @end table
1683
1684 @subsection Examples
1685
1686 @itemize
1687
1688 @item
1689 Generate a simple 440 Hz sine wave:
1690 @example
1691 sine
1692 @end example
1693
1694 @item
1695 Generate a 220 Hz sine wave with a 880 Hz beep each second, for 5 seconds:
1696 @example
1697 sine=220:4:d=5
1698 sine=f=220:b=4:d=5
1699 sine=frequency=220:beep_factor=4:duration=5
1700 @end example
1701
1702 @end itemize
1703
1704 @c man end AUDIO SOURCES
1705
1706 @chapter Audio Sinks
1707 @c man begin AUDIO SINKS
1708
1709 Below is a description of the currently available audio sinks.
1710
1711 @section abuffersink
1712
1713 Buffer audio frames, and make them available to the end of filter chain.
1714
1715 This sink is mainly intended for programmatic use, in particular
1716 through the interface defined in @file{libavfilter/buffersink.h}
1717 or the options system.
1718
1719 It accepts a pointer to an AVABufferSinkContext structure, which
1720 defines the incoming buffers' formats, to be passed as the opaque
1721 parameter to @code{avfilter_init_filter} for initialization.
1722
1723 @section anullsink
1724
1725 Null audio sink, do absolutely nothing with the input audio. It is
1726 mainly useful as a template and to be employed in analysis / debugging
1727 tools.
1728
1729 @c man end AUDIO SINKS
1730
1731 @chapter Video Filters
1732 @c man begin VIDEO FILTERS
1733
1734 When you configure your FFmpeg build, you can disable any of the
1735 existing filters using @code{--disable-filters}.
1736 The configure output will show the video filters included in your
1737 build.
1738
1739 Below is a description of the currently available video filters.
1740
1741 @section alphaextract
1742
1743 Extract the alpha component from the input as a grayscale video. This
1744 is especially useful with the @var{alphamerge} filter.
1745
1746 @section alphamerge
1747
1748 Add or replace the alpha component of the primary input with the
1749 grayscale value of a second input. This is intended for use with
1750 @var{alphaextract} to allow the transmission or storage of frame
1751 sequences that have alpha in a format that doesn't support an alpha
1752 channel.
1753
1754 For example, to reconstruct full frames from a normal YUV-encoded video
1755 and a separate video created with @var{alphaextract}, you might use:
1756 @example
1757 movie=in_alpha.mkv [alpha]; [in][alpha] alphamerge [out]
1758 @end example
1759
1760 Since this filter is designed for reconstruction, it operates on frame
1761 sequences without considering timestamps, and terminates when either
1762 input reaches end of stream. This will cause problems if your encoding
1763 pipeline drops frames. If you're trying to apply an image as an
1764 overlay to a video stream, consider the @var{overlay} filter instead.
1765
1766 @section ass
1767
1768 Same as the @ref{subtitles} filter, except that it doesn't require libavcodec
1769 and libavformat to work. On the other hand, it is limited to ASS (Advanced
1770 Substation Alpha) subtitles files.
1771
1772 @section bbox
1773
1774 Compute the bounding box for the non-black pixels in the input frame
1775 luminance plane.
1776
1777 This filter computes the bounding box containing all the pixels with a
1778 luminance value greater than the minimum allowed value.
1779 The parameters describing the bounding box are printed on the filter
1780 log.
1781
1782 @section blackdetect
1783
1784 Detect video intervals that are (almost) completely black. Can be
1785 useful to detect chapter transitions, commercials, or invalid
1786 recordings. Output lines contains the time for the start, end and
1787 duration of the detected black interval expressed in seconds.
1788
1789 In order to display the output lines, you need to set the loglevel at
1790 least to the AV_LOG_INFO value.
1791
1792 The filter accepts the following options:
1793
1794 @table @option
1795 @item black_min_duration, d
1796 Set the minimum detected black duration expressed in seconds. It must
1797 be a non-negative floating point number.
1798
1799 Default value is 2.0.
1800
1801 @item picture_black_ratio_th, pic_th
1802 Set the threshold for considering a picture "black".
1803 Express the minimum value for the ratio:
1804 @example
1805 @var{nb_black_pixels} / @var{nb_pixels}
1806 @end example
1807
1808 for which a picture is considered black.
1809 Default value is 0.98.
1810
1811 @item pixel_black_th, pix_th
1812 Set the threshold for considering a pixel "black".
1813
1814 The threshold expresses the maximum pixel luminance value for which a
1815 pixel is considered "black". The provided value is scaled according to
1816 the following equation:
1817 @example
1818 @var{absolute_threshold} = @var{luminance_minimum_value} + @var{pixel_black_th} * @var{luminance_range_size}
1819 @end example
1820
1821 @var{luminance_range_size} and @var{luminance_minimum_value} depend on
1822 the input video format, the range is [0-255] for YUV full-range
1823 formats and [16-235] for YUV non full-range formats.
1824
1825 Default value is 0.10.
1826 @end table
1827
1828 The following example sets the maximum pixel threshold to the minimum
1829 value, and detects only black intervals of 2 or more seconds:
1830 @example
1831 blackdetect=d=2:pix_th=0.00
1832 @end example
1833
1834 @section blackframe
1835
1836 Detect frames that are (almost) completely black. Can be useful to
1837 detect chapter transitions or commercials. Output lines consist of
1838 the frame number of the detected frame, the percentage of blackness,
1839 the position in the file if known or -1 and the timestamp in seconds.
1840
1841 In order to display the output lines, you need to set the loglevel at
1842 least to the AV_LOG_INFO value.
1843
1844 The filter accepts the following options:
1845
1846 @table @option
1847
1848 @item amount
1849 Set the percentage of the pixels that have to be below the threshold, defaults
1850 to @code{98}.
1851
1852 @item threshold, thresh
1853 Set the threshold below which a pixel value is considered black, defaults to
1854 @code{32}.
1855
1856 @end table
1857
1858 @section blend
1859
1860 Blend two video frames into each other.
1861
1862 It takes two input streams and outputs one stream, the first input is the
1863 "top" layer and second input is "bottom" layer.
1864 Output terminates when shortest input terminates.
1865
1866 A description of the accepted options follows.
1867
1868 @table @option
1869 @item c0_mode
1870 @item c1_mode
1871 @item c2_mode
1872 @item c3_mode
1873 @item all_mode
1874 Set blend mode for specific pixel component or all pixel components in case
1875 of @var{all_mode}. Default value is @code{normal}.
1876
1877 Available values for component modes are:
1878 @table @samp
1879 @item addition
1880 @item and
1881 @item average
1882 @item burn
1883 @item darken
1884 @item difference
1885 @item divide
1886 @item dodge
1887 @item exclusion
1888 @item hardlight
1889 @item lighten
1890 @item multiply
1891 @item negation
1892 @item normal
1893 @item or
1894 @item overlay
1895 @item phoenix
1896 @item pinlight
1897 @item reflect
1898 @item screen
1899 @item softlight
1900 @item subtract
1901 @item vividlight
1902 @item xor
1903 @end table
1904
1905 @item c0_opacity
1906 @item c1_opacity
1907 @item c2_opacity
1908 @item c3_opacity
1909 @item all_opacity
1910 Set blend opacity for specific pixel component or all pixel components in case
1911 of @var{all_opacity}. Only used in combination with pixel component blend modes.
1912
1913 @item c0_expr
1914 @item c1_expr
1915 @item c2_expr
1916 @item c3_expr
1917 @item all_expr
1918 Set blend expression for specific pixel component or all pixel components in case
1919 of @var{all_expr}. Note that related mode options will be ignored if those are set.
1920
1921 The expressions can use the following variables:
1922
1923 @table @option
1924 @item N
1925 The sequential number of the filtered frame, starting from @code{0}.
1926
1927 @item X
1928 @item Y
1929 the coordinates of the current sample
1930
1931 @item W
1932 @item H
1933 the width and height of currently filtered plane
1934
1935 @item SW
1936 @item SH
1937 Width and height scale depending on the currently filtered plane. It is the
1938 ratio between the corresponding luma plane number of pixels and the current
1939 plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and
1940 @code{0.5,0.5} for chroma planes.
1941
1942 @item T
1943 Time of the current frame, expressed in seconds.
1944
1945 @item TOP, A
1946 Value of pixel component at current location for first video frame (top layer).
1947
1948 @item BOTTOM, B
1949 Value of pixel component at current location for second video frame (bottom layer).
1950 @end table
1951 @end table
1952
1953 @subsection Examples
1954
1955 @itemize
1956 @item
1957 Apply transition from bottom layer to top layer in first 10 seconds:
1958 @example
1959 blend=all_expr='A*(if(gte(T,10),1,T/10))+B*(1-(if(gte(T,10),1,T/10)))'
1960 @end example
1961
1962 @item
1963 Apply 1x1 checkerboard effect:
1964 @example
1965 blend=all_expr='if(eq(mod(X,2),mod(Y,2)),A,B)'
1966 @end example
1967 @end itemize
1968
1969 @section boxblur
1970
1971 Apply boxblur algorithm to the input video.
1972
1973 The filter accepts the following options:
1974
1975 @table @option
1976
1977 @item luma_radius, lr
1978 @item luma_power, lp
1979 @item chroma_radius, cr
1980 @item chroma_power, cp
1981 @item alpha_radius, ar
1982 @item alpha_power, ap
1983
1984 @end table
1985
1986 A description of the accepted options follows.
1987
1988 @table @option
1989 @item luma_radius, lr
1990 @item chroma_radius, cr
1991 @item alpha_radius, ar
1992 Set an expression for the box radius in pixels used for blurring the
1993 corresponding input plane.
1994
1995 The radius value must be a non-negative number, and must not be
1996 greater than the value of the expression @code{min(w,h)/2} for the
1997 luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma
1998 planes.
1999
2000 Default value for @option{luma_radius} is "2". If not specified,
2001 @option{chroma_radius} and @option{alpha_radius} default to the
2002 corresponding value set for @option{luma_radius}.
2003
2004 The expressions can contain the following constants:
2005 @table @option
2006 @item w, h
2007 the input width and height in pixels
2008
2009 @item cw, ch
2010 the input chroma image width and height in pixels
2011
2012 @item hsub, vsub
2013 horizontal and vertical chroma subsample values. For example for the
2014 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
2015 @end table
2016
2017 @item luma_power, lp
2018 @item chroma_power, cp
2019 @item alpha_power, ap
2020 Specify how many times the boxblur filter is applied to the
2021 corresponding plane.
2022
2023 Default value for @option{luma_power} is 2. If not specified,
2024 @option{chroma_power} and @option{alpha_power} default to the
2025 corresponding value set for @option{luma_power}.
2026
2027 A value of 0 will disable the effect.
2028 @end table
2029
2030 @subsection Examples
2031
2032 @itemize
2033 @item
2034 Apply a boxblur filter with luma, chroma, and alpha radius
2035 set to 2:
2036 @example
2037 boxblur=luma_radius=2:luma_power=1
2038 boxblur=2:1
2039 @end example
2040
2041 @item
2042 Set luma radius to 2, alpha and chroma radius to 0:
2043 @example
2044 boxblur=2:1:cr=0:ar=0
2045 @end example
2046
2047 @item
2048 Set luma and chroma radius to a fraction of the video dimension:
2049 @example
2050 boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1
2051 @end example
2052 @end itemize
2053
2054 @section colorbalance
2055 Modify intensity of primary colors (red, green and blue) of input frames.
2056
2057 The filter allows an input frame to be adjusted in the shadows, midtones or highlights
2058 regions for the red-cyan, green-magenta or blue-yellow balance.
2059
2060 A positive adjustment value shifts the balance towards the primary color, a negative
2061 value towards the complementary color.
2062
2063 The filter accepts the following options:
2064
2065 @table @option
2066 @item rs
2067 @item gs
2068 @item bs
2069 Adjust red, green and blue shadows (darkest pixels).
2070
2071 @item rm
2072 @item gm
2073 @item bm
2074 Adjust red, green and blue midtones (medium pixels).
2075
2076 @item rh
2077 @item gh
2078 @item bh
2079 Adjust red, green and blue highlights (brightest pixels).
2080
2081 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
2082 @end table
2083
2084 @subsection Examples
2085
2086 @itemize
2087 @item
2088 Add red color cast to shadows:
2089 @example
2090 colorbalance=rs=.3
2091 @end example
2092 @end itemize
2093
2094 @section colormatrix
2095
2096 Convert color matrix.
2097
2098 The filter accepts the following options:
2099
2100 @table @option
2101 @item src
2102 @item dst
2103 Specify the source and destination color matrix. Both values must be
2104 specified.
2105
2106 The accepted values are:
2107 @table @samp
2108 @item bt709
2109 BT.709
2110
2111 @item bt601
2112 BT.601
2113
2114 @item smpte240m
2115 SMPTE-240M
2116
2117 @item fcc
2118 FCC
2119 @end table
2120 @end table
2121
2122 For example to convert from BT.601 to SMPTE-240M, use the command:
2123 @example
2124 colormatrix=bt601:smpte240m
2125 @end example
2126
2127 @section copy
2128
2129 Copy the input source unchanged to the output. Mainly useful for
2130 testing purposes.
2131
2132 @section crop
2133
2134 Crop the input video to given dimensions.
2135
2136 The filter accepts the following options:
2137
2138 @table @option
2139 @item w, out_w
2140 Width of the output video. It defaults to @code{iw}.
2141 This expression is evaluated only once during the filter
2142 configuration.
2143
2144 @item h, out_h
2145 Height of the output video. It defaults to @code{ih}.
2146 This expression is evaluated only once during the filter
2147 configuration.
2148
2149 @item x
2150 Horizontal position, in the input video, of the left edge of the output video.
2151 It defaults to @code{(in_w-out_w)/2}.
2152 This expression is evaluated per-frame.
2153
2154 @item y
2155 Vertical position, in the input video, of the top edge of the output video.
2156 It defaults to @code{(in_h-out_h)/2}.
2157 This expression is evaluated per-frame.
2158
2159 @item keep_aspect
2160 If set to 1 will force the output display aspect ratio
2161 to be the same of the input, by changing the output sample aspect
2162 ratio. It defaults to 0.
2163 @end table
2164
2165 The @var{out_w}, @var{out_h}, @var{x}, @var{y} parameters are
2166 expressions containing the following constants:
2167
2168 @table @option
2169 @item x, y
2170 the computed values for @var{x} and @var{y}. They are evaluated for
2171 each new frame.
2172
2173 @item in_w, in_h
2174 the input width and height
2175
2176 @item iw, ih
2177 same as @var{in_w} and @var{in_h}
2178
2179 @item out_w, out_h
2180 the output (cropped) width and height
2181
2182 @item ow, oh
2183 same as @var{out_w} and @var{out_h}
2184
2185 @item a
2186 same as @var{iw} / @var{ih}
2187
2188 @item sar
2189 input sample aspect ratio
2190
2191 @item dar
2192 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
2193
2194 @item hsub, vsub
2195 horizontal and vertical chroma subsample values. For example for the
2196 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
2197
2198 @item n
2199 the number of input frame, starting from 0
2200
2201 @item pos
2202 the position in the file of the input frame, NAN if unknown
2203
2204 @item t
2205 timestamp expressed in seconds, NAN if the input timestamp is unknown
2206
2207 @end table
2208
2209 The expression for @var{out_w} may depend on the value of @var{out_h},
2210 and the expression for @var{out_h} may depend on @var{out_w}, but they
2211 cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are
2212 evaluated after @var{out_w} and @var{out_h}.
2213
2214 The @var{x} and @var{y} parameters specify the expressions for the
2215 position of the top-left corner of the output (non-cropped) area. They
2216 are evaluated for each frame. If the evaluated value is not valid, it
2217 is approximated to the nearest valid value.
2218
2219 The expression for @var{x} may depend on @var{y}, and the expression
2220 for @var{y} may depend on @var{x}.
2221
2222 @subsection Examples
2223
2224 @itemize
2225 @item
2226 Crop area with size 100x100 at position (12,34).
2227 @example
2228 crop=100:100:12:34
2229 @end example
2230
2231 Using named options, the example above becomes:
2232 @example
2233 crop=w=100:h=100:x=12:y=34
2234 @end example
2235
2236 @item
2237 Crop the central input area with size 100x100:
2238 @example
2239 crop=100:100
2240 @end example
2241
2242 @item
2243 Crop the central input area with size 2/3 of the input video:
2244 @example
2245 crop=2/3*in_w:2/3*in_h
2246 @end example
2247
2248 @item
2249 Crop the input video central square:
2250 @example
2251 crop=out_w=in_h
2252 crop=in_h
2253 @end example
2254
2255 @item
2256 Delimit the rectangle with the top-left corner placed at position
2257 100:100 and the right-bottom corner corresponding to the right-bottom
2258 corner of the input image:
2259 @example
2260 crop=in_w-100:in_h-100:100:100
2261 @end example
2262
2263 @item
2264 Crop 10 pixels from the left and right borders, and 20 pixels from
2265 the top and bottom borders
2266 @example
2267 crop=in_w-2*10:in_h-2*20
2268 @end example
2269
2270 @item
2271 Keep only the bottom right quarter of the input image:
2272 @example
2273 crop=in_w/2:in_h/2:in_w/2:in_h/2
2274 @end example
2275
2276 @item
2277 Crop height for getting Greek harmony:
2278 @example
2279 crop=in_w:1/PHI*in_w
2280 @end example
2281
2282 @item
2283 Appply trembling effect:
2284 @example
2285 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)
2286 @end example
2287
2288 @item
2289 Apply erratic camera effect depending on timestamp:
2290 @example
2291 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)"
2292 @end example
2293
2294 @item
2295 Set x depending on the value of y:
2296 @example
2297 crop=in_w/2:in_h/2:y:10+10*sin(n/10)
2298 @end example
2299 @end itemize
2300
2301 @section cropdetect
2302
2303 Auto-detect crop size.
2304
2305 Calculate necessary cropping parameters and prints the recommended
2306 parameters through the logging system. The detected dimensions
2307 correspond to the non-black area of the input video.
2308
2309 The filter accepts the following options:
2310
2311 @table @option
2312
2313 @item limit
2314 Set higher black value threshold, which can be optionally specified
2315 from nothing (0) to everything (255). An intensity value greater
2316 to the set value is considered non-black. Default value is 24.
2317
2318 @item round
2319 Set the value for which the width/height should be divisible by. The
2320 offset is automatically adjusted to center the video. Use 2 to get
2321 only even dimensions (needed for 4:2:2 video). 16 is best when
2322 encoding to most video codecs. Default value is 16.
2323
2324 @item reset_count, reset
2325 Set the counter that determines after how many frames cropdetect will
2326 reset the previously detected largest video area and start over to
2327 detect the current optimal crop area. Default value is 0.
2328
2329 This can be useful when channel logos distort the video area. 0
2330 indicates never reset and return the largest area encountered during
2331 playback.
2332 @end table
2333
2334 @section curves
2335
2336 Apply color adjustments using curves.
2337
2338 This filter is similar to the Adobe Photoshop and GIMP curves tools. Each
2339 component (red, green and blue) has its values defined by @var{N} key points
2340 tied from each other using a smooth curve. The x-axis represents the pixel
2341 values from the input frame, and the y-axis the new pixel values to be set for
2342 the output frame.
2343
2344 By default, a component curve is defined by the two points @var{(0;0)} and
2345 @var{(1;1)}. This creates a straight line where each original pixel value is
2346 "adjusted" to its own value, which means no change to the image.
2347
2348 The filter allows you to redefine these two points and add some more. A new
2349 curve (using a natural cubic spline interpolation) will be define to pass
2350 smoothly through all these new coordinates. The new defined points needs to be
2351 strictly increasing over the x-axis, and their @var{x} and @var{y} values must
2352 be in the @var{[0;1]} interval.  If the computed curves happened to go outside
2353 the vector spaces, the values will be clipped accordingly.
2354
2355 If there is no key point defined in @code{x=0}, the filter will automatically
2356 insert a @var{(0;0)} point. In the same way, if there is no key point defined
2357 in @code{x=1}, the filter will automatically insert a @var{(1;1)} point.
2358
2359 The filter accepts the following options:
2360
2361 @table @option
2362 @item preset
2363 Select one of the available color presets. This option can be used in addition
2364 to the @option{r}, @option{g}, @option{b} parameters; in this case, the later
2365 options takes priority on the preset values.
2366 Available presets are:
2367 @table @samp
2368 @item none
2369 @item color_negative
2370 @item cross_process
2371 @item darker
2372 @item increase_contrast
2373 @item lighter
2374 @item linear_contrast
2375 @item medium_contrast
2376 @item negative
2377 @item strong_contrast
2378 @item vintage
2379 @end table
2380 Default is @code{none}.
2381 @item master, m
2382 Set the master key points. These points will define a second pass mapping. It
2383 is sometimes called a "luminance" or "value" mapping. It can be used with
2384 @option{r}, @option{g}, @option{b} or @option{all} since it acts like a
2385 post-processing LUT.
2386 @item red, r
2387 Set the key points for the red component.
2388 @item green, g
2389 Set the key points for the green component.
2390 @item blue, b
2391 Set the key points for the blue component.
2392 @item all
2393 Set the key points for all components (not including master).
2394 Can be used in addition to the other key points component
2395 options. In this case, the unset component(s) will fallback on this
2396 @option{all} setting.
2397 @item psfile
2398 Specify a Photoshop curves file (@code{.asv}) to import the settings from.
2399 @end table
2400
2401 To avoid some filtergraph syntax conflicts, each key points list need to be
2402 defined using the following syntax: @code{x0/y0 x1/y1 x2/y2 ...}.
2403
2404 @subsection Examples
2405
2406 @itemize
2407 @item
2408 Increase slightly the middle level of blue:
2409 @example
2410 curves=blue='0.5/0.58'
2411 @end example
2412
2413 @item
2414 Vintage effect:
2415 @example
2416 curves=r='0/0.11 .42/.51 1/0.95':g='0.50/0.48':b='0/0.22 .49/.44 1/0.8'
2417 @end example
2418 Here we obtain the following coordinates for each components:
2419 @table @var
2420 @item red
2421 @code{(0;0.11) (0.42;0.51) (1;0.95)}
2422 @item green
2423 @code{(0;0) (0.50;0.48) (1;1)}
2424 @item blue
2425 @code{(0;0.22) (0.49;0.44) (1;0.80)}
2426 @end table
2427
2428 @item
2429 The previous example can also be achieved with the associated built-in preset:
2430 @example
2431 curves=preset=vintage
2432 @end example
2433
2434 @item
2435 Or simply:
2436 @example
2437 curves=vintage
2438 @end example
2439
2440 @item
2441 Use a Photoshop preset and redefine the points of the green component:
2442 @example
2443 curves=psfile='MyCurvesPresets/purple.asv':green='0.45/0.53'
2444 @end example
2445 @end itemize
2446
2447 @anchor{decimate}
2448 @section decimate
2449
2450 Drop duplicated frames at regular intervals.
2451
2452 The filter accepts the following options:
2453
2454 @table @option
2455 @item cycle
2456 Set the number of frames from which one will be dropped. Setting this to
2457 @var{N} means one frame in every batch of @var{N} frames will be dropped.
2458 Default is @code{5}.
2459
2460 @item dupthresh
2461 Set the threshold for duplicate detection. If the difference metric for a frame
2462 is less than or equal to this value, then it is declared as duplicate. Default
2463 is @code{1.1}
2464
2465 @item scthresh
2466 Set scene change threshold. Default is @code{15}.
2467
2468 @item blockx
2469 @item blocky
2470 Set the size of the x and y-axis blocks used during metric calculations.
2471 Larger blocks give better noise suppression, but also give worse detection of
2472 small movements. Must be a power of two. Default is @code{32}.
2473
2474 @item ppsrc
2475 Mark main input as a pre-processed input and activate clean source input
2476 stream. This allows the input to be pre-processed with various filters to help
2477 the metrics calculation while keeping the frame selection lossless. When set to
2478 @code{1}, the first stream is for the pre-processed input, and the second
2479 stream is the clean source from where the kept frames are chosen. Default is
2480 @code{0}.
2481
2482 @item chroma
2483 Set whether or not chroma is considered in the metric calculations. Default is
2484 @code{1}.
2485 @end table
2486
2487 @section delogo
2488
2489 Suppress a TV station logo by a simple interpolation of the surrounding
2490 pixels. Just set a rectangle covering the logo and watch it disappear
2491 (and sometimes something even uglier appear - your mileage may vary).
2492
2493 This filter accepts the following options:
2494 @table @option
2495
2496 @item x, y
2497 Specify the top left corner coordinates of the logo. They must be
2498 specified.
2499
2500 @item w, h
2501 Specify the width and height of the logo to clear. They must be
2502 specified.
2503
2504 @item band, t
2505 Specify the thickness of the fuzzy edge of the rectangle (added to
2506 @var{w} and @var{h}). The default value is 4.
2507
2508 @item show
2509 When set to 1, a green rectangle is drawn on the screen to simplify
2510 finding the right @var{x}, @var{y}, @var{w}, @var{h} parameters, and
2511 @var{band} is set to 4. The default value is 0.
2512
2513 @end table
2514
2515 @subsection Examples
2516
2517 @itemize
2518 @item
2519 Set a rectangle covering the area with top left corner coordinates 0,0
2520 and size 100x77, setting a band of size 10:
2521 @example
2522 delogo=x=0:y=0:w=100:h=77:band=10
2523 @end example
2524
2525 @end itemize
2526
2527 @section deshake
2528
2529 Attempt to fix small changes in horizontal and/or vertical shift. This
2530 filter helps remove camera shake from hand-holding a camera, bumping a
2531 tripod, moving on a vehicle, etc.
2532
2533 The filter accepts the following options:
2534
2535 @table @option
2536
2537 @item x
2538 @item y
2539 @item w
2540 @item h
2541 Specify a rectangular area where to limit the search for motion
2542 vectors.
2543 If desired the search for motion vectors can be limited to a
2544 rectangular area of the frame defined by its top left corner, width
2545 and height. These parameters have the same meaning as the drawbox
2546 filter which can be used to visualise the position of the bounding
2547 box.
2548
2549 This is useful when simultaneous movement of subjects within the frame
2550 might be confused for camera motion by the motion vector search.
2551
2552 If any or all of @var{x}, @var{y}, @var{w} and @var{h} are set to -1
2553 then the full frame is used. This allows later options to be set
2554 without specifying the bounding box for the motion vector search.
2555
2556 Default - search the whole frame.
2557
2558 @item rx
2559 @item ry
2560 Specify the maximum extent of movement in x and y directions in the
2561 range 0-64 pixels. Default 16.
2562
2563 @item edge
2564 Specify how to generate pixels to fill blanks at the edge of the
2565 frame. Available values are:
2566 @table @samp
2567 @item blank, 0
2568 Fill zeroes at blank locations
2569 @item original, 1
2570 Original image at blank locations
2571 @item clamp, 2
2572 Extruded edge value at blank locations
2573 @item mirror, 3
2574 Mirrored edge at blank locations
2575 @end table
2576 Default value is @samp{mirror}.
2577
2578 @item blocksize
2579 Specify the blocksize to use for motion search. Range 4-128 pixels,
2580 default 8.
2581
2582 @item contrast
2583 Specify the contrast threshold for blocks. Only blocks with more than
2584 the specified contrast (difference between darkest and lightest
2585 pixels) will be considered. Range 1-255, default 125.
2586
2587 @item search
2588 Specify the search strategy. Available values are:
2589 @table @samp
2590 @item exhaustive, 0
2591 Set exhaustive search
2592 @item less, 1
2593 Set less exhaustive search.
2594 @end table
2595 Default value is @samp{exhaustive}.
2596
2597 @item filename
2598 If set then a detailed log of the motion search is written to the
2599 specified file.
2600
2601 @item opencl
2602 If set to 1, specify using OpenCL capabilities, only available if
2603 FFmpeg was configured with @code{--enable-opencl}. Default value is 0.
2604
2605 @end table
2606
2607 @section drawbox
2608
2609 Draw a colored box on the input image.
2610
2611 This filter accepts the following options:
2612
2613 @table @option
2614 @item x, y
2615 Specify the top left corner coordinates of the box. Default to 0.
2616
2617 @item width, w
2618 @item height, h
2619 Specify the width and height of the box, if 0 they are interpreted as
2620 the input width and height. Default to 0.
2621
2622 @item color, c
2623 Specify the color of the box to write, it can be the name of a color
2624 (case insensitive match) or a 0xRRGGBB[AA] sequence. If the special
2625 value @code{invert} is used, the box edge color is the same as the
2626 video with inverted luma.
2627
2628 @item thickness, t
2629 Set the thickness of the box edge. Default value is @code{4}.
2630 @end table
2631
2632 @subsection Examples
2633
2634 @itemize
2635 @item
2636 Draw a black box around the edge of the input image:
2637 @example
2638 drawbox
2639 @end example
2640
2641 @item
2642 Draw a box with color red and an opacity of 50%:
2643 @example
2644 drawbox=10:20:200:60:red@@0.5
2645 @end example
2646
2647 The previous example can be specified as:
2648 @example
2649 drawbox=x=10:y=20:w=200:h=60:color=red@@0.5
2650 @end example
2651
2652 @item
2653 Fill the box with pink color:
2654 @example
2655 drawbox=x=10:y=10:w=100:h=100:color=pink@@0.5:t=max
2656 @end example
2657 @end itemize
2658
2659 @anchor{drawtext}
2660 @section drawtext
2661
2662 Draw text string or text from specified file on top of video using the
2663 libfreetype library.
2664
2665 To enable compilation of this filter you need to configure FFmpeg with
2666 @code{--enable-libfreetype}.
2667
2668 @subsection Syntax
2669
2670 The description of the accepted parameters follows.
2671
2672 @table @option
2673
2674 @item box
2675 Used to draw a box around text using background color.
2676 Value should be either 1 (enable) or 0 (disable).
2677 The default value of @var{box} is 0.
2678
2679 @item boxcolor
2680 The color to be used for drawing box around text.
2681 Either a string (e.g. "yellow") or in 0xRRGGBB[AA] format
2682 (e.g. "0xff00ff"), possibly followed by an alpha specifier.
2683 The default value of @var{boxcolor} is "white".
2684
2685 @item draw
2686 Set an expression which specifies if the text should be drawn. If the
2687 expression evaluates to 0, the text is not drawn. This is useful for
2688 specifying that the text should be drawn only when specific conditions
2689 are met.
2690
2691 Default value is "1".
2692
2693 See below for the list of accepted constants and functions.
2694
2695 @item expansion
2696 Select how the @var{text} is expanded. Can be either @code{none},
2697 @code{strftime} (deprecated) or
2698 @code{normal} (default). See the @ref{drawtext_expansion, Text expansion} section
2699 below for details.
2700
2701 @item fix_bounds
2702 If true, check and fix text coords to avoid clipping.
2703
2704 @item fontcolor
2705 The color to be used for drawing fonts.
2706 Either a string (e.g. "red") or in 0xRRGGBB[AA] format
2707 (e.g. "0xff000033"), possibly followed by an alpha specifier.
2708 The default value of @var{fontcolor} is "black".
2709
2710 @item fontfile
2711 The font file to be used for drawing text. Path must be included.
2712 This parameter is mandatory.
2713
2714 @item fontsize
2715 The font size to be used for drawing text.
2716 The default value of @var{fontsize} is 16.
2717
2718 @item ft_load_flags
2719 Flags to be used for loading the fonts.
2720
2721 The flags map the corresponding flags supported by libfreetype, and are
2722 a combination of the following values:
2723 @table @var
2724 @item default
2725 @item no_scale
2726 @item no_hinting
2727 @item render
2728 @item no_bitmap
2729 @item vertical_layout
2730 @item force_autohint
2731 @item crop_bitmap
2732 @item pedantic
2733 @item ignore_global_advance_width
2734 @item no_recurse
2735 @item ignore_transform
2736 @item monochrome
2737 @item linear_design
2738 @item no_autohint
2739 @item end table
2740 @end table
2741
2742 Default value is "render".
2743
2744 For more information consult the documentation for the FT_LOAD_*
2745 libfreetype flags.
2746
2747 @item shadowcolor
2748 The color to be used for drawing a shadow behind the drawn text.  It
2749 can be a color name (e.g. "yellow") or a string in the 0xRRGGBB[AA]
2750 form (e.g. "0xff00ff"), possibly followed by an alpha specifier.
2751 The default value of @var{shadowcolor} is "black".
2752
2753 @item shadowx, shadowy
2754 The x and y offsets for the text shadow position with respect to the
2755 position of the text. They can be either positive or negative
2756 values. Default value for both is "0".
2757
2758 @item tabsize
2759 The size in number of spaces to use for rendering the tab.
2760 Default value is 4.
2761
2762 @item timecode
2763 Set the initial timecode representation in "hh:mm:ss[:;.]ff"
2764 format. It can be used with or without text parameter. @var{timecode_rate}
2765 option must be specified.
2766
2767 @item timecode_rate, rate, r
2768 Set the timecode frame rate (timecode only).
2769
2770 @item text
2771 The text string to be drawn. The text must be a sequence of UTF-8
2772 encoded characters.
2773 This parameter is mandatory if no file is specified with the parameter
2774 @var{textfile}.
2775
2776 @item textfile
2777 A text file containing text to be drawn. The text must be a sequence
2778 of UTF-8 encoded characters.
2779
2780 This parameter is mandatory if no text string is specified with the
2781 parameter @var{text}.
2782
2783 If both @var{text} and @var{textfile} are specified, an error is thrown.
2784
2785 @item reload
2786 If set to 1, the @var{textfile} will be reloaded before each frame.
2787 Be sure to update it atomically, or it may be read partially, or even fail.
2788
2789 @item x, y
2790 The expressions which specify the offsets where text will be drawn
2791 within the video frame. They are relative to the top/left border of the
2792 output image.
2793
2794 The default value of @var{x} and @var{y} is "0".
2795
2796 See below for the list of accepted constants and functions.
2797 @end table
2798
2799 The parameters for @var{x} and @var{y} are expressions containing the
2800 following constants and functions:
2801
2802 @table @option
2803 @item dar
2804 input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
2805
2806 @item hsub, vsub
2807 horizontal and vertical chroma subsample values. For example for the
2808 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
2809
2810 @item line_h, lh
2811 the height of each text line
2812
2813 @item main_h, h, H
2814 the input height
2815
2816 @item main_w, w, W
2817 the input width
2818
2819 @item max_glyph_a, ascent
2820 the maximum distance from the baseline to the highest/upper grid
2821 coordinate used to place a glyph outline point, for all the rendered
2822 glyphs.
2823 It is a positive value, due to the grid's orientation with the Y axis
2824 upwards.
2825
2826 @item max_glyph_d, descent
2827 the maximum distance from the baseline to the lowest grid coordinate
2828 used to place a glyph outline point, for all the rendered glyphs.
2829 This is a negative value, due to the grid's orientation, with the Y axis
2830 upwards.
2831
2832 @item max_glyph_h
2833 maximum glyph height, that is the maximum height for all the glyphs
2834 contained in the rendered text, it is equivalent to @var{ascent} -
2835 @var{descent}.
2836
2837 @item max_glyph_w
2838 maximum glyph width, that is the maximum width for all the glyphs
2839 contained in the rendered text
2840
2841 @item n
2842 the number of input frame, starting from 0
2843
2844 @item rand(min, max)
2845 return a random number included between @var{min} and @var{max}
2846
2847 @item sar
2848 input sample aspect ratio
2849
2850 @item t
2851 timestamp expressed in seconds, NAN if the input timestamp is unknown
2852
2853 @item text_h, th
2854 the height of the rendered text
2855
2856 @item text_w, tw
2857 the width of the rendered text
2858
2859 @item x, y
2860 the x and y offset coordinates where the text is drawn.
2861
2862 These parameters allow the @var{x} and @var{y} expressions to refer
2863 each other, so you can for example specify @code{y=x/dar}.
2864 @end table
2865
2866 If libavfilter was built with @code{--enable-fontconfig}, then
2867 @option{fontfile} can be a fontconfig pattern or omitted.
2868
2869 @anchor{drawtext_expansion}
2870 @subsection Text expansion
2871
2872 If @option{expansion} is set to @code{strftime},
2873 the filter recognizes strftime() sequences in the provided text and
2874 expands them accordingly. Check the documentation of strftime(). This
2875 feature is deprecated.
2876
2877 If @option{expansion} is set to @code{none}, the text is printed verbatim.
2878
2879 If @option{expansion} is set to @code{normal} (which is the default),
2880 the following expansion mechanism is used.
2881
2882 The backslash character '\', followed by any character, always expands to
2883 the second character.
2884
2885 Sequence of the form @code{%@{...@}} are expanded. The text between the
2886 braces is a function name, possibly followed by arguments separated by ':'.
2887 If the arguments contain special characters or delimiters (':' or '@}'),
2888 they should be escaped.
2889
2890 Note that they probably must also be escaped as the value for the
2891 @option{text} option in the filter argument string and as the filter
2892 argument in the filtergraph description, and possibly also for the shell,
2893 that makes up to four levels of escaping; using a text file avoids these
2894 problems.
2895
2896 The following functions are available:
2897
2898 @table @command
2899
2900 @item expr, e
2901 The expression evaluation result.
2902
2903 It must take one argument specifying the expression to be evaluated,
2904 which accepts the same constants and functions as the @var{x} and
2905 @var{y} values. Note that not all constants should be used, for
2906 example the text size is not known when evaluating the expression, so
2907 the constants @var{text_w} and @var{text_h} will have an undefined
2908 value.
2909
2910 @item gmtime
2911 The time at which the filter is running, expressed in UTC.
2912 It can accept an argument: a strftime() format string.
2913
2914 @item localtime
2915 The time at which the filter is running, expressed in the local time zone.
2916 It can accept an argument: a strftime() format string.
2917
2918 @item n, frame_num
2919 The frame number, starting from 0.
2920
2921 @item pts
2922 The timestamp of the current frame, in seconds, with microsecond accuracy.
2923
2924 @end table
2925
2926 @subsection Examples
2927
2928 @itemize
2929 @item
2930 Draw "Test Text" with font FreeSerif, using the default values for the
2931 optional parameters.
2932
2933 @example
2934 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"
2935 @end example
2936
2937 @item
2938 Draw 'Test Text' with font FreeSerif of size 24 at position x=100
2939 and y=50 (counting from the top-left corner of the screen), text is
2940 yellow with a red box around it. Both the text and the box have an
2941 opacity of 20%.
2942
2943 @example
2944 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
2945           x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2"
2946 @end example
2947
2948 Note that the double quotes are not necessary if spaces are not used
2949 within the parameter list.
2950
2951 @item
2952 Show the text at the center of the video frame:
2953 @example
2954 drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h-line_h)/2"
2955 @end example
2956
2957 @item
2958 Show a text line sliding from right to left in the last row of the video
2959 frame. The file @file{LONG_LINE} is assumed to contain a single line
2960 with no newlines.
2961 @example
2962 drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t"
2963 @end example
2964
2965 @item
2966 Show the content of file @file{CREDITS} off the bottom of the frame and scroll up.
2967 @example
2968 drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t"
2969 @end example
2970
2971 @item
2972 Draw a single green letter "g", at the center of the input video.
2973 The glyph baseline is placed at half screen height.
2974 @example
2975 drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent"
2976 @end example
2977
2978 @item
2979 Show text for 1 second every 3 seconds:
2980 @example
2981 drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:draw=lt(mod(t\,3)\,1):text='blink'"
2982 @end example
2983
2984 @item
2985 Use fontconfig to set the font. Note that the colons need to be escaped.
2986 @example
2987 drawtext='fontfile=Linux Libertine O-40\:style=Semibold:text=FFmpeg'
2988 @end example
2989
2990 @item
2991 Print the date of a real-time encoding (see strftime(3)):
2992 @example
2993 drawtext='fontfile=FreeSans.ttf:text=%@{localtime:%a %b %d %Y@}'
2994 @end example
2995
2996 @end itemize
2997
2998 For more information about libfreetype, check:
2999 @url{http://www.freetype.org/}.
3000
3001 For more information about fontconfig, check:
3002 @url{http://freedesktop.org/software/fontconfig/fontconfig-user.html}.
3003
3004 @section edgedetect
3005
3006 Detect and draw edges. The filter uses the Canny Edge Detection algorithm.
3007
3008 The filter accepts the following options:
3009
3010 @table @option
3011 @item low, high
3012 Set low and high threshold values used by the Canny thresholding
3013 algorithm.
3014
3015 The high threshold selects the "strong" edge pixels, which are then
3016 connected through 8-connectivity with the "weak" edge pixels selected
3017 by the low threshold.
3018
3019 @var{low} and @var{high} threshold values must be choosen in the range
3020 [0,1], and @var{low} should be lesser or equal to @var{high}.
3021
3022 Default value for @var{low} is @code{20/255}, and default value for @var{high}
3023 is @code{50/255}.
3024 @end table
3025
3026 Example:
3027 @example
3028 edgedetect=low=0.1:high=0.4
3029 @end example
3030
3031 @section fade
3032
3033 Apply fade-in/out effect to input video.
3034
3035 This filter accepts the following options:
3036
3037 @table @option
3038 @item type, t
3039 The effect type -- can be either "in" for fade-in, or "out" for a fade-out
3040 effect.
3041 Default is @code{in}.
3042
3043 @item start_frame, s
3044 Specify the number of the start frame for starting to apply the fade
3045 effect. Default is 0.
3046
3047 @item nb_frames, n
3048 The number of frames for which the fade effect has to last. At the end of the
3049 fade-in effect the output video will have the same intensity as the input video,
3050 at the end of the fade-out transition the output video will be completely black.
3051 Default is 25.
3052
3053 @item alpha
3054 If set to 1, fade only alpha channel, if one exists on the input.
3055 Default value is 0.
3056 @end table
3057
3058 @subsection Examples
3059
3060 @itemize
3061 @item
3062 Fade in first 30 frames of video:
3063 @example
3064 fade=in:0:30
3065 @end example
3066
3067 The command above is equivalent to:
3068 @example
3069 fade=t=in:s=0:n=30
3070 @end example
3071
3072 @item
3073 Fade out last 45 frames of a 200-frame video:
3074 @example
3075 fade=out:155:45
3076 fade=type=out:start_frame=155:nb_frames=45
3077 @end example
3078
3079 @item
3080 Fade in first 25 frames and fade out last 25 frames of a 1000-frame video:
3081 @example
3082 fade=in:0:25, fade=out:975:25
3083 @end example
3084
3085 @item
3086 Make first 5 frames black, then fade in from frame 5-24:
3087 @example
3088 fade=in:5:20
3089 @end example
3090
3091 @item
3092 Fade in alpha over first 25 frames of video:
3093 @example
3094 fade=in:0:25:alpha=1
3095 @end example
3096 @end itemize
3097
3098 @section field
3099
3100 Extract a single field from an interlaced image using stride
3101 arithmetic to avoid wasting CPU time. The output frames are marked as
3102 non-interlaced.
3103
3104 The filter accepts the following options:
3105
3106 @table @option
3107 @item type
3108 Specify whether to extract the top (if the value is @code{0} or
3109 @code{top}) or the bottom field (if the value is @code{1} or
3110 @code{bottom}).
3111 @end table
3112
3113 @section fieldmatch
3114
3115 Field matching filter for inverse telecine. It is meant to reconstruct the
3116 progressive frames from a telecined stream. The filter does not drop duplicated
3117 frames, so to achieve a complete inverse telecine @code{fieldmatch} needs to be
3118 followed by a decimation filter such as @ref{decimate} in the filtergraph.
3119
3120 The separation of the field matching and the decimation is notably motivated by
3121 the possibility of inserting a de-interlacing filter fallback between the two.
3122 If the source has mixed telecined and real interlaced content,
3123 @code{fieldmatch} will not be able to match fields for the interlaced parts.
3124 But these remaining combed frames will be marked as interlaced, and thus can be
3125 de-interlaced by a later filter such as @ref{yadif} before decimation.
3126
3127 In addition to the various configuration options, @code{fieldmatch} can take an
3128 optional second stream, activated through the @option{ppsrc} option. If
3129 enabled, the frames reconstruction will be based on the fields and frames from
3130 this second stream. This allows the first input to be pre-processed in order to
3131 help the various algorithms of the filter, while keeping the output lossless
3132 (assuming the fields are matched properly). Typically, a field-aware denoiser,
3133 or brightness/contrast adjustments can help.
3134
3135 Note that this filter uses the same algorithms as TIVTC/TFM (AviSynth project)
3136 and VIVTC/VFM (VapourSynth project). The later is a light clone of TFM from
3137 which @code{fieldmatch} is based on. While the semantic and usage are very
3138 close, some behaviour and options names can differ.
3139
3140 The filter accepts the following options:
3141
3142 @table @option
3143 @item order
3144 Specify the assumed field order of the input stream. Available values are:
3145
3146 @table @samp
3147 @item auto
3148 Auto detect parity (use FFmpeg's internal parity value).
3149 @item bff
3150 Assume bottom field first.
3151 @item tff
3152 Assume top field first.
3153 @end table
3154
3155 Note that it is sometimes recommended not to trust the parity announced by the
3156 stream.
3157
3158 Default value is @var{auto}.
3159
3160 @item mode
3161 Set the matching mode or strategy to use. @option{pc} mode is the safest in the
3162 sense that it wont risk creating jerkiness due to duplicate frames when
3163 possible, but if there are bad edits or blended fields it will end up
3164 outputting combed frames when a good match might actually exist. On the other
3165 hand, @option{pcn_ub} mode is the most risky in terms of creating jerkiness,
3166 but will almost always find a good frame if there is one. The other values are
3167 all somewhere in between @option{pc} and @option{pcn_ub} in terms of risking
3168 jerkiness and creating duplicate frames versus finding good matches in sections
3169 with bad edits, orphaned fields, blended fields, etc.
3170
3171 More details about p/c/n/u/b are available in @ref{p/c/n/u/b meaning} section.
3172
3173 Available values are:
3174
3175 @table @samp
3176 @item pc
3177 2-way matching (p/c)
3178 @item pc_n
3179 2-way matching, and trying 3rd match if still combed (p/c + n)
3180 @item pc_u
3181 2-way matching, and trying 3rd match (same order) if still combed (p/c + u)
3182 @item pc_n_ub
3183 2-way matching, trying 3rd match if still combed, and trying 4th/5th matches if
3184 still combed (p/c + n + u/b)
3185 @item pcn
3186 3-way matching (p/c/n)
3187 @item pcn_ub
3188 3-way matching, and trying 4th/5th matches if all 3 of the original matches are
3189 detected as combed (p/c/n + u/b)
3190 @end table
3191
3192 The parenthesis at the end indicate the matches that would be used for that
3193 mode assuming @option{order}=@var{tff} (and @option{field} on @var{auto} or
3194 @var{top}).
3195
3196 In terms of speed @option{pc} mode is by far the fastest and @option{pcn_ub} is
3197 the slowest.
3198
3199 Default value is @var{pc_n}.
3200
3201 @item ppsrc
3202 Mark the main input stream as a pre-processed input, and enable the secondary
3203 input stream as the clean source to pick the fields from. See the filter
3204 introduction for more details. It is similar to the @option{clip2} feature from
3205 VFM/TFM.
3206
3207 Default value is @code{0} (disabled).
3208
3209 @item field
3210 Set the field to match from. It is recommended to set this to the same value as
3211 @option{order} unless you experience matching failures with that setting. In
3212 certain circumstances changing the field that is used to match from can have a
3213 large impact on matching performance. Available values are:
3214
3215 @table @samp
3216 @item auto
3217 Automatic (same value as @option{order}).
3218 @item bottom
3219 Match from the bottom field.
3220 @item top
3221 Match from the top field.
3222 @end table
3223
3224 Default value is @var{auto}.
3225
3226 @item mchroma
3227 Set whether or not chroma is included during the match comparisons. In most
3228 cases it is recommended to leave this enabled. You should set this to @code{0}
3229 only if your clip has bad chroma problems such as heavy rainbowing or other
3230 artifacts. Setting this to @code{0} could also be used to speed things up at
3231 the cost of some accuracy.
3232
3233 Default value is @code{1}.
3234
3235 @item y0
3236 @item y1
3237 These define an exclusion band which excludes the lines between @option{y0} and
3238 @option{y1} from being included in the field matching decision. An exclusion
3239 band can be used to ignore subtitles, a logo, or other things that may
3240 interfere with the matching. @option{y0} sets the starting scan line and
3241 @option{y1} sets the ending line; all lines in between @option{y0} and
3242 @option{y1} (including @option{y0} and @option{y1}) will be ignored. Setting
3243 @option{y0} and @option{y1} to the same value will disable the feature.
3244 @option{y0} and @option{y1} defaults to @code{0}.
3245
3246 @item scthresh
3247 Set the scene change detection threshold as a percentage of maximum change on
3248 the luma plane. Good values are in the @code{[8.0, 14.0]} range. Scene change
3249 detection is only relevant in case @option{combmatch}=@var{sc}.  The range for
3250 @option{scthresh} is @code{[0.0, 100.0]}.
3251
3252 Default value is @code{12.0}.
3253
3254 @item combmatch
3255 When @option{combatch} is not @var{none}, @code{fieldmatch} will take into
3256 account the combed scores of matches when deciding what match to use as the
3257 final match. Available values are:
3258
3259 @table @samp
3260 @item none
3261 No final matching based on combed scores.
3262 @item sc
3263 Combed scores are only used when a scene change is detected.
3264 @item full
3265 Use combed scores all the time.
3266 @end table
3267
3268 Default is @var{sc}.
3269
3270 @item combdbg
3271 Force @code{fieldmatch} to calculate the combed metrics for certain matches and
3272 print them. This setting is known as @option{micout} in TFM/VFM vocabulary.
3273 Available values are:
3274
3275 @table @samp
3276 @item none
3277 No forced calculation.
3278 @item pcn
3279 Force p/c/n calculations.
3280 @item pcnub
3281 Force p/c/n/u/b calculations.
3282 @end table
3283
3284 Default value is @var{none}.
3285
3286 @item cthresh
3287 This is the area combing threshold used for combed frame detection. This
3288 essentially controls how "strong" or "visible" combing must be to be detected.
3289 Larger values mean combing must be more visible and smaller values mean combing
3290 can be less visible or strong and still be detected. Valid settings are from
3291 @code{-1} (every pixel will be detected as combed) to @code{255} (no pixel will
3292 be detected as combed). This is basically a pixel difference value. A good
3293 range is @code{[8, 12]}.
3294
3295 Default value is @code{9}.
3296
3297 @item chroma
3298 Sets whether or not chroma is considered in the combed frame decision.  Only
3299 disable this if your source has chroma problems (rainbowing, etc.) that are
3300 causing problems for the combed frame detection with chroma enabled. Actually,
3301 using @option{chroma}=@var{0} is usually more reliable, except for the case
3302 where there is chroma only combing in the source.
3303
3304 Default value is @code{0}.
3305
3306 @item blockx
3307 @item blocky
3308 Respectively set the x-axis and y-axis size of the window used during combed
3309 frame detection. This has to do with the size of the area in which
3310 @option{combpel} pixels are required to be detected as combed for a frame to be
3311 declared combed. See the @option{combpel} parameter description for more info.
3312 Possible values are any number that is a power of 2 starting at 4 and going up
3313 to 512.
3314
3315 Default value is @code{16}.
3316
3317 @item combpel
3318 The number of combed pixels inside any of the @option{blocky} by
3319 @option{blockx} size blocks on the frame for the frame to be detected as
3320 combed. While @option{cthresh} controls how "visible" the combing must be, this
3321 setting controls "how much" combing there must be in any localized area (a
3322 window defined by the @option{blockx} and @option{blocky} settings) on the
3323 frame. Minimum value is @code{0} and maximum is @code{blocky x blockx} (at
3324 which point no frames will ever be detected as combed). This setting is known
3325 as @option{MI} in TFM/VFM vocabulary.
3326
3327 Default value is @code{80}.
3328 @end table
3329
3330 @anchor{p/c/n/u/b meaning}
3331 @subsection p/c/n/u/b meaning
3332
3333 @subsubsection p/c/n
3334
3335 We assume the following telecined stream:
3336
3337 @example
3338 Top fields:     1 2 2 3 4
3339 Bottom fields:  1 2 3 4 4
3340 @end example
3341
3342 The numbers correspond to the progressive frame the fields relate to. Here, the
3343 first two frames are progressive, the 3rd and 4th are combed, and so on.
3344
3345 When @code{fieldmatch} is configured to run a matching from bottom
3346 (@option{field}=@var{bottom}) this is how this input stream get transformed:
3347
3348 @example
3349 Input stream:
3350                 T     1 2 2 3 4
3351                 B     1 2 3 4 4   <-- matching reference
3352
3353 Matches:              c c n n c
3354
3355 Output stream:
3356                 T     1 2 3 4 4
3357                 B     1 2 3 4 4
3358 @end example
3359
3360 As a result of the field matching, we can see that some frames get duplicated.
3361 To perform a complete inverse telecine, you need to rely on a decimation filter
3362 after this operation. See for instance the @ref{decimate} filter.
3363
3364 The same operation now matching from top fields (@option{field}=@var{top})
3365 looks like this:
3366
3367 @example
3368 Input stream:
3369                 T     1 2 2 3 4   <-- matching reference
3370                 B     1 2 3 4 4
3371
3372 Matches:              c c p p c
3373
3374 Output stream:
3375                 T     1 2 2 3 4
3376                 B     1 2 2 3 4
3377 @end example
3378
3379 In these examples, we can see what @var{p}, @var{c} and @var{n} mean;
3380 basically, they refer to the frame and field of the opposite parity:
3381
3382 @itemize
3383 @item @var{p} matches the field of the opposite parity in the previous frame
3384 @item @var{c} matches the field of the opposite parity in the current frame
3385 @item @var{n} matches the field of the opposite parity in the next frame
3386 @end itemize
3387
3388 @subsubsection u/b
3389
3390 The @var{u} and @var{b} matching are a bit special in the sense that they match
3391 from the opposite parity flag. In the following examples, we assume that we are
3392 currently matching the 2nd frame (Top:2, bottom:2). According to the match, a
3393 'x' is placed above and below each matched fields.
3394
3395 With bottom matching (@option{field}=@var{bottom}):
3396 @example
3397 Match:           c         p           n          b          u
3398
3399                  x       x               x        x          x
3400   Top          1 2 2     1 2 2       1 2 2      1 2 2      1 2 2
3401   Bottom       1 2 3     1 2 3       1 2 3      1 2 3      1 2 3
3402                  x         x           x        x              x
3403
3404 Output frames:
3405                  2          1          2          2          2
3406                  2          2          2          1          3
3407 @end example
3408
3409 With top matching (@option{field}=@var{top}):
3410 @example
3411 Match:           c         p           n          b          u
3412
3413                  x         x           x        x              x
3414   Top          1 2 2     1 2 2       1 2 2      1 2 2      1 2 2
3415   Bottom       1 2 3     1 2 3       1 2 3      1 2 3      1 2 3
3416                  x       x               x        x          x
3417
3418 Output frames:
3419                  2          2          2          1          2
3420                  2          1          3          2          2
3421 @end example
3422
3423 @subsection Examples
3424
3425 Simple IVTC of a top field first telecined stream:
3426 @example
3427 fieldmatch=order=tff:combmatch=none, decimate
3428 @end example
3429
3430 Advanced IVTC, with fallback on @ref{yadif} for still combed frames:
3431 @example
3432 fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate
3433 @end example
3434
3435 @section fieldorder
3436
3437 Transform the field order of the input video.
3438
3439 This filter accepts the following options:
3440
3441 @table @option
3442
3443 @item order
3444 Output field order. Valid values are @var{tff} for top field first or @var{bff}
3445 for bottom field first.
3446 @end table
3447
3448 Default value is @samp{tff}.
3449
3450 Transformation is achieved by shifting the picture content up or down
3451 by one line, and filling the remaining line with appropriate picture content.
3452 This method is consistent with most broadcast field order converters.
3453
3454 If the input video is not flagged as being interlaced, or it is already
3455 flagged as being of the required output field order then this filter does
3456 not alter the incoming video.
3457
3458 This filter is very useful when converting to or from PAL DV material,
3459 which is bottom field first.
3460
3461 For example:
3462 @example
3463 ffmpeg -i in.vob -vf "fieldorder=bff" out.dv
3464 @end example
3465
3466 @section fifo
3467
3468 Buffer input images and send them when they are requested.
3469
3470 This filter is mainly useful when auto-inserted by the libavfilter
3471 framework.
3472
3473 The filter does not take parameters.
3474
3475 @anchor{format}
3476 @section format
3477
3478 Convert the input video to one of the specified pixel formats.
3479 Libavfilter will try to pick one that is supported for the input to
3480 the next filter.
3481
3482 This filter accepts the following parameters:
3483 @table @option
3484
3485 @item pix_fmts
3486 A '|'-separated list of pixel format names, for example
3487 "pix_fmts=yuv420p|monow|rgb24".
3488
3489 @end table
3490
3491 @subsection Examples
3492
3493 @itemize
3494 @item
3495 Convert the input video to the format @var{yuv420p}
3496 @example
3497 format=pix_fmts=yuv420p
3498 @end example
3499
3500 Convert the input video to any of the formats in the list
3501 @example
3502 format=pix_fmts=yuv420p|yuv444p|yuv410p
3503 @end example
3504 @end itemize
3505
3506 @section fps
3507
3508 Convert the video to specified constant frame rate by duplicating or dropping
3509 frames as necessary.
3510
3511 This filter accepts the following named parameters:
3512 @table @option
3513
3514 @item fps
3515 Desired output frame rate. The default is @code{25}.
3516
3517 @item round
3518 Rounding method.
3519
3520 Possible values are:
3521 @table @option
3522 @item zero
3523 zero round towards 0
3524 @item inf
3525 round away from 0
3526 @item down
3527 round towards -infinity
3528 @item up
3529 round towards +infinity
3530 @item near
3531 round to nearest
3532 @end table
3533 The default is @code{near}.
3534
3535 @end table
3536
3537 Alternatively, the options can be specified as a flat string:
3538 @var{fps}[:@var{round}].
3539
3540 See also the @ref{setpts} filter.
3541
3542 @section framestep
3543
3544 Select one frame every N-th frame.
3545
3546 This filter accepts the following option:
3547 @table @option
3548 @item step
3549 Select frame after every @code{step} frames.
3550 Allowed values are positive integers higher than 0. Default value is @code{1}.
3551 @end table
3552
3553 @anchor{frei0r}
3554 @section frei0r
3555
3556 Apply a frei0r effect to the input video.
3557
3558 To enable compilation of this filter you need to install the frei0r
3559 header and configure FFmpeg with @code{--enable-frei0r}.
3560
3561 This filter accepts the following options:
3562
3563 @table @option
3564
3565 @item filter_name
3566 The name to the frei0r effect to load. If the environment variable
3567 @env{FREI0R_PATH} is defined, the frei0r effect is searched in each one of the
3568 directories specified by the colon separated list in @env{FREIOR_PATH},
3569 otherwise in the standard frei0r paths, which are in this order:
3570 @file{HOME/.frei0r-1/lib/}, @file{/usr/local/lib/frei0r-1/},
3571 @file{/usr/lib/frei0r-1/}.
3572
3573 @item filter_params
3574 A '|'-separated list of parameters to pass to the frei0r effect.
3575
3576 @end table
3577
3578 A frei0r effect parameter can be a boolean (whose values are specified
3579 with "y" and "n"), a double, a color (specified by the syntax
3580 @var{R}/@var{G}/@var{B}, @var{R}, @var{G}, and @var{B} being float
3581 numbers from 0.0 to 1.0) or by an @code{av_parse_color()} color
3582 description), a position (specified by the syntax @var{X}/@var{Y},
3583 @var{X} and @var{Y} being float numbers) and a string.
3584
3585 The number and kind of parameters depend on the loaded effect. If an
3586 effect parameter is not specified the default value is set.
3587
3588 @subsection Examples
3589
3590 @itemize
3591 @item
3592 Apply the distort0r effect, set the first two double parameters:
3593 @example
3594 frei0r=filter_name=distort0r:filter_params=0.5|0.01
3595 @end example
3596
3597 @item
3598 Apply the colordistance effect, take a color as first parameter:
3599 @example
3600 frei0r=colordistance:0.2/0.3/0.4
3601 frei0r=colordistance:violet
3602 frei0r=colordistance:0x112233
3603 @end example
3604
3605 @item
3606 Apply the perspective effect, specify the top left and top right image
3607 positions:
3608 @example
3609 frei0r=perspective:0.2/0.2|0.8/0.2
3610 @end example
3611 @end itemize
3612
3613 For more information see:
3614 @url{http://frei0r.dyne.org}
3615
3616 @section geq
3617
3618 The filter accepts the following options:
3619
3620 @table @option
3621 @item lum_expr
3622 the luminance expression
3623 @item cb_expr
3624 the chrominance blue expression
3625 @item cr_expr
3626 the chrominance red expression
3627 @item alpha_expr
3628 the alpha expression
3629 @end table
3630
3631 If one of the chrominance expression is not defined, it falls back on the other
3632 one. If no alpha expression is specified it will evaluate to opaque value.
3633 If none of chrominance expressions are
3634 specified, they will evaluate the luminance expression.
3635
3636 The expressions can use the following variables and functions:
3637
3638 @table @option
3639 @item N
3640 The sequential number of the filtered frame, starting from @code{0}.
3641
3642 @item X
3643 @item Y
3644 The coordinates of the current sample.
3645
3646 @item W
3647 @item H
3648 The width and height of the image.
3649
3650 @item SW
3651 @item SH
3652 Width and height scale depending on the currently filtered plane. It is the
3653 ratio between the corresponding luma plane number of pixels and the current
3654 plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and
3655 @code{0.5,0.5} for chroma planes.
3656
3657 @item T
3658 Time of the current frame, expressed in seconds.
3659
3660 @item p(x, y)
3661 Return the value of the pixel at location (@var{x},@var{y}) of the current
3662 plane.
3663
3664 @item lum(x, y)
3665 Return the value of the pixel at location (@var{x},@var{y}) of the luminance
3666 plane.
3667
3668 @item cb(x, y)
3669 Return the value of the pixel at location (@var{x},@var{y}) of the
3670 blue-difference chroma plane. Returns 0 if there is no such plane.
3671
3672 @item cr(x, y)
3673 Return the value of the pixel at location (@var{x},@var{y}) of the
3674 red-difference chroma plane. Returns 0 if there is no such plane.
3675
3676 @item alpha(x, y)
3677 Return the value of the pixel at location (@var{x},@var{y}) of the alpha
3678 plane. Returns 0 if there is no such plane.
3679 @end table
3680
3681 For functions, if @var{x} and @var{y} are outside the area, the value will be
3682 automatically clipped to the closer edge.
3683
3684 @subsection Examples
3685
3686 @itemize
3687 @item
3688 Flip the image horizontally:
3689 @example
3690 geq=p(W-X\,Y)
3691 @end example
3692
3693 @item
3694 Generate a bidimensional sine wave, with angle @code{PI/3} and a
3695 wavelength of 100 pixels:
3696 @example
3697 geq=128 + 100*sin(2*(PI/100)*(cos(PI/3)*(X-50*T) + sin(PI/3)*Y)):128:128
3698 @end example
3699
3700 @item
3701 Generate a fancy enigmatic moving light:
3702 @example
3703 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
3704 @end example
3705
3706 @item
3707 Generate a quick emboss effect:
3708 @example
3709 format=gray,geq=lum_expr='(p(X,Y)+(256-p(X-4,Y-4)))/2'
3710 @end example
3711 @end itemize
3712
3713 @section gradfun
3714
3715 Fix the banding artifacts that are sometimes introduced into nearly flat
3716 regions by truncation to 8bit color depth.
3717 Interpolate the gradients that should go where the bands are, and
3718 dither them.
3719
3720 This filter is designed for playback only.  Do not use it prior to
3721 lossy compression, because compression tends to lose the dither and
3722 bring back the bands.
3723
3724 This filter accepts the following options:
3725
3726 @table @option
3727
3728 @item strength
3729 The maximum amount by which the filter will change any one pixel. Also the
3730 threshold for detecting nearly flat regions. Acceptable values range from .51 to
3731 64, default value is 1.2, out-of-range values will be clipped to the valid
3732 range.
3733
3734 @item radius
3735 The neighborhood to fit the gradient to. A larger radius makes for smoother
3736 gradients, but also prevents the filter from modifying the pixels near detailed
3737 regions. Acceptable values are 8-32, default value is 16, out-of-range values
3738 will be clipped to the valid range.
3739
3740 @end table
3741
3742 Alternatively, the options can be specified as a flat string:
3743 @var{strength}[:@var{radius}]
3744
3745 @subsection Examples
3746
3747 @itemize
3748 @item
3749 Apply the filter with a @code{3.5} strength and radius of @code{8}:
3750 @example
3751 gradfun=3.5:8
3752 @end example
3753
3754 @item
3755 Specify radius, omitting the strength (which will fall-back to the default
3756 value):
3757 @example
3758 gradfun=radius=8
3759 @end example
3760
3761 @end itemize
3762
3763 @section hflip
3764
3765 Flip the input video horizontally.
3766
3767 For example to horizontally flip the input video with @command{ffmpeg}:
3768 @example
3769 ffmpeg -i in.avi -vf "hflip" out.avi
3770 @end example
3771
3772 @section histeq
3773 This filter applies a global color histogram equalization on a
3774 per-frame basis.
3775
3776 It can be used to correct video that has a compressed range of pixel
3777 intensities.  The filter redistributes the pixel intensities to
3778 equalize their distribution across the intensity range. It may be
3779 viewed as an "automatically adjusting contrast filter". This filter is
3780 useful only for correcting degraded or poorly captured source
3781 video.
3782
3783 The filter accepts the following options:
3784
3785 @table @option
3786 @item strength
3787 Determine the amount of equalization to be applied.  As the strength
3788 is reduced, the distribution of pixel intensities more-and-more
3789 approaches that of the input frame. The value must be a float number
3790 in the range [0,1] and defaults to 0.200.
3791
3792 @item intensity
3793 Set the maximum intensity that can generated and scale the output
3794 values appropriately.  The strength should be set as desired and then
3795 the intensity can be limited if needed to avoid washing-out. The value
3796 must be a float number in the range [0,1] and defaults to 0.210.
3797
3798 @item antibanding
3799 Set the antibanding level. If enabled the filter will randomly vary
3800 the luminance of output pixels by a small amount to avoid banding of
3801 the histogram. Possible values are @code{none}, @code{weak} or
3802 @code{strong}. It defaults to @code{none}.
3803 @end table
3804
3805 @section histogram
3806
3807 Compute and draw a color distribution histogram for the input video.
3808
3809 The computed histogram is a representation of distribution of color components
3810 in an image.
3811
3812 The filter accepts the following options:
3813
3814 @table @option
3815 @item mode
3816 Set histogram mode.
3817
3818 It accepts the following values:
3819 @table @samp
3820 @item levels
3821 standard histogram that display color components distribution in an image.
3822 Displays color graph for each color component. Shows distribution
3823 of the Y, U, V, A or G, B, R components, depending on input format,
3824 in current frame. Bellow each graph is color component scale meter.
3825
3826 @item color
3827 chroma values in vectorscope, if brighter more such chroma values are
3828 distributed in an image.
3829 Displays chroma values (U/V color placement) in two dimensional graph
3830 (which is called a vectorscope). It can be used to read of the hue and
3831 saturation of the current frame. At a same time it is a histogram.
3832 The whiter a pixel in the vectorscope, the more pixels of the input frame
3833 correspond to that pixel (that is the more pixels have this chroma value).
3834 The V component is displayed on the horizontal (X) axis, with the leftmost
3835 side being V = 0 and the rightmost side being V = 255.
3836 The U component is displayed on the vertical (Y) axis, with the top
3837 representing U = 0 and the bottom representing U = 255.
3838
3839 The position of a white pixel in the graph corresponds to the chroma value
3840 of a pixel of the input clip. So the graph can be used to read of the
3841 hue (color flavor) and the saturation (the dominance of the hue in the color).
3842 As the hue of a color changes, it moves around the square. At the center of
3843 the square, the saturation is zero, which means that the corresponding pixel
3844 has no color. If you increase the amount of a specific color, while leaving
3845 the other colors unchanged, the saturation increases, and you move towards
3846 the edge of the square.
3847
3848 @item color2
3849 chroma values in vectorscope, similar as @code{color} but actual chroma values
3850 are displayed.
3851
3852 @item waveform
3853 per row/column color component graph. In row mode graph in the left side represents
3854 color component value 0 and right side represents value = 255. In column mode top
3855 side represents color component value = 0 and bottom side represents value = 255.
3856 @end table
3857 Default value is @code{levels}.
3858
3859 @item level_height
3860 Set height of level in @code{levels}. Default value is @code{200}.
3861 Allowed range is [50, 2048].
3862
3863 @item scale_height
3864 Set height of color scale in @code{levels}. Default value is @code{12}.
3865 Allowed range is [0, 40].
3866
3867 @item step
3868 Set step for @code{waveform} mode. Smaller values are useful to find out how much
3869 of same luminance values across input rows/columns are distributed.
3870 Default value is @code{10}. Allowed range is [1, 255].
3871
3872 @item waveform_mode
3873 Set mode for @code{waveform}. Can be either @code{row}, or @code{column}.
3874 Default is @code{row}.
3875
3876 @item display_mode
3877 Set display mode for @code{waveform} and @code{levels}.
3878 It accepts the following values:
3879 @table @samp
3880 @item parade
3881 Display separate graph for the color components side by side in
3882 @code{row} waveform mode or one below other in @code{column} waveform mode
3883 for @code{waveform} histogram mode. For @code{levels} histogram mode
3884 per color component graphs are placed one bellow other.
3885
3886 This display mode in @code{waveform} histogram mode makes it easy to spot
3887 color casts in the highlights and shadows of an image, by comparing the
3888 contours of the top and the bottom of each waveform.
3889 Since whites, grays, and blacks are characterized by
3890 exactly equal amounts of red, green, and blue, neutral areas of the
3891 picture should display three waveforms of roughly equal width/height.
3892 If not, the correction is easy to make by making adjustments to level the
3893 three waveforms.
3894
3895 @item overlay
3896 Presents information that's identical to that in the @code{parade}, except
3897 that the graphs representing color components are superimposed directly
3898 over one another.
3899
3900 This display mode in @code{waveform} histogram mode can make it easier to spot
3901 the relative differences or similarities in overlapping areas of the color
3902 components that are supposed to be identical, such as neutral whites, grays,
3903 or blacks.
3904 @end table
3905 Default is @code{parade}.
3906 @end table
3907
3908 @subsection Examples
3909
3910 @itemize
3911
3912 @item
3913 Calculate and draw histogram:
3914 @example
3915 ffplay -i input -vf histogram
3916 @end example
3917
3918 @end itemize
3919
3920 @section hqdn3d
3921
3922 High precision/quality 3d denoise filter. This filter aims to reduce
3923 image noise producing smooth images and making still images really
3924 still. It should enhance compressibility.
3925
3926 It accepts the following optional parameters:
3927
3928 @table @option
3929 @item luma_spatial
3930 a non-negative float number which specifies spatial luma strength,
3931 defaults to 4.0
3932
3933 @item chroma_spatial
3934 a non-negative float number which specifies spatial chroma strength,
3935 defaults to 3.0*@var{luma_spatial}/4.0
3936
3937 @item luma_tmp
3938 a float number which specifies luma temporal strength, defaults to
3939 6.0*@var{luma_spatial}/4.0
3940
3941 @item chroma_tmp
3942 a float number which specifies chroma temporal strength, defaults to
3943 @var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}
3944 @end table
3945
3946 @section hue
3947
3948 Modify the hue and/or the saturation of the input.
3949
3950 This filter accepts the following options:
3951
3952 @table @option
3953 @item h
3954 Specify the hue angle as a number of degrees. It accepts an expression,
3955 and defaults to "0".
3956
3957 @item s
3958 Specify the saturation in the [-10,10] range. It accepts a float number and
3959 defaults to "1".
3960
3961 @item H
3962 Specify the hue angle as a number of radians. It accepts a float
3963 number or an expression, and defaults to "0".
3964 @end table
3965
3966 @option{h} and @option{H} are mutually exclusive, and can't be
3967 specified at the same time.
3968
3969 The @option{h}, @option{H} and @option{s} option values are
3970 expressions containing the following constants:
3971
3972 @table @option
3973 @item n
3974 frame count of the input frame starting from 0
3975
3976 @item pts
3977 presentation timestamp of the input frame expressed in time base units
3978
3979 @item r
3980 frame rate of the input video, NAN if the input frame rate is unknown
3981
3982 @item t
3983 timestamp expressed in seconds, NAN if the input timestamp is unknown
3984
3985 @item tb
3986 time base of the input video
3987 @end table
3988
3989 @subsection Examples
3990
3991 @itemize
3992 @item
3993 Set the hue to 90 degrees and the saturation to 1.0:
3994 @example
3995 hue=h=90:s=1
3996 @end example
3997
3998 @item
3999 Same command but expressing the hue in radians:
4000 @example
4001 hue=H=PI/2:s=1
4002 @end example
4003
4004 @item
4005 Rotate hue and make the saturation swing between 0
4006 and 2 over a period of 1 second:
4007 @example
4008 hue="H=2*PI*t: s=sin(2*PI*t)+1"
4009 @end example
4010
4011 @item
4012 Apply a 3 seconds saturation fade-in effect starting at 0:
4013 @example
4014 hue="s=min(t/3\,1)"
4015 @end example
4016
4017 The general fade-in expression can be written as:
4018 @example
4019 hue="s=min(0\, max((t-START)/DURATION\, 1))"
4020 @end example
4021
4022 @item
4023 Apply a 3 seconds saturation fade-out effect starting at 5 seconds:
4024 @example
4025 hue="s=max(0\, min(1\, (8-t)/3))"
4026 @end example
4027
4028 The general fade-out expression can be written as:
4029 @example
4030 hue="s=max(0\, min(1\, (START+DURATION-t)/DURATION))"
4031 @end example
4032
4033 @end itemize
4034
4035 @subsection Commands
4036
4037 This filter supports the following commands:
4038 @table @option
4039 @item s
4040 @item h
4041 @item H
4042 Modify the hue and/or the saturation of the input video.
4043 The command accepts the same syntax of the corresponding option.
4044
4045 If the specified expression is not valid, it is kept at its current
4046 value.
4047 @end table
4048
4049 @section idet
4050
4051 Detect video interlacing type.
4052
4053 This filter tries to detect if the input is interlaced or progressive,
4054 top or bottom field first.
4055
4056 The filter accepts the following options:
4057
4058 @table @option
4059 @item intl_thres
4060 Set interlacing threshold.
4061 @item prog_thres
4062 Set progressive threshold.
4063 @end table
4064
4065 @section il
4066
4067 Deinterleave or interleave fields.
4068
4069 This filter allows to process interlaced images fields without
4070 deinterlacing them. Deinterleaving splits the input frame into 2
4071 fields (so called half pictures). Odd lines are moved to the top
4072 half of the output image, even lines to the bottom half.
4073 You can process (filter) them independently and then re-interleave them.
4074
4075 The filter accepts the following options:
4076
4077 @table @option
4078 @item luma_mode, l
4079 @item chroma_mode, s
4080 @item alpha_mode, a
4081 Available values for @var{luma_mode}, @var{chroma_mode} and
4082 @var{alpha_mode} are:
4083
4084 @table @samp
4085 @item none
4086 Do nothing.
4087
4088 @item deinterleave, d
4089 Deinterleave fields, placing one above the other.
4090
4091 @item interleave, i
4092 Interleave fields. Reverse the effect of deinterleaving.
4093 @end table
4094 Default value is @code{none}.
4095
4096 @item luma_swap, ls
4097 @item chroma_swap, cs
4098 @item alpha_swap, as
4099 Swap luma/chroma/alpha fields. Exchange even & odd lines. Default value is @code{0}.
4100 @end table
4101
4102 @section interlace
4103
4104 Simple interlacing filter from progressive contents. This interleaves upper (or
4105 lower) lines from odd frames with lower (or upper) lines from even frames,
4106 halving the frame rate and preserving image height.
4107
4108 @example
4109    Original        Original             New Frame
4110    Frame 'j'      Frame 'j+1'             (tff)
4111   ==========      ===========       ==================
4112     Line 0  -------------------->    Frame 'j' Line 0
4113     Line 1          Line 1  ---->   Frame 'j+1' Line 1
4114     Line 2 --------------------->    Frame 'j' Line 2
4115     Line 3          Line 3  ---->   Frame 'j+1' Line 3
4116      ...             ...                   ...
4117 New Frame + 1 will be generated by Frame 'j+2' and Frame 'j+3' and so on
4118 @end example
4119
4120 It accepts the following optional parameters:
4121
4122 @table @option
4123 @item scan
4124 determines whether the interlaced frame is taken from the even (tff - default)
4125 or odd (bff) lines of the progressive frame.
4126
4127 @item lowpass
4128 Enable (default) or disable the vertical lowpass filter to avoid twitter
4129 interlacing and reduce moire patterns.
4130 @end table
4131
4132 @section kerndeint
4133
4134 Deinterlace input video by applying Donald Graft's adaptive kernel
4135 deinterling. Work on interlaced parts of a video to produce
4136 progressive frames.
4137
4138 The description of the accepted parameters follows.
4139
4140 @table @option
4141 @item thresh
4142 Set the threshold which affects the filter's tolerance when
4143 determining if a pixel line must be processed. It must be an integer
4144 in the range [0,255] and defaults to 10. A value of 0 will result in
4145 applying the process on every pixels.
4146
4147 @item map
4148 Paint pixels exceeding the threshold value to white if set to 1.
4149 Default is 0.
4150
4151 @item order
4152 Set the fields order. Swap fields if set to 1, leave fields alone if
4153 0. Default is 0.
4154
4155 @item sharp
4156 Enable additional sharpening if set to 1. Default is 0.
4157
4158 @item twoway
4159 Enable twoway sharpening if set to 1. Default is 0.
4160 @end table
4161
4162 @subsection Examples
4163
4164 @itemize
4165 @item
4166 Apply default values:
4167 @example
4168 kerndeint=thresh=10:map=0:order=0:sharp=0:twoway=0
4169 @end example
4170
4171 @item
4172 Enable additional sharpening:
4173 @example
4174 kerndeint=sharp=1
4175 @end example
4176
4177 @item
4178 Paint processed pixels in white:
4179 @example
4180 kerndeint=map=1
4181 @end example
4182 @end itemize
4183
4184 @section lut, lutrgb, lutyuv
4185
4186 Compute a look-up table for binding each pixel component input value
4187 to an output value, and apply it to input video.
4188
4189 @var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb}
4190 to an RGB input video.
4191
4192 These filters accept the following options:
4193 @table @option
4194 @item c0
4195 set first pixel component expression
4196 @item c1
4197 set second pixel component expression
4198 @item c2
4199 set third pixel component expression
4200 @item c3
4201 set fourth pixel component expression, corresponds to the alpha component
4202
4203 @item r
4204 set red component expression
4205 @item g
4206 set green component expression
4207 @item b
4208 set blue component expression
4209 @item a
4210 alpha component expression
4211
4212 @item y
4213 set Y/luminance component expression
4214 @item u
4215 set U/Cb component expression
4216 @item v
4217 set V/Cr component expression
4218 @end table
4219
4220 Each of them specifies the expression to use for computing the lookup table for
4221 the corresponding pixel component values.
4222
4223 The exact component associated to each of the @var{c*} options depends on the
4224 format in input.
4225
4226 The @var{lut} filter requires either YUV or RGB pixel formats in input,
4227 @var{lutrgb} requires RGB pixel formats in input, and @var{lutyuv} requires YUV.
4228
4229 The expressions can contain the following constants and functions:
4230
4231 @table @option
4232 @item w, h
4233 the input width and height
4234
4235 @item val
4236 input value for the pixel component
4237
4238 @item clipval
4239 the input value clipped in the @var{minval}-@var{maxval} range
4240
4241 @item maxval
4242 maximum value for the pixel component
4243
4244 @item minval
4245 minimum value for the pixel component
4246
4247 @item negval
4248 the negated value for the pixel component value clipped in the
4249 @var{minval}-@var{maxval} range , it corresponds to the expression
4250 "maxval-clipval+minval"
4251
4252 @item clip(val)
4253 the computed value in @var{val} clipped in the
4254 @var{minval}-@var{maxval} range
4255
4256 @item gammaval(gamma)
4257 the computed gamma correction value of the pixel component value
4258 clipped in the @var{minval}-@var{maxval} range, corresponds to the
4259 expression
4260 "pow((clipval-minval)/(maxval-minval)\,@var{gamma})*(maxval-minval)+minval"
4261
4262 @end table
4263
4264 All expressions default to "val".
4265
4266 @subsection Examples
4267
4268 @itemize
4269 @item
4270 Negate input video:
4271 @example
4272 lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val"
4273 lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val"
4274 @end example
4275
4276 The above is the same as:
4277 @example
4278 lutrgb="r=negval:g=negval:b=negval"
4279 lutyuv="y=negval:u=negval:v=negval"
4280 @end example
4281
4282 @item
4283 Negate luminance:
4284 @example
4285 lutyuv=y=negval
4286 @end example
4287
4288 @item
4289 Remove chroma components, turns the video into a graytone image:
4290 @example
4291 lutyuv="u=128:v=128"
4292 @end example
4293
4294 @item
4295 Apply a luma burning effect:
4296 @example
4297 lutyuv="y=2*val"
4298 @end example
4299
4300 @item
4301 Remove green and blue components:
4302 @example
4303 lutrgb="g=0:b=0"
4304 @end example
4305
4306 @item
4307 Set a constant alpha channel value on input:
4308 @example
4309 format=rgba,lutrgb=a="maxval-minval/2"
4310 @end example
4311
4312 @item
4313 Correct luminance gamma by a 0.5 factor:
4314 @example
4315 lutyuv=y=gammaval(0.5)
4316 @end example
4317
4318 @item
4319 Discard least significant bits of luma:
4320 @example
4321 lutyuv=y='bitand(val, 128+64+32)'
4322 @end example
4323 @end itemize
4324
4325 @section mp
4326
4327 Apply an MPlayer filter to the input video.
4328
4329 This filter provides a wrapper around most of the filters of
4330 MPlayer/MEncoder.
4331
4332 This wrapper is considered experimental. Some of the wrapped filters
4333 may not work properly and we may drop support for them, as they will
4334 be implemented natively into FFmpeg. Thus you should avoid
4335 depending on them when writing portable scripts.
4336
4337 The filters accepts the parameters:
4338 @var{filter_name}[:=]@var{filter_params}
4339
4340 @var{filter_name} is the name of a supported MPlayer filter,
4341 @var{filter_params} is a string containing the parameters accepted by
4342 the named filter.
4343
4344 The list of the currently supported filters follows:
4345 @table @var
4346 @item dint
4347 @item down3dright
4348 @item eq2
4349 @item eq
4350 @item fil
4351 @item fspp
4352 @item ilpack
4353 @item mcdeint
4354 @item ow
4355 @item perspective
4356 @item phase
4357 @item pp7
4358 @item pullup
4359 @item qp
4360 @item sab
4361 @item softpulldown
4362 @item spp
4363 @item tinterlace
4364 @item uspp
4365 @end table
4366
4367 The parameter syntax and behavior for the listed filters are the same
4368 of the corresponding MPlayer filters. For detailed instructions check
4369 the "VIDEO FILTERS" section in the MPlayer manual.
4370
4371 @subsection Examples
4372
4373 @itemize
4374 @item
4375 Adjust gamma, brightness, contrast:
4376 @example
4377 mp=eq2=1.0:2:0.5
4378 @end example
4379 @end itemize
4380
4381 See also mplayer(1), @url{http://www.mplayerhq.hu/}.
4382
4383 @section mpdecimate
4384
4385 Drop frames that do not differ greatly from the previous frame in
4386 order to reduce frame rate.
4387
4388 The main use of this filter is for very-low-bitrate encoding
4389 (e.g. streaming over dialup modem), but it could in theory be used for
4390 fixing movies that were inverse-telecined incorrectly.
4391
4392 A description of the accepted options follows.
4393
4394 @table @option
4395 @item max
4396 Set the maximum number of consecutive frames which can be dropped (if
4397 positive), or the minimum interval between dropped frames (if
4398 negative). If the value is 0, the frame is dropped unregarding the
4399 number of previous sequentially dropped frames.
4400
4401 Default value is 0.
4402
4403 @item hi
4404 @item lo
4405 @item frac
4406 Set the dropping threshold values.
4407
4408 Values for @option{hi} and @option{lo} are for 8x8 pixel blocks and
4409 represent actual pixel value differences, so a threshold of 64
4410 corresponds to 1 unit of difference for each pixel, or the same spread
4411 out differently over the block.
4412
4413 A frame is a candidate for dropping if no 8x8 blocks differ by more
4414 than a threshold of @option{hi}, and if no more than @option{frac} blocks (1
4415 meaning the whole image) differ by more than a threshold of @option{lo}.
4416
4417 Default value for @option{hi} is 64*12, default value for @option{lo} is
4418 64*5, and default value for @option{frac} is 0.33.
4419 @end table
4420
4421
4422 @section negate
4423
4424 Negate input video.
4425
4426 This filter accepts an integer in input, if non-zero it negates the
4427 alpha component (if available). The default value in input is 0.
4428
4429 @section noformat
4430
4431 Force libavfilter not to use any of the specified pixel formats for the
4432 input to the next filter.
4433
4434 This filter accepts the following parameters:
4435 @table @option
4436
4437 @item pix_fmts
4438 A '|'-separated list of pixel format names, for example
4439 "pix_fmts=yuv420p|monow|rgb24".
4440
4441 @end table
4442
4443 @subsection Examples
4444
4445 @itemize
4446 @item
4447 Force libavfilter to use a format different from @var{yuv420p} for the
4448 input to the vflip filter:
4449 @example
4450 noformat=pix_fmts=yuv420p,vflip
4451 @end example
4452
4453 @item
4454 Convert the input video to any of the formats not contained in the list:
4455 @example
4456 noformat=yuv420p|yuv444p|yuv410p
4457 @end example
4458 @end itemize
4459
4460 @section noise
4461
4462 Add noise on video input frame.
4463
4464 The filter accepts the following options:
4465
4466 @table @option
4467 @item all_seed
4468 @item c0_seed
4469 @item c1_seed
4470 @item c2_seed
4471 @item c3_seed
4472 Set noise seed for specific pixel component or all pixel components in case
4473 of @var{all_seed}. Default value is @code{123457}.
4474
4475 @item all_strength, alls
4476 @item c0_strength, c0s
4477 @item c1_strength, c1s
4478 @item c2_strength, c2s
4479 @item c3_strength, c3s
4480 Set noise strength for specific pixel component or all pixel components in case
4481 @var{all_strength}. Default value is @code{0}. Allowed range is [0, 100].
4482
4483 @item all_flags, allf
4484 @item c0_flags, c0f
4485 @item c1_flags, c1f
4486 @item c2_flags, c2f
4487 @item c3_flags, c3f
4488 Set pixel component flags or set flags for all components if @var{all_flags}.
4489 Available values for component flags are:
4490 @table @samp
4491 @item a
4492 averaged temporal noise (smoother)
4493 @item p
4494 mix random noise with a (semi)regular pattern
4495 @item q
4496 higher quality (slightly better looking, slightly slower)
4497 @item t
4498 temporal noise (noise pattern changes between frames)
4499 @item u
4500 uniform noise (gaussian otherwise)
4501 @end table
4502 @end table
4503
4504 @subsection Examples
4505
4506 Add temporal and uniform noise to input video:
4507 @example
4508 noise=alls=20:allf=t+u
4509 @end example
4510
4511 @section null
4512
4513 Pass the video source unchanged to the output.
4514
4515 @section ocv
4516
4517 Apply video transform using libopencv.
4518
4519 To enable this filter install libopencv library and headers and
4520 configure FFmpeg with @code{--enable-libopencv}.
4521
4522 This filter accepts the following parameters:
4523
4524 @table @option
4525
4526 @item filter_name
4527 The name of the libopencv filter to apply.
4528
4529 @item filter_params
4530 The parameters to pass to the libopencv filter. If not specified the default
4531 values are assumed.
4532
4533 @end table
4534
4535 Refer to the official libopencv documentation for more precise
4536 information:
4537 @url{http://opencv.willowgarage.com/documentation/c/image_filtering.html}
4538
4539 Follows the list of supported libopencv filters.
4540
4541 @anchor{dilate}
4542 @subsection dilate
4543
4544 Dilate an image by using a specific structuring element.
4545 This filter corresponds to the libopencv function @code{cvDilate}.
4546
4547 It accepts the parameters: @var{struct_el}|@var{nb_iterations}.
4548
4549 @var{struct_el} represents a structuring element, and has the syntax:
4550 @var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape}
4551
4552 @var{cols} and @var{rows} represent the number of columns and rows of
4553 the structuring element, @var{anchor_x} and @var{anchor_y} the anchor
4554 point, and @var{shape} the shape for the structuring element, and
4555 can be one of the values "rect", "cross", "ellipse", "custom".
4556
4557 If the value for @var{shape} is "custom", it must be followed by a
4558 string of the form "=@var{filename}". The file with name
4559 @var{filename} is assumed to represent a binary image, with each
4560 printable character corresponding to a bright pixel. When a custom
4561 @var{shape} is used, @var{cols} and @var{rows} are ignored, the number
4562 or columns and rows of the read file are assumed instead.
4563
4564 The default value for @var{struct_el} is "3x3+0x0/rect".
4565
4566 @var{nb_iterations} specifies the number of times the transform is
4567 applied to the image, and defaults to 1.
4568
4569 Follow some example:
4570 @example
4571 # use the default values
4572 ocv=dilate
4573
4574 # dilate using a structuring element with a 5x5 cross, iterate two times
4575 ocv=filter_name=dilate:filter_params=5x5+2x2/cross|2
4576
4577 # read the shape from the file diamond.shape, iterate two times
4578 # the file diamond.shape may contain a pattern of characters like this:
4579 #   *
4580 #  ***
4581 # *****
4582 #  ***
4583 #   *
4584 # the specified cols and rows are ignored (but not the anchor point coordinates)
4585 ocv=dilate:0x0+2x2/custom=diamond.shape|2
4586 @end example
4587
4588 @subsection erode
4589
4590 Erode an image by using a specific structuring element.
4591 This filter corresponds to the libopencv function @code{cvErode}.
4592
4593 The filter accepts the parameters: @var{struct_el}:@var{nb_iterations},
4594 with the same syntax and semantics as the @ref{dilate} filter.
4595
4596 @subsection smooth
4597
4598 Smooth the input video.
4599
4600 The filter takes the following parameters:
4601 @var{type}|@var{param1}|@var{param2}|@var{param3}|@var{param4}.
4602
4603 @var{type} is the type of smooth filter to apply, and can be one of
4604 the following values: "blur", "blur_no_scale", "median", "gaussian",
4605 "bilateral". The default value is "gaussian".
4606
4607 @var{param1}, @var{param2}, @var{param3}, and @var{param4} are
4608 parameters whose meanings depend on smooth type. @var{param1} and
4609 @var{param2} accept integer positive values or 0, @var{param3} and
4610 @var{param4} accept float values.
4611
4612 The default value for @var{param1} is 3, the default value for the
4613 other parameters is 0.
4614
4615 These parameters correspond to the parameters assigned to the
4616 libopencv function @code{cvSmooth}.
4617
4618 @anchor{overlay}
4619 @section overlay
4620
4621 Overlay one video on top of another.
4622
4623 It takes two inputs and one output, the first input is the "main"
4624 video on which the second input is overlayed.
4625
4626 This filter accepts the following parameters:
4627
4628 A description of the accepted options follows.
4629
4630 @table @option
4631 @item x
4632 @item y
4633 Set the expression for the x and y coordinates of the overlayed video
4634 on the main video. Default value is "0" for both expressions. In case
4635 the expression is invalid, it is set to a huge value (meaning that the
4636 overlay will not be displayed within the output visible area).
4637
4638 @item enable
4639 Set the expression which enables the overlay. If the evaluation is
4640 different from 0, the overlay is displayed on top of the input
4641 frame. By default it is "1".
4642
4643 @item eval
4644 Set when the expressions for @option{x}, @option{y}, and
4645 @option{enable} are evaluated.
4646
4647 It accepts the following values:
4648 @table @samp
4649 @item init
4650 only evaluate expressions once during the filter initialization or
4651 when a command is processed
4652
4653 @item frame
4654 evaluate expressions for each incoming frame
4655 @end table
4656
4657 Default value is @samp{frame}.
4658
4659 @item shortest
4660 If set to 1, force the output to terminate when the shortest input
4661 terminates. Default value is 0.
4662
4663 @item format
4664 Set the format for the output video.
4665
4666 It accepts the following values:
4667 @table @samp
4668 @item yuv420
4669 force YUV420 output
4670
4671 @item yuv444
4672 force YUV444 output
4673
4674 @item rgb
4675 force RGB output
4676 @end table
4677
4678 Default value is @samp{yuv420}.
4679
4680 @item rgb @emph{(deprecated)}
4681 If set to 1, force the filter to accept inputs in the RGB
4682 color space. Default value is 0. This option is deprecated, use
4683 @option{format} instead.
4684
4685 @item repeatlast
4686 If set to 1, force the filter to draw the last overlay frame over the
4687 main input until the end of the stream. A value of 0 disables this
4688 behavior, which is enabled by default.
4689 @end table
4690
4691 The @option{x}, @option{y}, and @option{enable} expressions can
4692 contain the following parameters.
4693
4694 @table @option
4695 @item main_w, W
4696 @item main_h, H
4697 main input width and height
4698
4699 @item overlay_w, w
4700 @item overlay_h, h
4701 overlay input width and height
4702
4703 @item x
4704 @item y
4705 the computed values for @var{x} and @var{y}. They are evaluated for
4706 each new frame.
4707
4708 @item hsub
4709 @item vsub
4710 horizontal and vertical chroma subsample values of the output
4711 format. For example for the pixel format "yuv422p" @var{hsub} is 2 and
4712 @var{vsub} is 1.
4713
4714 @item n
4715 the number of input frame, starting from 0
4716
4717 @item pos
4718 the position in the file of the input frame, NAN if unknown
4719
4720 @item t
4721 timestamp expressed in seconds, NAN if the input timestamp is unknown
4722 @end table
4723
4724 Note that the @var{n}, @var{pos}, @var{t} variables are available only
4725 when evaluation is done @emph{per frame}, and will evaluate to NAN
4726 when @option{eval} is set to @samp{init}.
4727
4728 Be aware that frames are taken from each input video in timestamp
4729 order, hence, if their initial timestamps differ, it is a a good idea
4730 to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to
4731 have them begin in the same zero timestamp, as it does the example for
4732 the @var{movie} filter.
4733
4734 You can chain together more overlays but you should test the
4735 efficiency of such approach.
4736
4737 @subsection Commands
4738
4739 This filter supports the following commands:
4740 @table @option
4741 @item x
4742 @item y
4743 @item enable
4744 Modify the x/y and enable overlay of the overlay input.
4745 The command accepts the same syntax of the corresponding option.
4746
4747 If the specified expression is not valid, it is kept at its current
4748 value.
4749 @end table
4750
4751 @subsection Examples
4752
4753 @itemize
4754 @item
4755 Draw the overlay at 10 pixels from the bottom right corner of the main
4756 video:
4757 @example
4758 overlay=main_w-overlay_w-10:main_h-overlay_h-10
4759 @end example
4760
4761 Using named options the example above becomes:
4762 @example
4763 overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10
4764 @end example
4765
4766 @item
4767 Insert a transparent PNG logo in the bottom left corner of the input,
4768 using the @command{ffmpeg} tool with the @code{-filter_complex} option:
4769 @example
4770 ffmpeg -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output
4771 @end example
4772
4773 @item
4774 Insert 2 different transparent PNG logos (second logo on bottom
4775 right corner) using the @command{ffmpeg} tool:
4776 @example
4777 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
4778 @end example
4779
4780 @item
4781 Add a transparent color layer on top of the main video, @code{WxH}
4782 must specify the size of the main input to the overlay filter:
4783 @example
4784 color=color=red@@.3:size=WxH [over]; [in][over] overlay [out]
4785 @end example
4786
4787 @item
4788 Play an original video and a filtered version (here with the deshake
4789 filter) side by side using the @command{ffplay} tool:
4790 @example
4791 ffplay input.avi -vf 'split[a][b]; [a]pad=iw*2:ih[src]; [b]deshake[filt]; [src][filt]overlay=w'
4792 @end example
4793
4794 The above command is the same as:
4795 @example
4796 ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w'
4797 @end example
4798
4799 @item
4800 Make a sliding overlay appearing from the left to the right top part of the
4801 screen starting since time 2:
4802 @example
4803 overlay=x='if(gte(t,2), -w+(t-2)*20, NAN)':y=0
4804 @end example
4805
4806 @item
4807 Compose output by putting two input videos side to side:
4808 @example
4809 ffmpeg -i left.avi -i right.avi -filter_complex "
4810 nullsrc=size=200x100 [background];
4811 [0:v] setpts=PTS-STARTPTS, scale=100x100 [left];
4812 [1:v] setpts=PTS-STARTPTS, scale=100x100 [right];
4813 [background][left]       overlay=shortest=1       [background+left];
4814 [background+left][right] overlay=shortest=1:x=100 [left+right]
4815 "
4816 @end example
4817
4818 @item
4819 Chain several overlays in cascade:
4820 @example
4821 nullsrc=s=200x200 [bg];
4822 testsrc=s=100x100, split=4 [in0][in1][in2][in3];
4823 [in0] lutrgb=r=0, [bg]   overlay=0:0     [mid0];
4824 [in1] lutrgb=g=0, [mid0] overlay=100:0   [mid1];
4825 [in2] lutrgb=b=0, [mid1] overlay=0:100   [mid2];
4826 [in3] null,       [mid2] overlay=100:100 [out0]
4827 @end example
4828
4829 @end itemize
4830
4831 @section pad
4832
4833 Add paddings to the input image, and place the original input at the
4834 given coordinates @var{x}, @var{y}.
4835
4836 This filter accepts the following parameters:
4837
4838 @table @option
4839 @item width, w
4840 @item height, h
4841 Specify an expression for the size of the output image with the
4842 paddings added. If the value for @var{width} or @var{height} is 0, the
4843 corresponding input size is used for the output.
4844
4845 The @var{width} expression can reference the value set by the
4846 @var{height} expression, and vice versa.
4847
4848 The default value of @var{width} and @var{height} is 0.
4849
4850 @item x
4851 @item y
4852 Specify an expression for the offsets where to place the input image
4853 in the padded area with respect to the top/left border of the output
4854 image.
4855
4856 The @var{x} expression can reference the value set by the @var{y}
4857 expression, and vice versa.
4858
4859 The default value of @var{x} and @var{y} is 0.
4860
4861 @item color
4862 Specify the color of the padded area, it can be the name of a color
4863 (case insensitive match) or a 0xRRGGBB[AA] sequence.
4864
4865 The default value of @var{color} is "black".
4866 @end table
4867
4868 The value for the @var{width}, @var{height}, @var{x}, and @var{y}
4869 options are expressions containing the following constants:
4870
4871 @table @option
4872 @item in_w, in_h
4873 the input video width and height
4874
4875 @item iw, ih
4876 same as @var{in_w} and @var{in_h}
4877
4878 @item out_w, out_h
4879 the output width and height, that is the size of the padded area as
4880 specified by the @var{width} and @var{height} expressions
4881
4882 @item ow, oh
4883 same as @var{out_w} and @var{out_h}
4884
4885 @item x, y
4886 x and y offsets as specified by the @var{x} and @var{y}
4887 expressions, or NAN if not yet specified
4888
4889 @item a
4890 same as @var{iw} / @var{ih}
4891
4892 @item sar
4893 input sample aspect ratio
4894
4895 @item dar
4896 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
4897
4898 @item hsub, vsub
4899 horizontal and vertical chroma subsample values. For example for the
4900 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
4901 @end table
4902
4903 @subsection Examples
4904
4905 @itemize
4906 @item
4907 Add paddings with color "violet" to the input video. Output video
4908 size is 640x480, the top-left corner of the input video is placed at
4909 column 0, row 40:
4910 @example
4911 pad=640:480:0:40:violet
4912 @end example
4913
4914 The example above is equivalent to the following command:
4915 @example
4916 pad=width=640:height=480:x=0:y=40:color=violet
4917 @end example
4918
4919 @item
4920 Pad the input to get an output with dimensions increased by 3/2,
4921 and put the input video at the center of the padded area:
4922 @example
4923 pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2"
4924 @end example
4925
4926 @item
4927 Pad the input to get a squared output with size equal to the maximum
4928 value between the input width and height, and put the input video at
4929 the center of the padded area:
4930 @example
4931 pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2"
4932 @end example
4933
4934 @item
4935 Pad the input to get a final w/h ratio of 16:9:
4936 @example
4937 pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2"
4938 @end example
4939
4940 @item
4941 In case of anamorphic video, in order to set the output display aspect
4942 correctly, it is necessary to use @var{sar} in the expression,
4943 according to the relation:
4944 @example
4945 (ih * X / ih) * sar = output_dar
4946 X = output_dar / sar
4947 @end example
4948
4949 Thus the previous example needs to be modified to:
4950 @example
4951 pad="ih*16/9/sar:ih:(ow-iw)/2:(oh-ih)/2"
4952 @end example
4953
4954 @item
4955 Double output size and put the input video in the bottom-right
4956 corner of the output padded area:
4957 @example
4958 pad="2*iw:2*ih:ow-iw:oh-ih"
4959 @end example
4960 @end itemize
4961
4962 @section pixdesctest
4963
4964 Pixel format descriptor test filter, mainly useful for internal
4965 testing. The output video should be equal to the input video.
4966
4967 For example:
4968 @example
4969 format=monow, pixdesctest
4970 @end example
4971
4972 can be used to test the monowhite pixel format descriptor definition.
4973
4974 @section pp
4975
4976 Enable the specified chain of postprocessing subfilters using libpostproc. This
4977 library should be automatically selected with a GPL build (@code{--enable-gpl}).
4978 Subfilters must be separated by '/' and can be disabled by prepending a '-'.
4979 Each subfilter and some options have a short and a long name that can be used
4980 interchangeably, i.e. dr/dering are the same.
4981
4982 The filters accept the following options:
4983
4984 @table @option
4985 @item subfilters
4986 Set postprocessing subfilters string.
4987 @end table
4988
4989 All subfilters share common options to determine their scope:
4990
4991 @table @option
4992 @item a/autoq
4993 Honor the quality commands for this subfilter.
4994
4995 @item c/chrom
4996 Do chrominance filtering, too (default).
4997
4998 @item y/nochrom
4999 Do luminance filtering only (no chrominance).
5000
5001 @item n/noluma
5002 Do chrominance filtering only (no luminance).
5003 @end table
5004
5005 These options can be appended after the subfilter name, separated by a '|'.
5006
5007 Available subfilters are:
5008
5009 @table @option
5010 @item hb/hdeblock[|difference[|flatness]]
5011 Horizontal deblocking filter
5012 @table @option
5013 @item difference
5014 Difference factor where higher values mean more deblocking (default: @code{32}).
5015 @item flatness
5016 Flatness threshold where lower values mean more deblocking (default: @code{39}).
5017 @end table
5018
5019 @item vb/vdeblock[|difference[|flatness]]
5020 Vertical deblocking filter
5021 @table @option
5022 @item difference
5023 Difference factor where higher values mean more deblocking (default: @code{32}).
5024 @item flatness
5025 Flatness threshold where lower values mean more deblocking (default: @code{39}).
5026 @end table
5027
5028 @item ha/hadeblock[|difference[|flatness]]
5029 Accurate horizontal deblocking filter
5030 @table @option
5031 @item difference
5032 Difference factor where higher values mean more deblocking (default: @code{32}).
5033 @item flatness
5034 Flatness threshold where lower values mean more deblocking (default: @code{39}).
5035 @end table
5036
5037 @item va/vadeblock[|difference[|flatness]]
5038 Accurate vertical deblocking filter
5039 @table @option
5040 @item difference
5041 Difference factor where higher values mean more deblocking (default: @code{32}).
5042 @item flatness
5043 Flatness threshold where lower values mean more deblocking (default: @code{39}).
5044 @end table
5045 @end table
5046
5047 The horizontal and vertical deblocking filters share the difference and
5048 flatness values so you cannot set different horizontal and vertical
5049 thresholds.
5050
5051 @table @option
5052 @item h1/x1hdeblock
5053 Experimental horizontal deblocking filter
5054
5055 @item v1/x1vdeblock
5056 Experimental vertical deblocking filter
5057
5058 @item dr/dering
5059 Deringing filter
5060
5061 @item tn/tmpnoise[|threshold1[|threshold2[|threshold3]]], temporal noise reducer
5062 @table @option
5063 @item threshold1
5064 larger -> stronger filtering
5065 @item threshold2
5066 larger -> stronger filtering
5067 @item threshold3
5068 larger -> stronger filtering
5069 @end table
5070
5071 @item al/autolevels[:f/fullyrange], automatic brightness / contrast correction
5072 @table @option
5073 @item f/fullyrange
5074 Stretch luminance to @code{0-255}.
5075 @end table
5076
5077 @item lb/linblenddeint
5078 Linear blend deinterlacing filter that deinterlaces the given block by
5079 filtering all lines with a @code{(1 2 1)} filter.
5080
5081 @item li/linipoldeint
5082 Linear interpolating deinterlacing filter that deinterlaces the given block by
5083 linearly interpolating every second line.
5084
5085 @item ci/cubicipoldeint
5086 Cubic interpolating deinterlacing filter deinterlaces the given block by
5087 cubically interpolating every second line.
5088
5089 @item md/mediandeint
5090 Median deinterlacing filter that deinterlaces the given block by applying a
5091 median filter to every second line.
5092
5093 @item fd/ffmpegdeint
5094 FFmpeg deinterlacing filter that deinterlaces the given block by filtering every
5095 second line with a @code{(-1 4 2 4 -1)} filter.
5096
5097 @item l5/lowpass5
5098 Vertically applied FIR lowpass deinterlacing filter that deinterlaces the given
5099 block by filtering all lines with a @code{(-1 2 6 2 -1)} filter.
5100
5101 @item fq/forceQuant[|quantizer]
5102 Overrides the quantizer table from the input with the constant quantizer you
5103 specify.
5104 @table @option
5105 @item quantizer
5106 Quantizer to use
5107 @end table
5108
5109 @item de/default
5110 Default pp filter combination (@code{hb|a,vb|a,dr|a})
5111
5112 @item fa/fast
5113 Fast pp filter combination (@code{h1|a,v1|a,dr|a})
5114
5115 @item ac
5116 High quality pp filter combination (@code{ha|a|128|7,va|a,dr|a})
5117 @end table
5118
5119 @subsection Examples
5120
5121 @itemize
5122 @item
5123 Apply horizontal and vertical deblocking, deringing and automatic
5124 brigh