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