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