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