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