avfilter: port pullup filter from libmpcodecs
[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 adelay
351
352 Delay one or more audio channels.
353
354 Samples in delayed channel are filled with silence.
355
356 The filter accepts the following option:
357
358 @table @option
359 @item delays
360 Set list of delays in milliseconds for each channel separated by '|'.
361 At least one delay greater than 0 should be provided.
362 Unused delays will be silently ignored. If number of given delays is
363 smaller than number of channels all remaining channels will not be delayed.
364 @end table
365
366 @subsection Examples
367
368 @itemize
369 @item
370 Delay first channel by 1.5 seconds, the third channel by 0.5 seconds and leave
371 the second channel (and any other channels that may be present) unchanged.
372 @example
373 adelay=1500:0:500
374 @end example
375 @end itemize
376
377 @section aecho
378
379 Apply echoing to the input audio.
380
381 Echoes are reflected sound and can occur naturally amongst mountains
382 (and sometimes large buildings) when talking or shouting; digital echo
383 effects emulate this behaviour and are often used to help fill out the
384 sound of a single instrument or vocal. The time difference between the
385 original signal and the reflection is the @code{delay}, and the
386 loudness of the reflected signal is the @code{decay}.
387 Multiple echoes can have different delays and decays.
388
389 A description of the accepted parameters follows.
390
391 @table @option
392 @item in_gain
393 Set input gain of reflected signal. Default is @code{0.6}.
394
395 @item out_gain
396 Set output gain of reflected signal. Default is @code{0.3}.
397
398 @item delays
399 Set list of time intervals in milliseconds between original signal and reflections
400 separated by '|'. Allowed range for each @code{delay} is @code{(0 - 90000.0]}.
401 Default is @code{1000}.
402
403 @item decays
404 Set list of loudnesses of reflected signals separated by '|'.
405 Allowed range for each @code{decay} is @code{(0 - 1.0]}.
406 Default is @code{0.5}.
407 @end table
408
409 @subsection Examples
410
411 @itemize
412 @item
413 Make it sound as if there are twice as many instruments as are actually playing:
414 @example
415 aecho=0.8:0.88:60:0.4
416 @end example
417
418 @item
419 If delay is very short, then it sound like a (metallic) robot playing music:
420 @example
421 aecho=0.8:0.88:6:0.4
422 @end example
423
424 @item
425 A longer delay will sound like an open air concert in the mountains:
426 @example
427 aecho=0.8:0.9:1000:0.3
428 @end example
429
430 @item
431 Same as above but with one more mountain:
432 @example
433 aecho=0.8:0.9:1000|1800:0.3|0.25
434 @end example
435 @end itemize
436
437 @section afade
438
439 Apply fade-in/out effect to input audio.
440
441 A description of the accepted parameters follows.
442
443 @table @option
444 @item type, t
445 Specify the effect type, can be either @code{in} for fade-in, or
446 @code{out} for a fade-out effect. Default is @code{in}.
447
448 @item start_sample, ss
449 Specify the number of the start sample for starting to apply the fade
450 effect. Default is 0.
451
452 @item nb_samples, ns
453 Specify the number of samples for which the fade effect has to last. At
454 the end of the fade-in effect the output audio will have the same
455 volume as the input audio, at the end of the fade-out transition
456 the output audio will be silence. Default is 44100.
457
458 @item start_time, st
459 Specify time for starting to apply the fade effect. Default is 0.
460 The accepted syntax is:
461 @example
462 [-]HH[:MM[:SS[.m...]]]
463 [-]S+[.m...]
464 @end example
465 See also the function @code{av_parse_time()}.
466 If set this option is used instead of @var{start_sample} one.
467
468 @item duration, d
469 Specify the duration for which the fade effect has to last. Default is 0.
470 The accepted syntax is:
471 @example
472 [-]HH[:MM[:SS[.m...]]]
473 [-]S+[.m...]
474 @end example
475 See also the function @code{av_parse_time()}.
476 At the end of the fade-in effect the output audio will have the same
477 volume as the input audio, at the end of the fade-out transition
478 the output audio will be silence.
479 If set this option is used instead of @var{nb_samples} one.
480
481 @item curve
482 Set curve for fade transition.
483
484 It accepts the following values:
485 @table @option
486 @item tri
487 select triangular, linear slope (default)
488 @item qsin
489 select quarter of sine wave
490 @item hsin
491 select half of sine wave
492 @item esin
493 select exponential sine wave
494 @item log
495 select logarithmic
496 @item par
497 select inverted parabola
498 @item qua
499 select quadratic
500 @item cub
501 select cubic
502 @item squ
503 select square root
504 @item cbr
505 select cubic root
506 @end table
507 @end table
508
509 @subsection Examples
510
511 @itemize
512 @item
513 Fade in first 15 seconds of audio:
514 @example
515 afade=t=in:ss=0:d=15
516 @end example
517
518 @item
519 Fade out last 25 seconds of a 900 seconds audio:
520 @example
521 afade=t=out:st=875:d=25
522 @end example
523 @end itemize
524
525 @anchor{aformat}
526 @section aformat
527
528 Set output format constraints for the input audio. The framework will
529 negotiate the most appropriate format to minimize conversions.
530
531 The filter accepts the following named parameters:
532 @table @option
533
534 @item sample_fmts
535 A '|'-separated list of requested sample formats.
536
537 @item sample_rates
538 A '|'-separated list of requested sample rates.
539
540 @item channel_layouts
541 A '|'-separated list of requested channel layouts.
542
543 @end table
544
545 If a parameter is omitted, all values are allowed.
546
547 For example to force the output to either unsigned 8-bit or signed 16-bit stereo:
548 @example
549 aformat=sample_fmts=u8|s16:channel_layouts=stereo
550 @end example
551
552 @section allpass
553
554 Apply a two-pole all-pass filter with central frequency (in Hz)
555 @var{frequency}, and filter-width @var{width}.
556 An all-pass filter changes the audio's frequency to phase relationship
557 without changing its frequency to amplitude relationship.
558
559 The filter accepts the following options:
560
561 @table @option
562 @item frequency, f
563 Set frequency in Hz.
564
565 @item width_type
566 Set method to specify band-width of filter.
567 @table @option
568 @item h
569 Hz
570 @item q
571 Q-Factor
572 @item o
573 octave
574 @item s
575 slope
576 @end table
577
578 @item width, w
579 Specify the band-width of a filter in width_type units.
580 @end table
581
582 @section amerge
583
584 Merge two or more audio streams into a single multi-channel stream.
585
586 The filter accepts the following options:
587
588 @table @option
589
590 @item inputs
591 Set the number of inputs. Default is 2.
592
593 @end table
594
595 If the channel layouts of the inputs are disjoint, and therefore compatible,
596 the channel layout of the output will be set accordingly and the channels
597 will be reordered as necessary. If the channel layouts of the inputs are not
598 disjoint, the output will have all the channels of the first input then all
599 the channels of the second input, in that order, and the channel layout of
600 the output will be the default value corresponding to the total number of
601 channels.
602
603 For example, if the first input is in 2.1 (FL+FR+LF) and the second input
604 is FC+BL+BR, then the output will be in 5.1, with the channels in the
605 following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the
606 first input, b1 is the first channel of the second input).
607
608 On the other hand, if both input are in stereo, the output channels will be
609 in the default order: a1, a2, b1, b2, and the channel layout will be
610 arbitrarily set to 4.0, which may or may not be the expected value.
611
612 All inputs must have the same sample rate, and format.
613
614 If inputs do not have the same duration, the output will stop with the
615 shortest.
616
617 @subsection Examples
618
619 @itemize
620 @item
621 Merge two mono files into a stereo stream:
622 @example
623 amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge
624 @end example
625
626 @item
627 Multiple merges assuming 1 video stream and 6 audio streams in @file{input.mkv}:
628 @example
629 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
630 @end example
631 @end itemize
632
633 @section amix
634
635 Mixes multiple audio inputs into a single output.
636
637 For example
638 @example
639 ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT
640 @end example
641 will mix 3 input audio streams to a single output with the same duration as the
642 first input and a dropout transition time of 3 seconds.
643
644 The filter accepts the following named parameters:
645 @table @option
646
647 @item inputs
648 Number of inputs. If unspecified, it defaults to 2.
649
650 @item duration
651 How to determine the end-of-stream.
652 @table @option
653
654 @item longest
655 Duration of longest input. (default)
656
657 @item shortest
658 Duration of shortest input.
659
660 @item first
661 Duration of first input.
662
663 @end table
664
665 @item dropout_transition
666 Transition time, in seconds, for volume renormalization when an input
667 stream ends. The default value is 2 seconds.
668
669 @end table
670
671 @section anull
672
673 Pass the audio source unchanged to the output.
674
675 @section apad
676
677 Pad the end of a audio stream with silence, this can be used together with
678 -shortest to extend audio streams to the same length as the video stream.
679
680 @section aphaser
681 Add a phasing effect to the input audio.
682
683 A phaser filter creates series of peaks and troughs in the frequency spectrum.
684 The position of the peaks and troughs are modulated so that they vary over time, creating a sweeping effect.
685
686 A description of the accepted parameters follows.
687
688 @table @option
689 @item in_gain
690 Set input gain. Default is 0.4.
691
692 @item out_gain
693 Set output gain. Default is 0.74
694
695 @item delay
696 Set delay in milliseconds. Default is 3.0.
697
698 @item decay
699 Set decay. Default is 0.4.
700
701 @item speed
702 Set modulation speed in Hz. Default is 0.5.
703
704 @item type
705 Set modulation type. Default is triangular.
706
707 It accepts the following values:
708 @table @samp
709 @item triangular, t
710 @item sinusoidal, s
711 @end table
712 @end table
713
714 @anchor{aresample}
715 @section aresample
716
717 Resample the input audio to the specified parameters, using the
718 libswresample library. If none are specified then the filter will
719 automatically convert between its input and output.
720
721 This filter is also able to stretch/squeeze the audio data to make it match
722 the timestamps or to inject silence / cut out audio to make it match the
723 timestamps, do a combination of both or do neither.
724
725 The filter accepts the syntax
726 [@var{sample_rate}:]@var{resampler_options}, where @var{sample_rate}
727 expresses a sample rate and @var{resampler_options} is a list of
728 @var{key}=@var{value} pairs, separated by ":". See the
729 ffmpeg-resampler manual for the complete list of supported options.
730
731 @subsection Examples
732
733 @itemize
734 @item
735 Resample the input audio to 44100Hz:
736 @example
737 aresample=44100
738 @end example
739
740 @item
741 Stretch/squeeze samples to the given timestamps, with a maximum of 1000
742 samples per second compensation:
743 @example
744 aresample=async=1000
745 @end example
746 @end itemize
747
748 @section asetnsamples
749
750 Set the number of samples per each output audio frame.
751
752 The last output packet may contain a different number of samples, as
753 the filter will flush all the remaining samples when the input audio
754 signal its end.
755
756 The filter accepts the following options:
757
758 @table @option
759
760 @item nb_out_samples, n
761 Set the number of frames per each output audio frame. The number is
762 intended as the number of samples @emph{per each channel}.
763 Default value is 1024.
764
765 @item pad, p
766 If set to 1, the filter will pad the last audio frame with zeroes, so
767 that the last frame will contain the same number of samples as the
768 previous ones. Default value is 1.
769 @end table
770
771 For example, to set the number of per-frame samples to 1234 and
772 disable padding for the last frame, use:
773 @example
774 asetnsamples=n=1234:p=0
775 @end example
776
777 @section asetrate
778
779 Set the sample rate without altering the PCM data.
780 This will result in a change of speed and pitch.
781
782 The filter accepts the following options:
783
784 @table @option
785 @item sample_rate, r
786 Set the output sample rate. Default is 44100 Hz.
787 @end table
788
789 @section ashowinfo
790
791 Show a line containing various information for each input audio frame.
792 The input audio is not modified.
793
794 The shown line contains a sequence of key/value pairs of the form
795 @var{key}:@var{value}.
796
797 A description of each shown parameter follows:
798
799 @table @option
800 @item n
801 sequential number of the input frame, starting from 0
802
803 @item pts
804 Presentation timestamp of the input frame, in time base units; the time base
805 depends on the filter input pad, and is usually 1/@var{sample_rate}.
806
807 @item pts_time
808 presentation timestamp of the input frame in seconds
809
810 @item pos
811 position of the frame in the input stream, -1 if this information in
812 unavailable and/or meaningless (for example in case of synthetic audio)
813
814 @item fmt
815 sample format
816
817 @item chlayout
818 channel layout
819
820 @item rate
821 sample rate for the audio frame
822
823 @item nb_samples
824 number of samples (per channel) in the frame
825
826 @item checksum
827 Adler-32 checksum (printed in hexadecimal) of the audio data. For planar audio
828 the data is treated as if all the planes were concatenated.
829
830 @item plane_checksums
831 A list of Adler-32 checksums for each data plane.
832 @end table
833
834 @section astats
835
836 Display time domain statistical information about the audio channels.
837 Statistics are calculated and displayed for each audio channel and,
838 where applicable, an overall figure is also given.
839
840 The filter accepts the following option:
841 @table @option
842 @item length
843 Short window length in seconds, used for peak and trough RMS measurement.
844 Default is @code{0.05} (50 miliseconds). Allowed range is @code{[0.1 - 10]}.
845 @end table
846
847 A description of each shown parameter follows:
848
849 @table @option
850 @item DC offset
851 Mean amplitude displacement from zero.
852
853 @item Min level
854 Minimal sample level.
855
856 @item Max level
857 Maximal sample level.
858
859 @item Peak level dB
860 @item RMS level dB
861 Standard peak and RMS level measured in dBFS.
862
863 @item RMS peak dB
864 @item RMS trough dB
865 Peak and trough values for RMS level measured over a short window.
866
867 @item Crest factor
868 Standard ratio of peak to RMS level (note: not in dB).
869
870 @item Flat factor
871 Flatness (i.e. consecutive samples with the same value) of the signal at its peak levels
872 (i.e. either @var{Min level} or @var{Max level}).
873
874 @item Peak count
875 Number of occasions (not the number of samples) that the signal attained either
876 @var{Min level} or @var{Max level}.
877 @end table
878
879 @section astreamsync
880
881 Forward two audio streams and control the order the buffers are forwarded.
882
883 The filter accepts the following options:
884
885 @table @option
886 @item expr, e
887 Set the expression deciding which stream should be
888 forwarded next: if the result is negative, the first stream is forwarded; if
889 the result is positive or zero, the second stream is forwarded. It can use
890 the following variables:
891
892 @table @var
893 @item b1 b2
894 number of buffers forwarded so far on each stream
895 @item s1 s2
896 number of samples forwarded so far on each stream
897 @item t1 t2
898 current timestamp of each stream
899 @end table
900
901 The default value is @code{t1-t2}, which means to always forward the stream
902 that has a smaller timestamp.
903 @end table
904
905 @subsection Examples
906
907 Stress-test @code{amerge} by randomly sending buffers on the wrong
908 input, while avoiding too much of a desynchronization:
909 @example
910 amovie=file.ogg [a] ; amovie=file.mp3 [b] ;
911 [a] [b] astreamsync=(2*random(1))-1+tanh(5*(t1-t2)) [a2] [b2] ;
912 [a2] [b2] amerge
913 @end example
914
915 @section asyncts
916
917 Synchronize audio data with timestamps by squeezing/stretching it and/or
918 dropping samples/adding silence when needed.
919
920 This filter is not built by default, please use @ref{aresample} to do squeezing/stretching.
921
922 The filter accepts the following named parameters:
923 @table @option
924
925 @item compensate
926 Enable stretching/squeezing the data to make it match the timestamps. Disabled
927 by default. When disabled, time gaps are covered with silence.
928
929 @item min_delta
930 Minimum difference between timestamps and audio data (in seconds) to trigger
931 adding/dropping samples. Default value is 0.1. If you get non-perfect sync with
932 this filter, try setting this parameter to 0.
933
934 @item max_comp
935 Maximum compensation in samples per second. Relevant only with compensate=1.
936 Default value 500.
937
938 @item first_pts
939 Assume the first pts should be this value. The time base is 1 / sample rate.
940 This allows for padding/trimming at the start of stream. By default, no
941 assumption is made about the first frame's expected pts, so no padding or
942 trimming is done. For example, this could be set to 0 to pad the beginning with
943 silence if an audio stream starts after the video stream or to trim any samples
944 with a negative pts due to encoder delay.
945
946 @end table
947
948 @section atempo
949
950 Adjust audio tempo.
951
952 The filter accepts exactly one parameter, the audio tempo. If not
953 specified then the filter will assume nominal 1.0 tempo. Tempo must
954 be in the [0.5, 2.0] range.
955
956 @subsection Examples
957
958 @itemize
959 @item
960 Slow down audio to 80% tempo:
961 @example
962 atempo=0.8
963 @end example
964
965 @item
966 To speed up audio to 125% tempo:
967 @example
968 atempo=1.25
969 @end example
970 @end itemize
971
972 @section atrim
973
974 Trim the input so that the output contains one continuous subpart of the input.
975
976 This filter accepts the following options:
977 @table @option
978 @item start
979 Specify time of the start of the kept section, i.e. the audio sample
980 with the timestamp @var{start} will be the first sample in the output.
981
982 @item end
983 Specify time of the first audio sample that will be dropped, i.e. the
984 audio sample immediately preceding the one with the timestamp @var{end} will be
985 the last sample in the output.
986
987 @item start_pts
988 Same as @var{start}, except this option sets the start timestamp in samples
989 instead of seconds.
990
991 @item end_pts
992 Same as @var{end}, except this option sets the end timestamp in samples instead
993 of seconds.
994
995 @item duration
996 Specify maximum duration of the output.
997
998 @item start_sample
999 Number of the first sample that should be passed to output.
1000
1001 @item end_sample
1002 Number of the first sample that should be dropped.
1003 @end table
1004
1005 @option{start}, @option{end}, @option{duration} are expressed as time
1006 duration specifications, check the "Time duration" section in the
1007 ffmpeg-utils manual.
1008
1009 Note that the first two sets of the start/end options and the @option{duration}
1010 option look at the frame timestamp, while the _sample options simply count the
1011 samples that pass through the filter. So start/end_pts and start/end_sample will
1012 give different results when the timestamps are wrong, inexact or do not start at
1013 zero. Also note that this filter does not modify the timestamps. If you wish
1014 that the output timestamps start at zero, insert the asetpts filter after the
1015 atrim filter.
1016
1017 If multiple start or end options are set, this filter tries to be greedy and
1018 keep all samples that match at least one of the specified constraints. To keep
1019 only the part that matches all the constraints at once, chain multiple atrim
1020 filters.
1021
1022 The defaults are such that all the input is kept. So it is possible to set e.g.
1023 just the end values to keep everything before the specified time.
1024
1025 Examples:
1026 @itemize
1027 @item
1028 drop everything except the second minute of input
1029 @example
1030 ffmpeg -i INPUT -af atrim=60:120
1031 @end example
1032
1033 @item
1034 keep only the first 1000 samples
1035 @example
1036 ffmpeg -i INPUT -af atrim=end_sample=1000
1037 @end example
1038
1039 @end itemize
1040
1041 @section bandpass
1042
1043 Apply a two-pole Butterworth band-pass filter with central
1044 frequency @var{frequency}, and (3dB-point) band-width width.
1045 The @var{csg} option selects a constant skirt gain (peak gain = Q)
1046 instead of the default: constant 0dB peak gain.
1047 The filter roll off at 6dB per octave (20dB per decade).
1048
1049 The filter accepts the following options:
1050
1051 @table @option
1052 @item frequency, f
1053 Set the filter's central frequency. Default is @code{3000}.
1054
1055 @item csg
1056 Constant skirt gain if set to 1. Defaults to 0.
1057
1058 @item width_type
1059 Set method to specify band-width of filter.
1060 @table @option
1061 @item h
1062 Hz
1063 @item q
1064 Q-Factor
1065 @item o
1066 octave
1067 @item s
1068 slope
1069 @end table
1070
1071 @item width, w
1072 Specify the band-width of a filter in width_type units.
1073 @end table
1074
1075 @section bandreject
1076
1077 Apply a two-pole Butterworth band-reject filter with central
1078 frequency @var{frequency}, and (3dB-point) band-width @var{width}.
1079 The filter roll off at 6dB per octave (20dB per decade).
1080
1081 The filter accepts the following options:
1082
1083 @table @option
1084 @item frequency, f
1085 Set the filter's central frequency. Default is @code{3000}.
1086
1087 @item width_type
1088 Set method to specify band-width of filter.
1089 @table @option
1090 @item h
1091 Hz
1092 @item q
1093 Q-Factor
1094 @item o
1095 octave
1096 @item s
1097 slope
1098 @end table
1099
1100 @item width, w
1101 Specify the band-width of a filter in width_type units.
1102 @end table
1103
1104 @section bass
1105
1106 Boost or cut the bass (lower) frequencies of the audio using a two-pole
1107 shelving filter with a response similar to that of a standard
1108 hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
1109
1110 The filter accepts the following options:
1111
1112 @table @option
1113 @item gain, g
1114 Give the gain at 0 Hz. Its useful range is about -20
1115 (for a large cut) to +20 (for a large boost).
1116 Beware of clipping when using a positive gain.
1117
1118 @item frequency, f
1119 Set the filter's central frequency and so can be used
1120 to extend or reduce the frequency range to be boosted or cut.
1121 The default value is @code{100} Hz.
1122
1123 @item width_type
1124 Set method to specify band-width of filter.
1125 @table @option
1126 @item h
1127 Hz
1128 @item q
1129 Q-Factor
1130 @item o
1131 octave
1132 @item s
1133 slope
1134 @end table
1135
1136 @item width, w
1137 Determine how steep is the filter's shelf transition.
1138 @end table
1139
1140 @section biquad
1141
1142 Apply a biquad IIR filter with the given coefficients.
1143 Where @var{b0}, @var{b1}, @var{b2} and @var{a0}, @var{a1}, @var{a2}
1144 are the numerator and denominator coefficients respectively.
1145
1146 @section channelmap
1147
1148 Remap input channels to new locations.
1149
1150 This filter accepts the following named parameters:
1151 @table @option
1152 @item channel_layout
1153 Channel layout of the output stream.
1154
1155 @item map
1156 Map channels from input to output. The argument is a '|'-separated list of
1157 mappings, each in the @code{@var{in_channel}-@var{out_channel}} or
1158 @var{in_channel} form. @var{in_channel} can be either the name of the input
1159 channel (e.g. FL for front left) or its index in the input channel layout.
1160 @var{out_channel} is the name of the output channel or its index in the output
1161 channel layout. If @var{out_channel} is not given then it is implicitly an
1162 index, starting with zero and increasing by one for each mapping.
1163 @end table
1164
1165 If no mapping is present, the filter will implicitly map input channels to
1166 output channels preserving index.
1167
1168 For example, assuming a 5.1+downmix input MOV file
1169 @example
1170 ffmpeg -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav
1171 @end example
1172 will create an output WAV file tagged as stereo from the downmix channels of
1173 the input.
1174
1175 To fix a 5.1 WAV improperly encoded in AAC's native channel order
1176 @example
1177 ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:channel_layout=5.1' out.wav
1178 @end example
1179
1180 @section channelsplit
1181
1182 Split each channel in input audio stream into a separate output stream.
1183
1184 This filter accepts the following named parameters:
1185 @table @option
1186 @item channel_layout
1187 Channel layout of the input stream. Default is "stereo".
1188 @end table
1189
1190 For example, assuming a stereo input MP3 file
1191 @example
1192 ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv
1193 @end example
1194 will create an output Matroska file with two audio streams, one containing only
1195 the left channel and the other the right channel.
1196
1197 To split a 5.1 WAV file into per-channel files
1198 @example
1199 ffmpeg -i in.wav -filter_complex
1200 'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]'
1201 -map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]'
1202 front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]'
1203 side_right.wav
1204 @end example
1205
1206 @section compand
1207
1208 Compress or expand audio dynamic range.
1209
1210 A description of the accepted options follows.
1211
1212 @table @option
1213 @item attacks
1214 @item decays
1215 Set list of times in seconds for each channel over which the instantaneous
1216 level of the input signal is averaged to determine its volume.
1217 @option{attacks} refers to increase of volume and @option{decays} refers
1218 to decrease of volume.
1219 For most situations, the attack time (response to the audio getting louder)
1220 should be shorter than the decay time because the human ear is more sensitive
1221 to sudden loud audio than sudden soft audio.
1222 Typical value for attack is @code{0.3} seconds and for decay @code{0.8}
1223 seconds.
1224
1225 @item points
1226 Set list of points for transfer function, specified in dB relative to maximum
1227 possible signal amplitude.
1228 Each key points list need to be defined using the following syntax:
1229 @code{x0/y0 x1/y1 x2/y2 ...}.
1230
1231 The input values must be in strictly increasing order but the transfer
1232 function does not have to be monotonically rising.
1233 The point @code{0/0} is assumed but may be overridden (by @code{0/out-dBn}).
1234 Typical values for the transfer function are @code{-70/-70 -60/-20}.
1235
1236 @item soft-knee
1237 Set amount for which the points at where adjacent line segments on the
1238 transfer function meet will be rounded. Defaults is @code{0.01}.
1239
1240 @item gain
1241 Set additional gain in dB to be applied at all points on the transfer function
1242 and allows easy adjustment of the overall gain.
1243 Default is @code{0}.
1244
1245 @item volume
1246 Set initial volume in dB to be assumed for each channel when filtering starts.
1247 This permits the user to supply a nominal level initially, so that,
1248 for example, a very large gain is not applied to initial signal levels before
1249 the companding has begun to operate. A typical value for audio which is
1250 initially quiet is -90 dB. Default is @code{0}.
1251
1252 @item delay
1253 Set delay in seconds. Default is @code{0}. The input audio
1254 is analysed immediately, but audio is delayed before being fed to the
1255 volume adjuster. Specifying a delay approximately equal to the attack/decay
1256 times allows the filter to effectively operate in predictive rather than
1257 reactive mode.
1258 @end table
1259
1260 @subsection Examples
1261 @itemize
1262 @item
1263 Make music with both quiet and loud passages suitable for listening
1264 in a noisy environment:
1265 @example
1266 compand=.3 .3:1 1:-90/-60 -60/-40 -40/-30 -20/-20:6:0:-90:0.2
1267 @end example
1268
1269 @item
1270 Noise-gate for when the noise is at a lower level than the signal:
1271 @example
1272 compand=.1 .1:.2 .2:-900/-900 -50.1/-900 -50/-50:.01:0:-90:.1
1273 @end example
1274
1275 @item
1276 Here is another noise-gate, this time for when the noise is at a higher level
1277 than the signal (making it, in some ways, similar to squelch):
1278 @example
1279 compand=.1 .1:.1 .1:-45.1/-45.1 -45/-900 0/-900:.01:45:-90:.1
1280 @end example
1281 @end itemize
1282
1283 @section earwax
1284
1285 Make audio easier to listen to on headphones.
1286
1287 This filter adds `cues' to 44.1kHz stereo (i.e. audio CD format) audio
1288 so that when listened to on headphones the stereo image is moved from
1289 inside your head (standard for headphones) to outside and in front of
1290 the listener (standard for speakers).
1291
1292 Ported from SoX.
1293
1294 @section equalizer
1295
1296 Apply a two-pole peaking equalisation (EQ) filter. With this
1297 filter, the signal-level at and around a selected frequency can
1298 be increased or decreased, whilst (unlike bandpass and bandreject
1299 filters) that at all other frequencies is unchanged.
1300
1301 In order to produce complex equalisation curves, this filter can
1302 be given several times, each with a different central frequency.
1303
1304 The filter accepts the following options:
1305
1306 @table @option
1307 @item frequency, f
1308 Set the filter's central frequency in Hz.
1309
1310 @item width_type
1311 Set method to specify band-width of filter.
1312 @table @option
1313 @item h
1314 Hz
1315 @item q
1316 Q-Factor
1317 @item o
1318 octave
1319 @item s
1320 slope
1321 @end table
1322
1323 @item width, w
1324 Specify the band-width of a filter in width_type units.
1325
1326 @item gain, g
1327 Set the required gain or attenuation in dB.
1328 Beware of clipping when using a positive gain.
1329 @end table
1330
1331 @section highpass
1332
1333 Apply a high-pass filter with 3dB point frequency.
1334 The filter can be either single-pole, or double-pole (the default).
1335 The filter roll off at 6dB per pole per octave (20dB per pole per decade).
1336
1337 The filter accepts the following options:
1338
1339 @table @option
1340 @item frequency, f
1341 Set frequency in Hz. Default is 3000.
1342
1343 @item poles, p
1344 Set number of poles. Default is 2.
1345
1346 @item width_type
1347 Set method to specify band-width of filter.
1348 @table @option
1349 @item h
1350 Hz
1351 @item q
1352 Q-Factor
1353 @item o
1354 octave
1355 @item s
1356 slope
1357 @end table
1358
1359 @item width, w
1360 Specify the band-width of a filter in width_type units.
1361 Applies only to double-pole filter.
1362 The default is 0.707q and gives a Butterworth response.
1363 @end table
1364
1365 @section join
1366
1367 Join multiple input streams into one multi-channel stream.
1368
1369 The filter accepts the following named parameters:
1370 @table @option
1371
1372 @item inputs
1373 Number of input streams. Defaults to 2.
1374
1375 @item channel_layout
1376 Desired output channel layout. Defaults to stereo.
1377
1378 @item map
1379 Map channels from inputs to output. The argument is a '|'-separated list of
1380 mappings, each in the @code{@var{input_idx}.@var{in_channel}-@var{out_channel}}
1381 form. @var{input_idx} is the 0-based index of the input stream. @var{in_channel}
1382 can be either the name of the input channel (e.g. FL for front left) or its
1383 index in the specified input stream. @var{out_channel} is the name of the output
1384 channel.
1385 @end table
1386
1387 The filter will attempt to guess the mappings when those are not specified
1388 explicitly. It does so by first trying to find an unused matching input channel
1389 and if that fails it picks the first unused input channel.
1390
1391 E.g. to join 3 inputs (with properly set channel layouts)
1392 @example
1393 ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT
1394 @end example
1395
1396 To build a 5.1 output from 6 single-channel streams:
1397 @example
1398 ffmpeg -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex
1399 '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'
1400 out
1401 @end example
1402
1403 @section lowpass
1404
1405 Apply a low-pass filter with 3dB point frequency.
1406 The filter can be either single-pole or double-pole (the default).
1407 The filter roll off at 6dB per pole per octave (20dB per pole per decade).
1408
1409 The filter accepts the following options:
1410
1411 @table @option
1412 @item frequency, f
1413 Set frequency in Hz. Default is 500.
1414
1415 @item poles, p
1416 Set number of poles. Default is 2.
1417
1418 @item width_type
1419 Set method to specify band-width of filter.
1420 @table @option
1421 @item h
1422 Hz
1423 @item q
1424 Q-Factor
1425 @item o
1426 octave
1427 @item s
1428 slope
1429 @end table
1430
1431 @item width, w
1432 Specify the band-width of a filter in width_type units.
1433 Applies only to double-pole filter.
1434 The default is 0.707q and gives a Butterworth response.
1435 @end table
1436
1437 @section pan
1438
1439 Mix channels with specific gain levels. The filter accepts the output
1440 channel layout followed by a set of channels definitions.
1441
1442 This filter is also designed to remap efficiently the channels of an audio
1443 stream.
1444
1445 The filter accepts parameters of the form:
1446 "@var{l}:@var{outdef}:@var{outdef}:..."
1447
1448 @table @option
1449 @item l
1450 output channel layout or number of channels
1451
1452 @item outdef
1453 output channel specification, of the form:
1454 "@var{out_name}=[@var{gain}*]@var{in_name}[+[@var{gain}*]@var{in_name}...]"
1455
1456 @item out_name
1457 output channel to define, either a channel name (FL, FR, etc.) or a channel
1458 number (c0, c1, etc.)
1459
1460 @item gain
1461 multiplicative coefficient for the channel, 1 leaving the volume unchanged
1462
1463 @item in_name
1464 input channel to use, see out_name for details; it is not possible to mix
1465 named and numbered input channels
1466 @end table
1467
1468 If the `=' in a channel specification is replaced by `<', then the gains for
1469 that specification will be renormalized so that the total is 1, thus
1470 avoiding clipping noise.
1471
1472 @subsection Mixing examples
1473
1474 For example, if you want to down-mix from stereo to mono, but with a bigger
1475 factor for the left channel:
1476 @example
1477 pan=1:c0=0.9*c0+0.1*c1
1478 @end example
1479
1480 A customized down-mix to stereo that works automatically for 3-, 4-, 5- and
1481 7-channels surround:
1482 @example
1483 pan=stereo: FL < FL + 0.5*FC + 0.6*BL + 0.6*SL : FR < FR + 0.5*FC + 0.6*BR + 0.6*SR
1484 @end example
1485
1486 Note that @command{ffmpeg} integrates a default down-mix (and up-mix) system
1487 that should be preferred (see "-ac" option) unless you have very specific
1488 needs.
1489
1490 @subsection Remapping examples
1491
1492 The channel remapping will be effective if, and only if:
1493
1494 @itemize
1495 @item gain coefficients are zeroes or ones,
1496 @item only one input per channel output,
1497 @end itemize
1498
1499 If all these conditions are satisfied, the filter will notify the user ("Pure
1500 channel mapping detected"), and use an optimized and lossless method to do the
1501 remapping.
1502
1503 For example, if you have a 5.1 source and want a stereo audio stream by
1504 dropping the extra channels:
1505 @example
1506 pan="stereo: c0=FL : c1=FR"
1507 @end example
1508
1509 Given the same source, you can also switch front left and front right channels
1510 and keep the input channel layout:
1511 @example
1512 pan="5.1: c0=c1 : c1=c0 : c2=c2 : c3=c3 : c4=c4 : c5=c5"
1513 @end example
1514
1515 If the input is a stereo audio stream, you can mute the front left channel (and
1516 still keep the stereo channel layout) with:
1517 @example
1518 pan="stereo:c1=c1"
1519 @end example
1520
1521 Still with a stereo audio stream input, you can copy the right channel in both
1522 front left and right:
1523 @example
1524 pan="stereo: c0=FR : c1=FR"
1525 @end example
1526
1527 @section resample
1528
1529 Convert the audio sample format, sample rate and channel layout. This filter is
1530 not meant to be used directly.
1531
1532 @section silencedetect
1533
1534 Detect silence in an audio stream.
1535
1536 This filter logs a message when it detects that the input audio volume is less
1537 or equal to a noise tolerance value for a duration greater or equal to the
1538 minimum detected noise duration.
1539
1540 The printed times and duration are expressed in seconds.
1541
1542 The filter accepts the following options:
1543
1544 @table @option
1545 @item duration, d
1546 Set silence duration until notification (default is 2 seconds).
1547
1548 @item noise, n
1549 Set noise tolerance. Can be specified in dB (in case "dB" is appended to the
1550 specified value) or amplitude ratio. Default is -60dB, or 0.001.
1551 @end table
1552
1553 @subsection Examples
1554
1555 @itemize
1556 @item
1557 Detect 5 seconds of silence with -50dB noise tolerance:
1558 @example
1559 silencedetect=n=-50dB:d=5
1560 @end example
1561
1562 @item
1563 Complete example with @command{ffmpeg} to detect silence with 0.0001 noise
1564 tolerance in @file{silence.mp3}:
1565 @example
1566 ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null -
1567 @end example
1568 @end itemize
1569
1570 @section treble
1571
1572 Boost or cut treble (upper) frequencies of the audio using a two-pole
1573 shelving filter with a response similar to that of a standard
1574 hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
1575
1576 The filter accepts the following options:
1577
1578 @table @option
1579 @item gain, g
1580 Give the gain at whichever is the lower of ~22 kHz and the
1581 Nyquist frequency. Its useful range is about -20 (for a large cut)
1582 to +20 (for a large boost). Beware of clipping when using a positive gain.
1583
1584 @item frequency, f
1585 Set the filter's central frequency and so can be used
1586 to extend or reduce the frequency range to be boosted or cut.
1587 The default value is @code{3000} Hz.
1588
1589 @item width_type
1590 Set method to specify band-width of filter.
1591 @table @option
1592 @item h
1593 Hz
1594 @item q
1595 Q-Factor
1596 @item o
1597 octave
1598 @item s
1599 slope
1600 @end table
1601
1602 @item width, w
1603 Determine how steep is the filter's shelf transition.
1604 @end table
1605
1606 @section volume
1607
1608 Adjust the input audio volume.
1609
1610 The filter accepts the following options:
1611
1612 @table @option
1613
1614 @item volume
1615 Expresses how the audio volume will be increased or decreased.
1616
1617 Output values are clipped to the maximum value.
1618
1619 The output audio volume is given by the relation:
1620 @example
1621 @var{output_volume} = @var{volume} * @var{input_volume}
1622 @end example
1623
1624 Default value for @var{volume} is 1.0.
1625
1626 @item precision
1627 Set the mathematical precision.
1628
1629 This determines which input sample formats will be allowed, which affects the
1630 precision of the volume scaling.
1631
1632 @table @option
1633 @item fixed
1634 8-bit fixed-point; limits input sample format to U8, S16, and S32.
1635 @item float
1636 32-bit floating-point; limits input sample format to FLT. (default)
1637 @item double
1638 64-bit floating-point; limits input sample format to DBL.
1639 @end table
1640 @end table
1641
1642 @subsection Examples
1643
1644 @itemize
1645 @item
1646 Halve the input audio volume:
1647 @example
1648 volume=volume=0.5
1649 volume=volume=1/2
1650 volume=volume=-6.0206dB
1651 @end example
1652
1653 In all the above example the named key for @option{volume} can be
1654 omitted, for example like in:
1655 @example
1656 volume=0.5
1657 @end example
1658
1659 @item
1660 Increase input audio power by 6 decibels using fixed-point precision:
1661 @example
1662 volume=volume=6dB:precision=fixed
1663 @end example
1664 @end itemize
1665
1666 @section volumedetect
1667
1668 Detect the volume of the input video.
1669
1670 The filter has no parameters. The input is not modified. Statistics about
1671 the volume will be printed in the log when the input stream end is reached.
1672
1673 In particular it will show the mean volume (root mean square), maximum
1674 volume (on a per-sample basis), and the beginning of a histogram of the
1675 registered volume values (from the maximum value to a cumulated 1/1000 of
1676 the samples).
1677
1678 All volumes are in decibels relative to the maximum PCM value.
1679
1680 @subsection Examples
1681
1682 Here is an excerpt of the output:
1683 @example
1684 [Parsed_volumedetect_0 @ 0xa23120] mean_volume: -27 dB
1685 [Parsed_volumedetect_0 @ 0xa23120] max_volume: -4 dB
1686 [Parsed_volumedetect_0 @ 0xa23120] histogram_4db: 6
1687 [Parsed_volumedetect_0 @ 0xa23120] histogram_5db: 62
1688 [Parsed_volumedetect_0 @ 0xa23120] histogram_6db: 286
1689 [Parsed_volumedetect_0 @ 0xa23120] histogram_7db: 1042
1690 [Parsed_volumedetect_0 @ 0xa23120] histogram_8db: 2551
1691 [Parsed_volumedetect_0 @ 0xa23120] histogram_9db: 4609
1692 [Parsed_volumedetect_0 @ 0xa23120] histogram_10db: 8409
1693 @end example
1694
1695 It means that:
1696 @itemize
1697 @item
1698 The mean square energy is approximately -27 dB, or 10^-2.7.
1699 @item
1700 The largest sample is at -4 dB, or more precisely between -4 dB and -5 dB.
1701 @item
1702 There are 6 samples at -4 dB, 62 at -5 dB, 286 at -6 dB, etc.
1703 @end itemize
1704
1705 In other words, raising the volume by +4 dB does not cause any clipping,
1706 raising it by +5 dB causes clipping for 6 samples, etc.
1707
1708 @c man end AUDIO FILTERS
1709
1710 @chapter Audio Sources
1711 @c man begin AUDIO SOURCES
1712
1713 Below is a description of the currently available audio sources.
1714
1715 @section abuffer
1716
1717 Buffer audio frames, and make them available to the filter chain.
1718
1719 This source is mainly intended for a programmatic use, in particular
1720 through the interface defined in @file{libavfilter/asrc_abuffer.h}.
1721
1722 It accepts the following named parameters:
1723
1724 @table @option
1725
1726 @item time_base
1727 Timebase which will be used for timestamps of submitted frames. It must be
1728 either a floating-point number or in @var{numerator}/@var{denominator} form.
1729
1730 @item sample_rate
1731 The sample rate of the incoming audio buffers.
1732
1733 @item sample_fmt
1734 The sample format of the incoming audio buffers.
1735 Either a sample format name or its corresponging integer representation from
1736 the enum AVSampleFormat in @file{libavutil/samplefmt.h}
1737
1738 @item channel_layout
1739 The channel layout of the incoming audio buffers.
1740 Either a channel layout name from channel_layout_map in
1741 @file{libavutil/channel_layout.c} or its corresponding integer representation
1742 from the AV_CH_LAYOUT_* macros in @file{libavutil/channel_layout.h}
1743
1744 @item channels
1745 The number of channels of the incoming audio buffers.
1746 If both @var{channels} and @var{channel_layout} are specified, then they
1747 must be consistent.
1748
1749 @end table
1750
1751 @subsection Examples
1752
1753 @example
1754 abuffer=sample_rate=44100:sample_fmt=s16p:channel_layout=stereo
1755 @end example
1756
1757 will instruct the source to accept planar 16bit signed stereo at 44100Hz.
1758 Since the sample format with name "s16p" corresponds to the number
1759 6 and the "stereo" channel layout corresponds to the value 0x3, this is
1760 equivalent to:
1761 @example
1762 abuffer=sample_rate=44100:sample_fmt=6:channel_layout=0x3
1763 @end example
1764
1765 @section aevalsrc
1766
1767 Generate an audio signal specified by an expression.
1768
1769 This source accepts in input one or more expressions (one for each
1770 channel), which are evaluated and used to generate a corresponding
1771 audio signal.
1772
1773 This source accepts the following options:
1774
1775 @table @option
1776 @item exprs
1777 Set the '|'-separated expressions list for each separate channel. In case the
1778 @option{channel_layout} option is not specified, the selected channel layout
1779 depends on the number of provided expressions.
1780
1781 @item channel_layout, c
1782 Set the channel layout. The number of channels in the specified layout
1783 must be equal to the number of specified expressions.
1784
1785 @item duration, d
1786 Set the minimum duration of the sourced audio. See the function
1787 @code{av_parse_time()} for the accepted format.
1788 Note that the resulting duration may be greater than the specified
1789 duration, as the generated audio is always cut at the end of a
1790 complete frame.
1791
1792 If not specified, or the expressed duration is negative, the audio is
1793 supposed to be generated forever.
1794
1795 @item nb_samples, n
1796 Set the number of samples per channel per each output frame,
1797 default to 1024.
1798
1799 @item sample_rate, s
1800 Specify the sample rate, default to 44100.
1801 @end table
1802
1803 Each expression in @var{exprs} can contain the following constants:
1804
1805 @table @option
1806 @item n
1807 number of the evaluated sample, starting from 0
1808
1809 @item t
1810 time of the evaluated sample expressed in seconds, starting from 0
1811
1812 @item s
1813 sample rate
1814
1815 @end table
1816
1817 @subsection Examples
1818
1819 @itemize
1820 @item
1821 Generate silence:
1822 @example
1823 aevalsrc=0
1824 @end example
1825
1826 @item
1827 Generate a sin signal with frequency of 440 Hz, set sample rate to
1828 8000 Hz:
1829 @example
1830 aevalsrc="sin(440*2*PI*t):s=8000"
1831 @end example
1832
1833 @item
1834 Generate a two channels signal, specify the channel layout (Front
1835 Center + Back Center) explicitly:
1836 @example
1837 aevalsrc="sin(420*2*PI*t)|cos(430*2*PI*t):c=FC|BC"
1838 @end example
1839
1840 @item
1841 Generate white noise:
1842 @example
1843 aevalsrc="-2+random(0)"
1844 @end example
1845
1846 @item
1847 Generate an amplitude modulated signal:
1848 @example
1849 aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)"
1850 @end example
1851
1852 @item
1853 Generate 2.5 Hz binaural beats on a 360 Hz carrier:
1854 @example
1855 aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) | 0.1*sin(2*PI*(360+2.5/2)*t)"
1856 @end example
1857
1858 @end itemize
1859
1860 @section anullsrc
1861
1862 Null audio source, return unprocessed audio frames. It is mainly useful
1863 as a template and to be employed in analysis / debugging tools, or as
1864 the source for filters which ignore the input data (for example the sox
1865 synth filter).
1866
1867 This source accepts the following options:
1868
1869 @table @option
1870
1871 @item channel_layout, cl
1872
1873 Specify the channel layout, and can be either an integer or a string
1874 representing a channel layout. The default value of @var{channel_layout}
1875 is "stereo".
1876
1877 Check the channel_layout_map definition in
1878 @file{libavutil/channel_layout.c} for the mapping between strings and
1879 channel layout values.
1880
1881 @item sample_rate, r
1882 Specify the sample rate, and defaults to 44100.
1883
1884 @item nb_samples, n
1885 Set the number of samples per requested frames.
1886
1887 @end table
1888
1889 @subsection Examples
1890
1891 @itemize
1892 @item
1893 Set the sample rate to 48000 Hz and the channel layout to AV_CH_LAYOUT_MONO.
1894 @example
1895 anullsrc=r=48000:cl=4
1896 @end example
1897
1898 @item
1899 Do the same operation with a more obvious syntax:
1900 @example
1901 anullsrc=r=48000:cl=mono
1902 @end example
1903 @end itemize
1904
1905 All the parameters need to be explicitly defined.
1906
1907 @section flite
1908
1909 Synthesize a voice utterance using the libflite library.
1910
1911 To enable compilation of this filter you need to configure FFmpeg with
1912 @code{--enable-libflite}.
1913
1914 Note that the flite library is not thread-safe.
1915
1916 The filter accepts the following options:
1917
1918 @table @option
1919
1920 @item list_voices
1921 If set to 1, list the names of the available voices and exit
1922 immediately. Default value is 0.
1923
1924 @item nb_samples, n
1925 Set the maximum number of samples per frame. Default value is 512.
1926
1927 @item textfile
1928 Set the filename containing the text to speak.
1929
1930 @item text
1931 Set the text to speak.
1932
1933 @item voice, v
1934 Set the voice to use for the speech synthesis. Default value is
1935 @code{kal}. See also the @var{list_voices} option.
1936 @end table
1937
1938 @subsection Examples
1939
1940 @itemize
1941 @item
1942 Read from file @file{speech.txt}, and synthetize the text using the
1943 standard flite voice:
1944 @example
1945 flite=textfile=speech.txt
1946 @end example
1947
1948 @item
1949 Read the specified text selecting the @code{slt} voice:
1950 @example
1951 flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
1952 @end example
1953
1954 @item
1955 Input text to ffmpeg:
1956 @example
1957 ffmpeg -f lavfi -i flite=text='So fare thee well, poor devil of a Sub-Sub, whose commentator I am':voice=slt
1958 @end example
1959
1960 @item
1961 Make @file{ffplay} speak the specified text, using @code{flite} and
1962 the @code{lavfi} device:
1963 @example
1964 ffplay -f lavfi flite=text='No more be grieved for which that thou hast done.'
1965 @end example
1966 @end itemize
1967
1968 For more information about libflite, check:
1969 @url{http://www.speech.cs.cmu.edu/flite/}
1970
1971 @section sine
1972
1973 Generate an audio signal made of a sine wave with amplitude 1/8.
1974
1975 The audio signal is bit-exact.
1976
1977 The filter accepts the following options:
1978
1979 @table @option
1980
1981 @item frequency, f
1982 Set the carrier frequency. Default is 440 Hz.
1983
1984 @item beep_factor, b
1985 Enable a periodic beep every second with frequency @var{beep_factor} times
1986 the carrier frequency. Default is 0, meaning the beep is disabled.
1987
1988 @item sample_rate, r
1989 Specify the sample rate, default is 44100.
1990
1991 @item duration, d
1992 Specify the duration of the generated audio stream.
1993
1994 @item samples_per_frame
1995 Set the number of samples per output frame, default is 1024.
1996 @end table
1997
1998 @subsection Examples
1999
2000 @itemize
2001
2002 @item
2003 Generate a simple 440 Hz sine wave:
2004 @example
2005 sine
2006 @end example
2007
2008 @item
2009 Generate a 220 Hz sine wave with a 880 Hz beep each second, for 5 seconds:
2010 @example
2011 sine=220:4:d=5
2012 sine=f=220:b=4:d=5
2013 sine=frequency=220:beep_factor=4:duration=5
2014 @end example
2015
2016 @end itemize
2017
2018 @c man end AUDIO SOURCES
2019
2020 @chapter Audio Sinks
2021 @c man begin AUDIO SINKS
2022
2023 Below is a description of the currently available audio sinks.
2024
2025 @section abuffersink
2026
2027 Buffer audio frames, and make them available to the end of filter chain.
2028
2029 This sink is mainly intended for programmatic use, in particular
2030 through the interface defined in @file{libavfilter/buffersink.h}
2031 or the options system.
2032
2033 It accepts a pointer to an AVABufferSinkContext structure, which
2034 defines the incoming buffers' formats, to be passed as the opaque
2035 parameter to @code{avfilter_init_filter} for initialization.
2036
2037 @section anullsink
2038
2039 Null audio sink, do absolutely nothing with the input audio. It is
2040 mainly useful as a template and to be employed in analysis / debugging
2041 tools.
2042
2043 @c man end AUDIO SINKS
2044
2045 @chapter Video Filters
2046 @c man begin VIDEO FILTERS
2047
2048 When you configure your FFmpeg build, you can disable any of the
2049 existing filters using @code{--disable-filters}.
2050 The configure output will show the video filters included in your
2051 build.
2052
2053 Below is a description of the currently available video filters.
2054
2055 @section alphaextract
2056
2057 Extract the alpha component from the input as a grayscale video. This
2058 is especially useful with the @var{alphamerge} filter.
2059
2060 @section alphamerge
2061
2062 Add or replace the alpha component of the primary input with the
2063 grayscale value of a second input. This is intended for use with
2064 @var{alphaextract} to allow the transmission or storage of frame
2065 sequences that have alpha in a format that doesn't support an alpha
2066 channel.
2067
2068 For example, to reconstruct full frames from a normal YUV-encoded video
2069 and a separate video created with @var{alphaextract}, you might use:
2070 @example
2071 movie=in_alpha.mkv [alpha]; [in][alpha] alphamerge [out]
2072 @end example
2073
2074 Since this filter is designed for reconstruction, it operates on frame
2075 sequences without considering timestamps, and terminates when either
2076 input reaches end of stream. This will cause problems if your encoding
2077 pipeline drops frames. If you're trying to apply an image as an
2078 overlay to a video stream, consider the @var{overlay} filter instead.
2079
2080 @section ass
2081
2082 Same as the @ref{subtitles} filter, except that it doesn't require libavcodec
2083 and libavformat to work. On the other hand, it is limited to ASS (Advanced
2084 Substation Alpha) subtitles files.
2085
2086 @section bbox
2087
2088 Compute the bounding box for the non-black pixels in the input frame
2089 luminance plane.
2090
2091 This filter computes the bounding box containing all the pixels with a
2092 luminance value greater than the minimum allowed value.
2093 The parameters describing the bounding box are printed on the filter
2094 log.
2095
2096 The filter accepts the following option:
2097
2098 @table @option
2099 @item min_val
2100 Set the minimal luminance value. Default is @code{16}.
2101 @end table
2102
2103 @section blackdetect
2104
2105 Detect video intervals that are (almost) completely black. Can be
2106 useful to detect chapter transitions, commercials, or invalid
2107 recordings. Output lines contains the time for the start, end and
2108 duration of the detected black interval expressed in seconds.
2109
2110 In order to display the output lines, you need to set the loglevel at
2111 least to the AV_LOG_INFO value.
2112
2113 The filter accepts the following options:
2114
2115 @table @option
2116 @item black_min_duration, d
2117 Set the minimum detected black duration expressed in seconds. It must
2118 be a non-negative floating point number.
2119
2120 Default value is 2.0.
2121
2122 @item picture_black_ratio_th, pic_th
2123 Set the threshold for considering a picture "black".
2124 Express the minimum value for the ratio:
2125 @example
2126 @var{nb_black_pixels} / @var{nb_pixels}
2127 @end example
2128
2129 for which a picture is considered black.
2130 Default value is 0.98.
2131
2132 @item pixel_black_th, pix_th
2133 Set the threshold for considering a pixel "black".
2134
2135 The threshold expresses the maximum pixel luminance value for which a
2136 pixel is considered "black". The provided value is scaled according to
2137 the following equation:
2138 @example
2139 @var{absolute_threshold} = @var{luminance_minimum_value} + @var{pixel_black_th} * @var{luminance_range_size}
2140 @end example
2141
2142 @var{luminance_range_size} and @var{luminance_minimum_value} depend on
2143 the input video format, the range is [0-255] for YUV full-range
2144 formats and [16-235] for YUV non full-range formats.
2145
2146 Default value is 0.10.
2147 @end table
2148
2149 The following example sets the maximum pixel threshold to the minimum
2150 value, and detects only black intervals of 2 or more seconds:
2151 @example
2152 blackdetect=d=2:pix_th=0.00
2153 @end example
2154
2155 @section blackframe
2156
2157 Detect frames that are (almost) completely black. Can be useful to
2158 detect chapter transitions or commercials. Output lines consist of
2159 the frame number of the detected frame, the percentage of blackness,
2160 the position in the file if known or -1 and the timestamp in seconds.
2161
2162 In order to display the output lines, you need to set the loglevel at
2163 least to the AV_LOG_INFO value.
2164
2165 The filter accepts the following options:
2166
2167 @table @option
2168
2169 @item amount
2170 Set the percentage of the pixels that have to be below the threshold, defaults
2171 to @code{98}.
2172
2173 @item threshold, thresh
2174 Set the threshold below which a pixel value is considered black, defaults to
2175 @code{32}.
2176
2177 @end table
2178
2179 @section blend
2180
2181 Blend two video frames into each other.
2182
2183 It takes two input streams and outputs one stream, the first input is the
2184 "top" layer and second input is "bottom" layer.
2185 Output terminates when shortest input terminates.
2186
2187 A description of the accepted options follows.
2188
2189 @table @option
2190 @item c0_mode
2191 @item c1_mode
2192 @item c2_mode
2193 @item c3_mode
2194 @item all_mode
2195 Set blend mode for specific pixel component or all pixel components in case
2196 of @var{all_mode}. Default value is @code{normal}.
2197
2198 Available values for component modes are:
2199 @table @samp
2200 @item addition
2201 @item and
2202 @item average
2203 @item burn
2204 @item darken
2205 @item difference
2206 @item divide
2207 @item dodge
2208 @item exclusion
2209 @item hardlight
2210 @item lighten
2211 @item multiply
2212 @item negation
2213 @item normal
2214 @item or
2215 @item overlay
2216 @item phoenix
2217 @item pinlight
2218 @item reflect
2219 @item screen
2220 @item softlight
2221 @item subtract
2222 @item vividlight
2223 @item xor
2224 @end table
2225
2226 @item c0_opacity
2227 @item c1_opacity
2228 @item c2_opacity
2229 @item c3_opacity
2230 @item all_opacity
2231 Set blend opacity for specific pixel component or all pixel components in case
2232 of @var{all_opacity}. Only used in combination with pixel component blend modes.
2233
2234 @item c0_expr
2235 @item c1_expr
2236 @item c2_expr
2237 @item c3_expr
2238 @item all_expr
2239 Set blend expression for specific pixel component or all pixel components in case
2240 of @var{all_expr}. Note that related mode options will be ignored if those are set.
2241
2242 The expressions can use the following variables:
2243
2244 @table @option
2245 @item N
2246 The sequential number of the filtered frame, starting from @code{0}.
2247
2248 @item X
2249 @item Y
2250 the coordinates of the current sample
2251
2252 @item W
2253 @item H
2254 the width and height of currently filtered plane
2255
2256 @item SW
2257 @item SH
2258 Width and height scale depending on the currently filtered plane. It is the
2259 ratio between the corresponding luma plane number of pixels and the current
2260 plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and
2261 @code{0.5,0.5} for chroma planes.
2262
2263 @item T
2264 Time of the current frame, expressed in seconds.
2265
2266 @item TOP, A
2267 Value of pixel component at current location for first video frame (top layer).
2268
2269 @item BOTTOM, B
2270 Value of pixel component at current location for second video frame (bottom layer).
2271 @end table
2272
2273 @item shortest
2274 Force termination when the shortest input terminates. Default is @code{0}.
2275 @item repeatlast
2276 Continue applying the last bottom frame after the end of the stream. A value of
2277 @code{0} disable the filter after the last frame of the bottom layer is reached.
2278 Default is @code{1}.
2279 @end table
2280
2281 @subsection Examples
2282
2283 @itemize
2284 @item
2285 Apply transition from bottom layer to top layer in first 10 seconds:
2286 @example
2287 blend=all_expr='A*(if(gte(T,10),1,T/10))+B*(1-(if(gte(T,10),1,T/10)))'
2288 @end example
2289
2290 @item
2291 Apply 1x1 checkerboard effect:
2292 @example
2293 blend=all_expr='if(eq(mod(X,2),mod(Y,2)),A,B)'
2294 @end example
2295 @end itemize
2296
2297 @section boxblur
2298
2299 Apply boxblur algorithm to the input video.
2300
2301 The filter accepts the following options:
2302
2303 @table @option
2304
2305 @item luma_radius, lr
2306 @item luma_power, lp
2307 @item chroma_radius, cr
2308 @item chroma_power, cp
2309 @item alpha_radius, ar
2310 @item alpha_power, ap
2311
2312 @end table
2313
2314 A description of the accepted options follows.
2315
2316 @table @option
2317 @item luma_radius, lr
2318 @item chroma_radius, cr
2319 @item alpha_radius, ar
2320 Set an expression for the box radius in pixels used for blurring the
2321 corresponding input plane.
2322
2323 The radius value must be a non-negative number, and must not be
2324 greater than the value of the expression @code{min(w,h)/2} for the
2325 luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma
2326 planes.
2327
2328 Default value for @option{luma_radius} is "2". If not specified,
2329 @option{chroma_radius} and @option{alpha_radius} default to the
2330 corresponding value set for @option{luma_radius}.
2331
2332 The expressions can contain the following constants:
2333 @table @option
2334 @item w
2335 @item h
2336 the input width and height in pixels
2337
2338 @item cw
2339 @item ch
2340 the input chroma image width and height in pixels
2341
2342 @item hsub
2343 @item vsub
2344 horizontal and vertical chroma subsample values. For example for the
2345 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
2346 @end table
2347
2348 @item luma_power, lp
2349 @item chroma_power, cp
2350 @item alpha_power, ap
2351 Specify how many times the boxblur filter is applied to the
2352 corresponding plane.
2353
2354 Default value for @option{luma_power} is 2. If not specified,
2355 @option{chroma_power} and @option{alpha_power} default to the
2356 corresponding value set for @option{luma_power}.
2357
2358 A value of 0 will disable the effect.
2359 @end table
2360
2361 @subsection Examples
2362
2363 @itemize
2364 @item
2365 Apply a boxblur filter with luma, chroma, and alpha radius
2366 set to 2:
2367 @example
2368 boxblur=luma_radius=2:luma_power=1
2369 boxblur=2:1
2370 @end example
2371
2372 @item
2373 Set luma radius to 2, alpha and chroma radius to 0:
2374 @example
2375 boxblur=2:1:cr=0:ar=0
2376 @end example
2377
2378 @item
2379 Set luma and chroma radius to a fraction of the video dimension:
2380 @example
2381 boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1
2382 @end example
2383 @end itemize
2384
2385 @section colorbalance
2386 Modify intensity of primary colors (red, green and blue) of input frames.
2387
2388 The filter allows an input frame to be adjusted in the shadows, midtones or highlights
2389 regions for the red-cyan, green-magenta or blue-yellow balance.
2390
2391 A positive adjustment value shifts the balance towards the primary color, a negative
2392 value towards the complementary color.
2393
2394 The filter accepts the following options:
2395
2396 @table @option
2397 @item rs
2398 @item gs
2399 @item bs
2400 Adjust red, green and blue shadows (darkest pixels).
2401
2402 @item rm
2403 @item gm
2404 @item bm
2405 Adjust red, green and blue midtones (medium pixels).
2406
2407 @item rh
2408 @item gh
2409 @item bh
2410 Adjust red, green and blue highlights (brightest pixels).
2411
2412 Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
2413 @end table
2414
2415 @subsection Examples
2416
2417 @itemize
2418 @item
2419 Add red color cast to shadows:
2420 @example
2421 colorbalance=rs=.3
2422 @end example
2423 @end itemize
2424
2425 @section colorchannelmixer
2426
2427 Adjust video input frames by re-mixing color channels.
2428
2429 This filter modifies a color channel by adding the values associated to
2430 the other channels of the same pixels. For example if the value to
2431 modify is red, the output value will be:
2432 @example
2433 @var{red}=@var{red}*@var{rr} + @var{blue}*@var{rb} + @var{green}*@var{rg} + @var{alpha}*@var{ra}
2434 @end example
2435
2436 The filter accepts the following options:
2437
2438 @table @option
2439 @item rr
2440 @item rg
2441 @item rb
2442 @item ra
2443 Adjust contribution of input red, green, blue and alpha channels for output red channel.
2444 Default is @code{1} for @var{rr}, and @code{0} for @var{rg}, @var{rb} and @var{ra}.
2445
2446 @item gr
2447 @item gg
2448 @item gb
2449 @item ga
2450 Adjust contribution of input red, green, blue and alpha channels for output green channel.
2451 Default is @code{1} for @var{gg}, and @code{0} for @var{gr}, @var{gb} and @var{ga}.
2452
2453 @item br
2454 @item bg
2455 @item bb
2456 @item ba
2457 Adjust contribution of input red, green, blue and alpha channels for output blue channel.
2458 Default is @code{1} for @var{bb}, and @code{0} for @var{br}, @var{bg} and @var{ba}.
2459
2460 @item ar
2461 @item ag
2462 @item ab
2463 @item aa
2464 Adjust contribution of input red, green, blue and alpha channels for output alpha channel.
2465 Default is @code{1} for @var{aa}, and @code{0} for @var{ar}, @var{ag} and @var{ab}.
2466
2467 Allowed ranges for options are @code{[-2.0, 2.0]}.
2468 @end table
2469
2470 @subsection Examples
2471
2472 @itemize
2473 @item
2474 Convert source to grayscale:
2475 @example
2476 colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3
2477 @end example
2478 @item
2479 Simulate sepia tones:
2480 @example
2481 colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131
2482 @end example
2483 @end itemize
2484
2485 @section colormatrix
2486
2487 Convert color matrix.
2488
2489 The filter accepts the following options:
2490
2491 @table @option
2492 @item src
2493 @item dst
2494 Specify the source and destination color matrix. Both values must be
2495 specified.
2496
2497 The accepted values are:
2498 @table @samp
2499 @item bt709
2500 BT.709
2501
2502 @item bt601
2503 BT.601
2504
2505 @item smpte240m
2506 SMPTE-240M
2507
2508 @item fcc
2509 FCC
2510 @end table
2511 @end table
2512
2513 For example to convert from BT.601 to SMPTE-240M, use the command:
2514 @example
2515 colormatrix=bt601:smpte240m
2516 @end example
2517
2518 @section copy
2519
2520 Copy the input source unchanged to the output. Mainly useful for
2521 testing purposes.
2522
2523 @section crop
2524
2525 Crop the input video to given dimensions.
2526
2527 The filter accepts the following options:
2528
2529 @table @option
2530 @item w, out_w
2531 Width of the output video. It defaults to @code{iw}.
2532 This expression is evaluated only once during the filter
2533 configuration.
2534
2535 @item h, out_h
2536 Height of the output video. It defaults to @code{ih}.
2537 This expression is evaluated only once during the filter
2538 configuration.
2539
2540 @item x
2541 Horizontal position, in the input video, of the left edge of the output video.
2542 It defaults to @code{(in_w-out_w)/2}.
2543 This expression is evaluated per-frame.
2544
2545 @item y
2546 Vertical position, in the input video, of the top edge of the output video.
2547 It defaults to @code{(in_h-out_h)/2}.
2548 This expression is evaluated per-frame.
2549
2550 @item keep_aspect
2551 If set to 1 will force the output display aspect ratio
2552 to be the same of the input, by changing the output sample aspect
2553 ratio. It defaults to 0.
2554 @end table
2555
2556 The @var{out_w}, @var{out_h}, @var{x}, @var{y} parameters are
2557 expressions containing the following constants:
2558
2559 @table @option
2560 @item x
2561 @item y
2562 the computed values for @var{x} and @var{y}. They are evaluated for
2563 each new frame.
2564
2565 @item in_w
2566 @item in_h
2567 the input width and height
2568
2569 @item iw
2570 @item ih
2571 same as @var{in_w} and @var{in_h}
2572
2573 @item out_w
2574 @item out_h
2575 the output (cropped) width and height
2576
2577 @item ow
2578 @item oh
2579 same as @var{out_w} and @var{out_h}
2580
2581 @item a
2582 same as @var{iw} / @var{ih}
2583
2584 @item sar
2585 input sample aspect ratio
2586
2587 @item dar
2588 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
2589
2590 @item hsub
2591 @item vsub
2592 horizontal and vertical chroma subsample values. For example for the
2593 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
2594
2595 @item n
2596 the number of input frame, starting from 0
2597
2598 @item pos
2599 the position in the file of the input frame, NAN if unknown
2600
2601 @item t
2602 timestamp expressed in seconds, NAN if the input timestamp is unknown
2603
2604 @end table
2605
2606 The expression for @var{out_w} may depend on the value of @var{out_h},
2607 and the expression for @var{out_h} may depend on @var{out_w}, but they
2608 cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are
2609 evaluated after @var{out_w} and @var{out_h}.
2610
2611 The @var{x} and @var{y} parameters specify the expressions for the
2612 position of the top-left corner of the output (non-cropped) area. They
2613 are evaluated for each frame. If the evaluated value is not valid, it
2614 is approximated to the nearest valid value.
2615
2616 The expression for @var{x} may depend on @var{y}, and the expression
2617 for @var{y} may depend on @var{x}.
2618
2619 @subsection Examples
2620
2621 @itemize
2622 @item
2623 Crop area with size 100x100 at position (12,34).
2624 @example
2625 crop=100:100:12:34
2626 @end example
2627
2628 Using named options, the example above becomes:
2629 @example
2630 crop=w=100:h=100:x=12:y=34
2631 @end example
2632
2633 @item
2634 Crop the central input area with size 100x100:
2635 @example
2636 crop=100:100
2637 @end example
2638
2639 @item
2640 Crop the central input area with size 2/3 of the input video:
2641 @example
2642 crop=2/3*in_w:2/3*in_h
2643 @end example
2644
2645 @item
2646 Crop the input video central square:
2647 @example
2648 crop=out_w=in_h
2649 crop=in_h
2650 @end example
2651
2652 @item
2653 Delimit the rectangle with the top-left corner placed at position
2654 100:100 and the right-bottom corner corresponding to the right-bottom
2655 corner of the input image:
2656 @example
2657 crop=in_w-100:in_h-100:100:100
2658 @end example
2659
2660 @item
2661 Crop 10 pixels from the left and right borders, and 20 pixels from
2662 the top and bottom borders
2663 @example
2664 crop=in_w-2*10:in_h-2*20
2665 @end example
2666
2667 @item
2668 Keep only the bottom right quarter of the input image:
2669 @example
2670 crop=in_w/2:in_h/2:in_w/2:in_h/2
2671 @end example
2672
2673 @item
2674 Crop height for getting Greek harmony:
2675 @example
2676 crop=in_w:1/PHI*in_w
2677 @end example
2678
2679 @item
2680 Appply trembling effect:
2681 @example
2682 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)
2683 @end example
2684
2685 @item
2686 Apply erratic camera effect depending on timestamp:
2687 @example
2688 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)"
2689 @end example
2690
2691 @item
2692 Set x depending on the value of y:
2693 @example
2694 crop=in_w/2:in_h/2:y:10+10*sin(n/10)
2695 @end example
2696 @end itemize
2697
2698 @section cropdetect
2699
2700 Auto-detect crop size.
2701
2702 Calculate necessary cropping parameters and prints the recommended
2703 parameters through the logging system. The detected dimensions
2704 correspond to the non-black area of the input video.
2705
2706 The filter accepts the following options:
2707
2708 @table @option
2709
2710 @item limit
2711 Set higher black value threshold, which can be optionally specified
2712 from nothing (0) to everything (255). An intensity value greater
2713 to the set value is considered non-black. Default value is 24.
2714
2715 @item round
2716 Set the value for which the width/height should be divisible by. The
2717 offset is automatically adjusted to center the video. Use 2 to get
2718 only even dimensions (needed for 4:2:2 video). 16 is best when
2719 encoding to most video codecs. Default value is 16.
2720
2721 @item reset_count, reset
2722 Set the counter that determines after how many frames cropdetect will
2723 reset the previously detected largest video area and start over to
2724 detect the current optimal crop area. Default value is 0.
2725
2726 This can be useful when channel logos distort the video area. 0
2727 indicates never reset and return the largest area encountered during
2728 playback.
2729 @end table
2730
2731 @anchor{curves}
2732 @section curves
2733
2734 Apply color adjustments using curves.
2735
2736 This filter is similar to the Adobe Photoshop and GIMP curves tools. Each
2737 component (red, green and blue) has its values defined by @var{N} key points
2738 tied from each other using a smooth curve. The x-axis represents the pixel
2739 values from the input frame, and the y-axis the new pixel values to be set for
2740 the output frame.
2741
2742 By default, a component curve is defined by the two points @var{(0;0)} and
2743 @var{(1;1)}. This creates a straight line where each original pixel value is
2744 "adjusted" to its own value, which means no change to the image.
2745
2746 The filter allows you to redefine these two points and add some more. A new
2747 curve (using a natural cubic spline interpolation) will be define to pass
2748 smoothly through all these new coordinates. The new defined points needs to be
2749 strictly increasing over the x-axis, and their @var{x} and @var{y} values must
2750 be in the @var{[0;1]} interval.  If the computed curves happened to go outside
2751 the vector spaces, the values will be clipped accordingly.
2752
2753 If there is no key point defined in @code{x=0}, the filter will automatically
2754 insert a @var{(0;0)} point. In the same way, if there is no key point defined
2755 in @code{x=1}, the filter will automatically insert a @var{(1;1)} point.
2756
2757 The filter accepts the following options:
2758
2759 @table @option
2760 @item preset
2761 Select one of the available color presets. This option can be used in addition
2762 to the @option{r}, @option{g}, @option{b} parameters; in this case, the later
2763 options takes priority on the preset values.
2764 Available presets are:
2765 @table @samp
2766 @item none
2767 @item color_negative
2768 @item cross_process
2769 @item darker
2770 @item increase_contrast
2771 @item lighter
2772 @item linear_contrast
2773 @item medium_contrast
2774 @item negative
2775 @item strong_contrast
2776 @item vintage
2777 @end table
2778 Default is @code{none}.
2779 @item master, m
2780 Set the master key points. These points will define a second pass mapping. It
2781 is sometimes called a "luminance" or "value" mapping. It can be used with
2782 @option{r}, @option{g}, @option{b} or @option{all} since it acts like a
2783 post-processing LUT.
2784 @item red, r
2785 Set the key points for the red component.
2786 @item green, g
2787 Set the key points for the green component.
2788 @item blue, b
2789 Set the key points for the blue component.
2790 @item all
2791 Set the key points for all components (not including master).
2792 Can be used in addition to the other key points component
2793 options. In this case, the unset component(s) will fallback on this
2794 @option{all} setting.
2795 @item psfile
2796 Specify a Photoshop curves file (@code{.asv}) to import the settings from.
2797 @end table
2798
2799 To avoid some filtergraph syntax conflicts, each key points list need to be
2800 defined using the following syntax: @code{x0/y0 x1/y1 x2/y2 ...}.
2801
2802 @subsection Examples
2803
2804 @itemize
2805 @item
2806 Increase slightly the middle level of blue:
2807 @example
2808 curves=blue='0.5/0.58'
2809 @end example
2810
2811 @item
2812 Vintage effect:
2813 @example
2814 curves=r='0/0.11 .42/.51 1/0.95':g='0.50/0.48':b='0/0.22 .49/.44 1/0.8'
2815 @end example
2816 Here we obtain the following coordinates for each components:
2817 @table @var
2818 @item red
2819 @code{(0;0.11) (0.42;0.51) (1;0.95)}
2820 @item green
2821 @code{(0;0) (0.50;0.48) (1;1)}
2822 @item blue
2823 @code{(0;0.22) (0.49;0.44) (1;0.80)}
2824 @end table
2825
2826 @item
2827 The previous example can also be achieved with the associated built-in preset:
2828 @example
2829 curves=preset=vintage
2830 @end example
2831
2832 @item
2833 Or simply:
2834 @example
2835 curves=vintage
2836 @end example
2837
2838 @item
2839 Use a Photoshop preset and redefine the points of the green component:
2840 @example
2841 curves=psfile='MyCurvesPresets/purple.asv':green='0.45/0.53'
2842 @end example
2843 @end itemize
2844
2845 @section dctdnoiz
2846
2847 Denoise frames using 2D DCT (frequency domain filtering).
2848
2849 This filter is not designed for real time and can be extremely slow.
2850
2851 The filter accepts the following options:
2852
2853 @table @option
2854 @item sigma, s
2855 Set the noise sigma constant.
2856
2857 This @var{sigma} defines a hard threshold of @code{3 * sigma}; every DCT
2858 coefficient (absolute value) below this threshold with be dropped.
2859
2860 If you need a more advanced filtering, see @option{expr}.
2861
2862 Default is @code{0}.
2863
2864 @item overlap
2865 Set number overlapping pixels for each block. Each block is of size
2866 @code{16x16}. Since the filter can be slow, you may want to reduce this value,
2867 at the cost of a less effective filter and the risk of various artefacts.
2868
2869 If the overlapping value doesn't allow to process the whole input width or
2870 height, a warning will be displayed and according borders won't be denoised.
2871
2872 Default value is @code{15}.
2873
2874 @item expr, e
2875 Set the coefficient factor expression.
2876
2877 For each coefficient of a DCT block, this expression will be evaluated as a
2878 multiplier value for the coefficient.
2879
2880 If this is option is set, the @option{sigma} option will be ignored.
2881
2882 The absolute value of the coefficient can be accessed through the @var{c}
2883 variable.
2884 @end table
2885
2886 @subsection Examples
2887
2888 Apply a denoise with a @option{sigma} of @code{4.5}:
2889 @example
2890 dctdnoiz=4.5
2891 @end example
2892
2893 The same operation can be achieved using the expression system:
2894 @example
2895 dctdnoiz=e='gte(c, 4.5*3)'
2896 @end example
2897
2898 @anchor{decimate}
2899 @section decimate
2900
2901 Drop duplicated frames at regular intervals.
2902
2903 The filter accepts the following options:
2904
2905 @table @option
2906 @item cycle
2907 Set the number of frames from which one will be dropped. Setting this to
2908 @var{N} means one frame in every batch of @var{N} frames will be dropped.
2909 Default is @code{5}.
2910
2911 @item dupthresh
2912 Set the threshold for duplicate detection. If the difference metric for a frame
2913 is less than or equal to this value, then it is declared as duplicate. Default
2914 is @code{1.1}
2915
2916 @item scthresh
2917 Set scene change threshold. Default is @code{15}.
2918
2919 @item blockx
2920 @item blocky
2921 Set the size of the x and y-axis blocks used during metric calculations.
2922 Larger blocks give better noise suppression, but also give worse detection of
2923 small movements. Must be a power of two. Default is @code{32}.
2924
2925 @item ppsrc
2926 Mark main input as a pre-processed input and activate clean source input
2927 stream. This allows the input to be pre-processed with various filters to help
2928 the metrics calculation while keeping the frame selection lossless. When set to
2929 @code{1}, the first stream is for the pre-processed input, and the second
2930 stream is the clean source from where the kept frames are chosen. Default is
2931 @code{0}.
2932
2933 @item chroma
2934 Set whether or not chroma is considered in the metric calculations. Default is
2935 @code{1}.
2936 @end table
2937
2938 @section delogo
2939
2940 Suppress a TV station logo by a simple interpolation of the surrounding
2941 pixels. Just set a rectangle covering the logo and watch it disappear
2942 (and sometimes something even uglier appear - your mileage may vary).
2943
2944 This filter accepts the following options:
2945 @table @option
2946
2947 @item x
2948 @item y
2949 Specify the top left corner coordinates of the logo. They must be
2950 specified.
2951
2952 @item w
2953 @item h
2954 Specify the width and height of the logo to clear. They must be
2955 specified.
2956
2957 @item band, t
2958 Specify the thickness of the fuzzy edge of the rectangle (added to
2959 @var{w} and @var{h}). The default value is 4.
2960
2961 @item show
2962 When set to 1, a green rectangle is drawn on the screen to simplify
2963 finding the right @var{x}, @var{y}, @var{w}, and @var{h} parameters.
2964 The default value is 0.
2965
2966 The rectangle is drawn on the outermost pixels which will be (partly)
2967 replaced with interpolated values. The values of the next pixels
2968 immediately outside this rectangle in each direction will be used to
2969 compute the interpolated pixel values inside the rectangle.
2970
2971 @end table
2972
2973 @subsection Examples
2974
2975 @itemize
2976 @item
2977 Set a rectangle covering the area with top left corner coordinates 0,0
2978 and size 100x77, setting a band of size 10:
2979 @example
2980 delogo=x=0:y=0:w=100:h=77:band=10
2981 @end example
2982
2983 @end itemize
2984
2985 @section deshake
2986
2987 Attempt to fix small changes in horizontal and/or vertical shift. This
2988 filter helps remove camera shake from hand-holding a camera, bumping a
2989 tripod, moving on a vehicle, etc.
2990
2991 The filter accepts the following options:
2992
2993 @table @option
2994
2995 @item x
2996 @item y
2997 @item w
2998 @item h
2999 Specify a rectangular area where to limit the search for motion
3000 vectors.
3001 If desired the search for motion vectors can be limited to a
3002 rectangular area of the frame defined by its top left corner, width
3003 and height. These parameters have the same meaning as the drawbox
3004 filter which can be used to visualise the position of the bounding
3005 box.
3006
3007 This is useful when simultaneous movement of subjects within the frame
3008 might be confused for camera motion by the motion vector search.
3009
3010 If any or all of @var{x}, @var{y}, @var{w} and @var{h} are set to -1
3011 then the full frame is used. This allows later options to be set
3012 without specifying the bounding box for the motion vector search.
3013
3014 Default - search the whole frame.
3015
3016 @item rx
3017 @item ry
3018 Specify the maximum extent of movement in x and y directions in the
3019 range 0-64 pixels. Default 16.
3020
3021 @item edge
3022 Specify how to generate pixels to fill blanks at the edge of the
3023 frame. Available values are:
3024 @table @samp
3025 @item blank, 0
3026 Fill zeroes at blank locations
3027 @item original, 1
3028 Original image at blank locations
3029 @item clamp, 2
3030 Extruded edge value at blank locations
3031 @item mirror, 3
3032 Mirrored edge at blank locations
3033 @end table
3034 Default value is @samp{mirror}.
3035
3036 @item blocksize
3037 Specify the blocksize to use for motion search. Range 4-128 pixels,
3038 default 8.
3039
3040 @item contrast
3041 Specify the contrast threshold for blocks. Only blocks with more than
3042 the specified contrast (difference between darkest and lightest
3043 pixels) will be considered. Range 1-255, default 125.
3044
3045 @item search
3046 Specify the search strategy. Available values are:
3047 @table @samp
3048 @item exhaustive, 0
3049 Set exhaustive search
3050 @item less, 1
3051 Set less exhaustive search.
3052 @end table
3053 Default value is @samp{exhaustive}.
3054
3055 @item filename
3056 If set then a detailed log of the motion search is written to the
3057 specified file.
3058
3059 @item opencl
3060 If set to 1, specify using OpenCL capabilities, only available if
3061 FFmpeg was configured with @code{--enable-opencl}. Default value is 0.
3062
3063 @end table
3064
3065 @section drawbox
3066
3067 Draw a colored box on the input image.
3068
3069 This filter accepts the following options:
3070
3071 @table @option
3072 @item x
3073 @item y
3074 The expressions which specify the top left corner coordinates of the box. Default to 0.
3075
3076 @item width, w
3077 @item height, h
3078 The expressions which specify the width and height of the box, if 0 they are interpreted as
3079 the input width and height. Default to 0.
3080
3081 @item color, c
3082 Specify the color of the box to write, it can be the name of a color
3083 (case insensitive match) or a 0xRRGGBB[AA] sequence. If the special
3084 value @code{invert} is used, the box edge color is the same as the
3085 video with inverted luma.
3086
3087 @item thickness, t
3088 The expression which sets the thickness of the box edge. Default value is @code{3}.
3089
3090 See below for the list of accepted constants.
3091 @end table
3092
3093 The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
3094 following constants:
3095
3096 @table @option
3097 @item dar
3098 The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
3099
3100 @item hsub
3101 @item vsub
3102 horizontal and vertical chroma subsample values. For example for the
3103 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
3104
3105 @item in_h, ih
3106 @item in_w, iw
3107 The input width and height.
3108
3109 @item sar
3110 The input sample aspect ratio.
3111
3112 @item x
3113 @item y
3114 The x and y offset coordinates where the box is drawn.
3115
3116 @item w
3117 @item h
3118 The width and height of the drawn box.
3119
3120 @item t
3121 The thickness of the drawn box.
3122
3123 These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
3124 each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
3125
3126 @end table
3127
3128 @subsection Examples
3129
3130 @itemize
3131 @item
3132 Draw a black box around the edge of the input image:
3133 @example
3134 drawbox
3135 @end example
3136
3137 @item
3138 Draw a box with color red and an opacity of 50%:
3139 @example
3140 drawbox=10:20:200:60:red@@0.5
3141 @end example
3142
3143 The previous example can be specified as:
3144 @example
3145 drawbox=x=10:y=20:w=200:h=60:color=red@@0.5
3146 @end example
3147
3148 @item
3149 Fill the box with pink color:
3150 @example
3151 drawbox=x=10:y=10:w=100:h=100:color=pink@@0.5:t=max
3152 @end example
3153
3154 @item
3155 Draw a 2-pixel red 2.40:1 mask:
3156 @example
3157 drawbox=x=-t:y=0.5*(ih-iw/2.4)-t:w=iw+t*2:h=iw/2.4+t*2:t=2:c=red
3158 @end example
3159 @end itemize
3160
3161 @section drawgrid
3162
3163 Draw a grid on the input image.
3164
3165 This filter accepts the following options:
3166
3167 @table @option
3168 @item x
3169 @item y
3170 The expressions which specify the coordinates of some point of grid intersection (meant to configure offset). Both default to 0.
3171
3172 @item width, w
3173 @item height, h
3174 The expressions which specify the width and height of the grid cell, if 0 they are interpreted as the
3175 input width and height, respectively, minus @code{thickness}, so image gets
3176 framed. Default to 0.
3177
3178 @item color, c
3179 Specify the color of the grid, it can be the name of a color
3180 (case insensitive match) or a 0xRRGGBB[AA] sequence. If the special
3181 value @code{invert} is used, the grid color is the same as the
3182 video with inverted luma.
3183 Note that you can append opacity value (in range of 0.0 - 1.0)
3184 to color name after @@ sign.
3185
3186 @item thickness, t
3187 The expression which sets the thickness of the grid line. Default value is @code{1}.
3188
3189 See below for the list of accepted constants.
3190 @end table
3191
3192 The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
3193 following constants:
3194
3195 @table @option
3196 @item dar
3197 The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
3198
3199 @item hsub
3200 @item vsub
3201 horizontal and vertical chroma subsample values. For example for the
3202 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
3203
3204 @item in_h, ih
3205 @item in_w, iw
3206 The input grid cell width and height.
3207
3208 @item sar
3209 The input sample aspect ratio.
3210
3211 @item x
3212 @item y
3213 The x and y coordinates of some point of grid intersection (meant to configure offset).
3214
3215 @item w
3216 @item h
3217 The width and height of the drawn cell.
3218
3219 @item t
3220 The thickness of the drawn cell.
3221
3222 These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
3223 each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
3224
3225 @end table
3226
3227 @subsection Examples
3228
3229 @itemize
3230 @item
3231 Draw a grid with cell 100x100 pixels, thickness 2 pixels, with color red and an opacity of 50%:
3232 @example
3233 drawgrid=width=100:height=100:thickness=2:color=red@@0.5
3234 @end example
3235
3236 @item
3237 Draw a white 3x3 grid with an opacity of 50%:
3238 @example
3239 drawgrid=w=iw/3:h=ih/3:t=2:c=white@@0.5
3240 @end example
3241 @end itemize
3242
3243 @anchor{drawtext}
3244 @section drawtext
3245
3246 Draw text string or text from specified file on top of video using the
3247 libfreetype library.
3248
3249 To enable compilation of this filter you need to configure FFmpeg with
3250 @code{--enable-libfreetype}.
3251
3252 @subsection Syntax
3253
3254 The description of the accepted parameters follows.
3255
3256 @table @option
3257
3258 @item box
3259 Used to draw a box around text using background color.
3260 Value should be either 1 (enable) or 0 (disable).
3261 The default value of @var{box} is 0.
3262
3263 @item boxcolor
3264 The color to be used for drawing box around text.
3265 Either a string (e.g. "yellow") or in 0xRRGGBB[AA] format
3266 (e.g. "0xff00ff"), possibly followed by an alpha specifier.
3267 The default value of @var{boxcolor} is "white".
3268
3269 @item expansion
3270 Select how the @var{text} is expanded. Can be either @code{none},
3271 @code{strftime} (deprecated) or
3272 @code{normal} (default). See the @ref{drawtext_expansion, Text expansion} section
3273 below for details.
3274
3275 @item fix_bounds
3276 If true, check and fix text coords to avoid clipping.
3277
3278 @item fontcolor
3279 The color to be used for drawing fonts.
3280 Either a string (e.g. "red") or in 0xRRGGBB[AA] format
3281 (e.g. "0xff000033"), possibly followed by an alpha specifier.
3282 The default value of @var{fontcolor} is "black".
3283
3284 @item fontfile
3285 The font file to be used for drawing text. Path must be included.
3286 This parameter is mandatory.
3287
3288 @item fontsize
3289 The font size to be used for drawing text.
3290 The default value of @var{fontsize} is 16.
3291
3292 @item ft_load_flags
3293 Flags to be used for loading the fonts.
3294
3295 The flags map the corresponding flags supported by libfreetype, and are
3296 a combination of the following values:
3297 @table @var
3298 @item default
3299 @item no_scale
3300 @item no_hinting
3301 @item render
3302 @item no_bitmap
3303 @item vertical_layout
3304 @item force_autohint
3305 @item crop_bitmap
3306 @item pedantic
3307 @item ignore_global_advance_width
3308 @item no_recurse
3309 @item ignore_transform
3310 @item monochrome
3311 @item linear_design
3312 @item no_autohint
3313 @end table
3314
3315 Default value is "render".
3316
3317 For more information consult the documentation for the FT_LOAD_*
3318 libfreetype flags.
3319
3320 @item shadowcolor
3321 The color to be used for drawing a shadow behind the drawn text.  It
3322 can be a color name (e.g. "yellow") or a string in the 0xRRGGBB[AA]
3323 form (e.g. "0xff00ff"), possibly followed by an alpha specifier.
3324 The default value of @var{shadowcolor} is "black".
3325
3326 @item shadowx
3327 @item shadowy
3328 The x and y offsets for the text shadow position with respect to the
3329 position of the text. They can be either positive or negative
3330 values. Default value for both is "0".
3331
3332 @item start_number
3333 The starting frame number for the n/frame_num variable. The default value
3334 is "0".
3335
3336 @item tabsize
3337 The size in number of spaces to use for rendering the tab.
3338 Default value is 4.
3339
3340 @item timecode
3341 Set the initial timecode representation in "hh:mm:ss[:;.]ff"
3342 format. It can be used with or without text parameter. @var{timecode_rate}
3343 option must be specified.
3344
3345 @item timecode_rate, rate, r
3346 Set the timecode frame rate (timecode only).
3347
3348 @item text
3349 The text string to be drawn. The text must be a sequence of UTF-8
3350 encoded characters.
3351 This parameter is mandatory if no file is specified with the parameter
3352 @var{textfile}.
3353
3354 @item textfile
3355 A text file containing text to be drawn. The text must be a sequence
3356 of UTF-8 encoded characters.
3357
3358 This parameter is mandatory if no text string is specified with the
3359 parameter @var{text}.
3360
3361 If both @var{text} and @var{textfile} are specified, an error is thrown.
3362
3363 @item reload
3364 If set to 1, the @var{textfile} will be reloaded before each frame.
3365 Be sure to update it atomically, or it may be read partially, or even fail.
3366
3367 @item x
3368 @item y
3369 The expressions which specify the offsets where text will be drawn
3370 within the video frame. They are relative to the top/left border of the
3371 output image.
3372
3373 The default value of @var{x} and @var{y} is "0".
3374
3375 See below for the list of accepted constants and functions.
3376 @end table
3377
3378 The parameters for @var{x} and @var{y} are expressions containing the
3379 following constants and functions:
3380
3381 @table @option
3382 @item dar
3383 input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
3384
3385 @item hsub
3386 @item vsub
3387 horizontal and vertical chroma subsample values. For example for the
3388 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
3389
3390 @item line_h, lh
3391 the height of each text line
3392
3393 @item main_h, h, H
3394 the input height
3395
3396 @item main_w, w, W
3397 the input width
3398
3399 @item max_glyph_a, ascent
3400 the maximum distance from the baseline to the highest/upper grid
3401 coordinate used to place a glyph outline point, for all the rendered
3402 glyphs.
3403 It is a positive value, due to the grid's orientation with the Y axis
3404 upwards.
3405
3406 @item max_glyph_d, descent
3407 the maximum distance from the baseline to the lowest grid coordinate
3408 used to place a glyph outline point, for all the rendered glyphs.
3409 This is a negative value, due to the grid's orientation, with the Y axis
3410 upwards.
3411
3412 @item max_glyph_h
3413 maximum glyph height, that is the maximum height for all the glyphs
3414 contained in the rendered text, it is equivalent to @var{ascent} -
3415 @var{descent}.
3416
3417 @item max_glyph_w
3418 maximum glyph width, that is the maximum width for all the glyphs
3419 contained in the rendered text
3420
3421 @item n
3422 the number of input frame, starting from 0
3423
3424 @item rand(min, max)
3425 return a random number included between @var{min} and @var{max}
3426
3427 @item sar
3428 input sample aspect ratio
3429
3430 @item t
3431 timestamp expressed in seconds, NAN if the input timestamp is unknown
3432
3433 @item text_h, th
3434 the height of the rendered text
3435
3436 @item text_w, tw
3437 the width of the rendered text
3438
3439 @item x
3440 @item y
3441 the x and y offset coordinates where the text is drawn.
3442
3443 These parameters allow the @var{x} and @var{y} expressions to refer
3444 each other, so you can for example specify @code{y=x/dar}.
3445 @end table
3446
3447 If libavfilter was built with @code{--enable-fontconfig}, then
3448 @option{fontfile} can be a fontconfig pattern or omitted.
3449
3450 @anchor{drawtext_expansion}
3451 @subsection Text expansion
3452
3453 If @option{expansion} is set to @code{strftime},
3454 the filter recognizes strftime() sequences in the provided text and
3455 expands them accordingly. Check the documentation of strftime(). This
3456 feature is deprecated.
3457
3458 If @option{expansion} is set to @code{none}, the text is printed verbatim.
3459
3460 If @option{expansion} is set to @code{normal} (which is the default),
3461 the following expansion mechanism is used.
3462
3463 The backslash character '\', followed by any character, always expands to
3464 the second character.
3465
3466 Sequence of the form @code{%@{...@}} are expanded. The text between the
3467 braces is a function name, possibly followed by arguments separated by ':'.
3468 If the arguments contain special characters or delimiters (':' or '@}'),
3469 they should be escaped.
3470
3471 Note that they probably must also be escaped as the value for the
3472 @option{text} option in the filter argument string and as the filter
3473 argument in the filtergraph description, and possibly also for the shell,
3474 that makes up to four levels of escaping; using a text file avoids these
3475 problems.
3476
3477 The following functions are available:
3478
3479 @table @command
3480
3481 @item expr, e
3482 The expression evaluation result.
3483
3484 It must take one argument specifying the expression to be evaluated,
3485 which accepts the same constants and functions as the @var{x} and
3486 @var{y} values. Note that not all constants should be used, for
3487 example the text size is not known when evaluating the expression, so
3488 the constants @var{text_w} and @var{text_h} will have an undefined
3489 value.
3490
3491 @item gmtime
3492 The time at which the filter is running, expressed in UTC.
3493 It can accept an argument: a strftime() format string.
3494
3495 @item localtime
3496 The time at which the filter is running, expressed in the local time zone.
3497 It can accept an argument: a strftime() format string.
3498
3499 @item metadata
3500 Frame metadata. It must take one argument specifying metadata key.
3501
3502 @item n, frame_num
3503 The frame number, starting from 0.
3504
3505 @item pict_type
3506 A 1 character description of the current picture type.
3507
3508 @item pts
3509 The timestamp of the current frame, in seconds, with microsecond accuracy.
3510
3511 @end table
3512
3513 @subsection Examples
3514
3515 @itemize
3516 @item
3517 Draw "Test Text" with font FreeSerif, using the default values for the
3518 optional parameters.
3519
3520 @example
3521 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"
3522 @end example
3523
3524 @item
3525 Draw 'Test Text' with font FreeSerif of size 24 at position x=100
3526 and y=50 (counting from the top-left corner of the screen), text is
3527 yellow with a red box around it. Both the text and the box have an
3528 opacity of 20%.
3529
3530 @example
3531 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
3532           x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2"
3533 @end example
3534
3535 Note that the double quotes are not necessary if spaces are not used
3536 within the parameter list.
3537
3538 @item
3539 Show the text at the center of the video frame:
3540 @example
3541 drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h-line_h)/2"
3542 @end example
3543
3544 @item
3545 Show a text line sliding from right to left in the last row of the video
3546 frame. The file @file{LONG_LINE} is assumed to contain a single line
3547 with no newlines.
3548 @example
3549 drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t"
3550 @end example
3551
3552 @item
3553 Show the content of file @file{CREDITS} off the bottom of the frame and scroll up.
3554 @example
3555 drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t"
3556 @end example
3557
3558 @item
3559 Draw a single green letter "g", at the center of the input video.
3560 The glyph baseline is placed at half screen height.
3561 @example
3562 drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent"
3563 @end example
3564
3565 @item
3566 Show text for 1 second every 3 seconds:
3567 @example
3568 drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:enable=lt(mod(t\,3)\,1):text='blink'"
3569 @end example
3570
3571 @item
3572 Use fontconfig to set the font. Note that the colons need to be escaped.
3573 @example
3574 drawtext='fontfile=Linux Libertine O-40\:style=Semibold:text=FFmpeg'
3575 @end example
3576
3577 @item
3578 Print the date of a real-time encoding (see strftime(3)):
3579 @example
3580 drawtext='fontfile=FreeSans.ttf:text=%@{localtime:%a %b %d %Y@}'
3581 @end example
3582
3583 @end itemize
3584
3585 For more information about libfreetype, check:
3586 @url{http://www.freetype.org/}.
3587
3588 For more information about fontconfig, check:
3589 @url{http://freedesktop.org/software/fontconfig/fontconfig-user.html}.
3590
3591 @section edgedetect
3592
3593 Detect and draw edges. The filter uses the Canny Edge Detection algorithm.
3594
3595 The filter accepts the following options:
3596
3597 @table @option
3598 @item low
3599 @item high
3600 Set low and high threshold values used by the Canny thresholding
3601 algorithm.
3602
3603 The high threshold selects the "strong" edge pixels, which are then
3604 connected through 8-connectivity with the "weak" edge pixels selected
3605 by the low threshold.
3606
3607 @var{low} and @var{high} threshold values must be choosen in the range
3608 [0,1], and @var{low} should be lesser or equal to @var{high}.
3609
3610 Default value for @var{low} is @code{20/255}, and default value for @var{high}
3611 is @code{50/255}.
3612 @end table
3613
3614 Example:
3615 @example
3616 edgedetect=low=0.1:high=0.4
3617 @end example
3618
3619 @section extractplanes
3620
3621 Extract color channel components from input video stream into
3622 separate grayscale video streams.
3623
3624 The filter accepts the following option:
3625
3626 @table @option
3627 @item planes
3628 Set plane(s) to extract.
3629
3630 Available values for planes are:
3631 @table @samp
3632 @item y
3633 @item u
3634 @item v
3635 @item a
3636 @item r
3637 @item g
3638 @item b
3639 @end table
3640
3641 Choosing planes not available in the input will result in an error.
3642 That means you cannot select @code{r}, @code{g}, @code{b} planes
3643 with @code{y}, @code{u}, @code{v} planes at same time.
3644 @end table
3645
3646 @subsection Examples
3647
3648 @itemize
3649 @item
3650 Extract luma, u and v color channel component from input video frame
3651 into 3 grayscale outputs:
3652 @example
3653 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
3654 @end example
3655 @end itemize
3656
3657 @section fade
3658
3659 Apply fade-in/out effect to input video.
3660
3661 This filter accepts the following options:
3662
3663 @table @option
3664 @item type, t
3665 The effect type -- can be either "in" for fade-in, or "out" for a fade-out
3666 effect.
3667 Default is @code{in}.
3668
3669 @item start_frame, s
3670 Specify the number of the start frame for starting to apply the fade
3671 effect. Default is 0.
3672
3673 @item nb_frames, n
3674 The number of frames for which the fade effect has to last. At the end of the
3675 fade-in effect the output video will have the same intensity as the input video,
3676 at the end of the fade-out transition the output video will be completely black.
3677 Default is 25.
3678
3679 @item alpha
3680 If set to 1, fade only alpha channel, if one exists on the input.
3681 Default value is 0.
3682
3683 @item start_time, st
3684 Specify the timestamp (in seconds) of the frame to start to apply the fade
3685 effect. If both start_frame and start_time are specified, the fade will start at
3686 whichever comes last.  Default is 0.
3687
3688 @item duration, d
3689 The number of seconds for which the fade effect has to last. At the end of the
3690 fade-in effect the output video will have the same intensity as the input video,
3691 at the end of the fade-out transition the output video will be completely black.
3692 If both duration and nb_frames are specified, duration is used. Default is 0.
3693 @end table
3694
3695 @subsection Examples
3696
3697 @itemize
3698 @item
3699 Fade in first 30 frames of video:
3700 @example
3701 fade=in:0:30
3702 @end example
3703
3704 The command above is equivalent to:
3705 @example
3706 fade=t=in:s=0:n=30
3707 @end example
3708
3709 @item
3710 Fade out last 45 frames of a 200-frame video:
3711 @example
3712 fade=out:155:45
3713 fade=type=out:start_frame=155:nb_frames=45
3714 @end example
3715
3716 @item
3717 Fade in first 25 frames and fade out last 25 frames of a 1000-frame video:
3718 @example
3719 fade=in:0:25, fade=out:975:25
3720 @end example
3721
3722 @item
3723 Make first 5 frames black, then fade in from frame 5-24:
3724 @example
3725 fade=in:5:20
3726 @end example
3727
3728 @item
3729 Fade in alpha over first 25 frames of video:
3730 @example
3731 fade=in:0:25:alpha=1
3732 @end example
3733
3734 @item
3735 Make first 5.5 seconds black, then fade in for 0.5 seconds:
3736 @example
3737 fade=t=in:st=5.5:d=0.5
3738 @end example
3739
3740 @end itemize
3741
3742 @section field
3743
3744 Extract a single field from an interlaced image using stride
3745 arithmetic to avoid wasting CPU time. The output frames are marked as
3746 non-interlaced.
3747
3748 The filter accepts the following options:
3749
3750 @table @option
3751 @item type
3752 Specify whether to extract the top (if the value is @code{0} or
3753 @code{top}) or the bottom field (if the value is @code{1} or
3754 @code{bottom}).
3755 @end table
3756
3757 @section fieldmatch
3758
3759 Field matching filter for inverse telecine. It is meant to reconstruct the
3760 progressive frames from a telecined stream. The filter does not drop duplicated
3761 frames, so to achieve a complete inverse telecine @code{fieldmatch} needs to be
3762 followed by a decimation filter such as @ref{decimate} in the filtergraph.
3763
3764 The separation of the field matching and the decimation is notably motivated by
3765 the possibility of inserting a de-interlacing filter fallback between the two.
3766 If the source has mixed telecined and real interlaced content,
3767 @code{fieldmatch} will not be able to match fields for the interlaced parts.
3768 But these remaining combed frames will be marked as interlaced, and thus can be
3769 de-interlaced by a later filter such as @ref{yadif} before decimation.
3770
3771 In addition to the various configuration options, @code{fieldmatch} can take an
3772 optional second stream, activated through the @option{ppsrc} option. If
3773 enabled, the frames reconstruction will be based on the fields and frames from
3774 this second stream. This allows the first input to be pre-processed in order to
3775 help the various algorithms of the filter, while keeping the output lossless
3776 (assuming the fields are matched properly). Typically, a field-aware denoiser,
3777 or brightness/contrast adjustments can help.
3778
3779 Note that this filter uses the same algorithms as TIVTC/TFM (AviSynth project)
3780 and VIVTC/VFM (VapourSynth project). The later is a light clone of TFM from
3781 which @code{fieldmatch} is based on. While the semantic and usage are very
3782 close, some behaviour and options names can differ.
3783
3784 The filter accepts the following options:
3785
3786 @table @option
3787 @item order
3788 Specify the assumed field order of the input stream. Available values are:
3789
3790 @table @samp
3791 @item auto
3792 Auto detect parity (use FFmpeg's internal parity value).
3793 @item bff
3794 Assume bottom field first.
3795 @item tff
3796 Assume top field first.
3797 @end table
3798
3799 Note that it is sometimes recommended not to trust the parity announced by the
3800 stream.
3801
3802 Default value is @var{auto}.
3803
3804 @item mode
3805 Set the matching mode or strategy to use. @option{pc} mode is the safest in the
3806 sense that it won't risk creating jerkiness due to duplicate frames when
3807 possible, but if there are bad edits or blended fields it will end up
3808 outputting combed frames when a good match might actually exist. On the other
3809 hand, @option{pcn_ub} mode is the most risky in terms of creating jerkiness,
3810 but will almost always find a good frame if there is one. The other values are
3811 all somewhere in between @option{pc} and @option{pcn_ub} in terms of risking
3812 jerkiness and creating duplicate frames versus finding good matches in sections
3813 with bad edits, orphaned fields, blended fields, etc.
3814
3815 More details about p/c/n/u/b are available in @ref{p/c/n/u/b meaning} section.
3816
3817 Available values are:
3818
3819 @table @samp
3820 @item pc
3821 2-way matching (p/c)
3822 @item pc_n
3823 2-way matching, and trying 3rd match if still combed (p/c + n)
3824 @item pc_u
3825 2-way matching, and trying 3rd match (same order) if still combed (p/c + u)
3826 @item pc_n_ub
3827 2-way matching, trying 3rd match if still combed, and trying 4th/5th matches if
3828 still combed (p/c + n + u/b)
3829 @item pcn
3830 3-way matching (p/c/n)
3831 @item pcn_ub
3832 3-way matching, and trying 4th/5th matches if all 3 of the original matches are
3833 detected as combed (p/c/n + u/b)
3834 @end table
3835
3836 The parenthesis at the end indicate the matches that would be used for that
3837 mode assuming @option{order}=@var{tff} (and @option{field} on @var{auto} or
3838 @var{top}).
3839
3840 In terms of speed @option{pc} mode is by far the fastest and @option{pcn_ub} is
3841 the slowest.
3842
3843 Default value is @var{pc_n}.
3844
3845 @item ppsrc
3846 Mark the main input stream as a pre-processed input, and enable the secondary
3847 input stream as the clean source to pick the fields from. See the filter
3848 introduction for more details. It is similar to the @option{clip2} feature from
3849 VFM/TFM.
3850
3851 Default value is @code{0} (disabled).
3852
3853 @item field
3854 Set the field to match from. It is recommended to set this to the same value as
3855 @option{order} unless you experience matching failures with that setting. In
3856 certain circumstances changing the field that is used to match from can have a
3857 large impact on matching performance. Available values are:
3858
3859 @table @samp
3860 @item auto
3861 Automatic (same value as @option{order}).
3862 @item bottom
3863 Match from the bottom field.
3864 @item top
3865 Match from the top field.
3866 @end table
3867
3868 Default value is @var{auto}.
3869
3870 @item mchroma
3871 Set whether or not chroma is included during the match comparisons. In most
3872 cases it is recommended to leave this enabled. You should set this to @code{0}
3873 only if your clip has bad chroma problems such as heavy rainbowing or other
3874 artifacts. Setting this to @code{0} could also be used to speed things up at
3875 the cost of some accuracy.
3876
3877 Default value is @code{1}.
3878
3879 @item y0
3880 @item y1
3881 These define an exclusion band which excludes the lines between @option{y0} and
3882 @option{y1} from being included in the field matching decision. An exclusion
3883 band can be used to ignore subtitles, a logo, or other things that may
3884 interfere with the matching. @option{y0} sets the starting scan line and
3885 @option{y1} sets the ending line; all lines in between @option{y0} and
3886 @option{y1} (including @option{y0} and @option{y1}) will be ignored. Setting
3887 @option{y0} and @option{y1} to the same value will disable the feature.
3888 @option{y0} and @option{y1} defaults to @code{0}.
3889
3890 @item scthresh
3891 Set the scene change detection threshold as a percentage of maximum change on
3892 the luma plane. Good values are in the @code{[8.0, 14.0]} range. Scene change
3893 detection is only relevant in case @option{combmatch}=@var{sc}.  The range for
3894 @option{scthresh} is @code{[0.0, 100.0]}.
3895
3896 Default value is @code{12.0}.
3897
3898 @item combmatch
3899 When @option{combatch} is not @var{none}, @code{fieldmatch} will take into
3900 account the combed scores of matches when deciding what match to use as the
3901 final match. Available values are:
3902
3903 @table @samp
3904 @item none
3905 No final matching based on combed scores.
3906 @item sc
3907 Combed scores are only used when a scene change is detected.
3908 @item full
3909 Use combed scores all the time.
3910 @end table
3911
3912 Default is @var{sc}.
3913
3914 @item combdbg
3915 Force @code{fieldmatch} to calculate the combed metrics for certain matches and
3916 print them. This setting is known as @option{micout} in TFM/VFM vocabulary.
3917 Available values are:
3918
3919 @table @samp
3920 @item none
3921 No forced calculation.
3922 @item pcn
3923 Force p/c/n calculations.
3924 @item pcnub
3925 Force p/c/n/u/b calculations.
3926 @end table
3927
3928 Default value is @var{none}.
3929
3930 @item cthresh
3931 This is the area combing threshold used for combed frame detection. This
3932 essentially controls how "strong" or "visible" combing must be to be detected.
3933 Larger values mean combing must be more visible and smaller values mean combing
3934 can be less visible or strong and still be detected. Valid settings are from
3935 @code{-1} (every pixel will be detected as combed) to @code{255} (no pixel will
3936 be detected as combed). This is basically a pixel difference value. A good
3937 range is @code{[8, 12]}.
3938
3939 Default value is @code{9}.
3940
3941 @item chroma
3942 Sets whether or not chroma is considered in the combed frame decision.  Only
3943 disable this if your source has chroma problems (rainbowing, etc.) that are
3944 causing problems for the combed frame detection with chroma enabled. Actually,
3945 using @option{chroma}=@var{0} is usually more reliable, except for the case
3946 where there is chroma only combing in the source.
3947
3948 Default value is @code{0}.
3949
3950 @item blockx
3951 @item blocky
3952 Respectively set the x-axis and y-axis size of the window used during combed
3953 frame detection. This has to do with the size of the area in which
3954 @option{combpel} pixels are required to be detected as combed for a frame to be
3955 declared combed. See the @option{combpel} parameter description for more info.
3956 Possible values are any number that is a power of 2 starting at 4 and going up
3957 to 512.
3958
3959 Default value is @code{16}.
3960
3961 @item combpel
3962 The number of combed pixels inside any of the @option{blocky} by
3963 @option{blockx} size blocks on the frame for the frame to be detected as
3964 combed. While @option{cthresh} controls how "visible" the combing must be, this
3965 setting controls "how much" combing there must be in any localized area (a
3966 window defined by the @option{blockx} and @option{blocky} settings) on the
3967 frame. Minimum value is @code{0} and maximum is @code{blocky x blockx} (at
3968 which point no frames will ever be detected as combed). This setting is known
3969 as @option{MI} in TFM/VFM vocabulary.
3970
3971 Default value is @code{80}.
3972 @end table
3973
3974 @anchor{p/c/n/u/b meaning}
3975 @subsection p/c/n/u/b meaning
3976
3977 @subsubsection p/c/n
3978
3979 We assume the following telecined stream:
3980
3981 @example
3982 Top fields:     1 2 2 3 4
3983 Bottom fields:  1 2 3 4 4
3984 @end example
3985
3986 The numbers correspond to the progressive frame the fields relate to. Here, the
3987 first two frames are progressive, the 3rd and 4th are combed, and so on.
3988
3989 When @code{fieldmatch} is configured to run a matching from bottom
3990 (@option{field}=@var{bottom}) this is how this input stream get transformed:
3991
3992 @example
3993 Input stream:
3994                 T     1 2 2 3 4
3995                 B     1 2 3 4 4   <-- matching reference
3996
3997 Matches:              c c n n c
3998
3999 Output stream:
4000                 T     1 2 3 4 4
4001                 B     1 2 3 4 4
4002 @end example
4003
4004 As a result of the field matching, we can see that some frames get duplicated.
4005 To perform a complete inverse telecine, you need to rely on a decimation filter
4006 after this operation. See for instance the @ref{decimate} filter.
4007
4008 The same operation now matching from top fields (@option{field}=@var{top})
4009 looks like this:
4010
4011 @example
4012 Input stream:
4013                 T     1 2 2 3 4   <-- matching reference
4014                 B     1 2 3 4 4
4015
4016 Matches:              c c p p c
4017
4018 Output stream:
4019                 T     1 2 2 3 4
4020                 B     1 2 2 3 4
4021 @end example
4022
4023 In these examples, we can see what @var{p}, @var{c} and @var{n} mean;
4024 basically, they refer to the frame and field of the opposite parity:
4025
4026 @itemize
4027 @item @var{p} matches the field of the opposite parity in the previous frame
4028 @item @var{c} matches the field of the opposite parity in the current frame
4029 @item @var{n} matches the field of the opposite parity in the next frame
4030 @end itemize
4031
4032 @subsubsection u/b
4033
4034 The @var{u} and @var{b} matching are a bit special in the sense that they match
4035 from the opposite parity flag. In the following examples, we assume that we are
4036 currently matching the 2nd frame (Top:2, bottom:2). According to the match, a
4037 'x' is placed above and below each matched fields.
4038
4039 With bottom matching (@option{field}=@var{bottom}):
4040 @example
4041 Match:           c         p           n          b          u
4042
4043                  x       x               x        x          x
4044   Top          1 2 2     1 2 2       1 2 2      1 2 2      1 2 2
4045   Bottom       1 2 3     1 2 3       1 2 3      1 2 3      1 2 3
4046                  x         x           x        x              x
4047
4048 Output frames:
4049                  2          1          2          2          2
4050                  2          2          2          1          3
4051 @end example
4052
4053 With top matching (@option{field}=@var{top}):
4054 @example
4055 Match:           c         p           n          b          u
4056
4057                  x         x           x        x              x
4058   Top          1 2 2     1 2 2       1 2 2      1 2 2      1 2 2
4059   Bottom       1 2 3     1 2 3       1 2 3      1 2 3      1 2 3
4060                  x       x               x        x          x
4061
4062 Output frames:
4063                  2          2          2          1          2
4064                  2          1          3          2          2
4065 @end example
4066
4067 @subsection Examples
4068
4069 Simple IVTC of a top field first telecined stream:
4070 @example
4071 fieldmatch=order=tff:combmatch=none, decimate
4072 @end example
4073
4074 Advanced IVTC, with fallback on @ref{yadif} for still combed frames:
4075 @example
4076 fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate
4077 @end example
4078
4079 @section fieldorder
4080
4081 Transform the field order of the input video.
4082
4083 This filter accepts the following options:
4084
4085 @table @option
4086
4087 @item order
4088 Output field order. Valid values are @var{tff} for top field first or @var{bff}
4089 for bottom field first.
4090 @end table
4091
4092 Default value is @samp{tff}.
4093
4094 Transformation is achieved by shifting the picture content up or down
4095 by one line, and filling the remaining line with appropriate picture content.
4096 This method is consistent with most broadcast field order converters.
4097
4098 If the input video is not flagged as being interlaced, or it is already
4099 flagged as being of the required output field order then this filter does
4100 not alter the incoming video.
4101
4102 This filter is very useful when converting to or from PAL DV material,
4103 which is bottom field first.
4104
4105 For example:
4106 @example
4107 ffmpeg -i in.vob -vf "fieldorder=bff" out.dv
4108 @end example
4109
4110 @section fifo
4111
4112 Buffer input images and send them when they are requested.
4113
4114 This filter is mainly useful when auto-inserted by the libavfilter
4115 framework.
4116
4117 The filter does not take parameters.
4118
4119 @anchor{format}
4120 @section format
4121
4122 Convert the input video to one of the specified pixel formats.
4123 Libavfilter will try to pick one that is supported for the input to
4124 the next filter.
4125
4126 This filter accepts the following parameters:
4127 @table @option
4128
4129 @item pix_fmts
4130 A '|'-separated list of pixel format names, for example
4131 "pix_fmts=yuv420p|monow|rgb24".
4132
4133 @end table
4134
4135 @subsection Examples
4136
4137 @itemize
4138 @item
4139 Convert the input video to the format @var{yuv420p}
4140 @example
4141 format=pix_fmts=yuv420p
4142 @end example
4143
4144 Convert the input video to any of the formats in the list
4145 @example
4146 format=pix_fmts=yuv420p|yuv444p|yuv410p
4147 @end example
4148 @end itemize
4149
4150 @section fps
4151
4152 Convert the video to specified constant frame rate by duplicating or dropping
4153 frames as necessary.
4154
4155 This filter accepts the following named parameters:
4156 @table @option
4157
4158 @item fps
4159 Desired output frame rate. The default is @code{25}.
4160
4161 @item round
4162 Rounding method.
4163
4164 Possible values are:
4165 @table @option
4166 @item zero
4167 zero round towards 0
4168 @item inf
4169 round away from 0
4170 @item down
4171 round towards -infinity
4172 @item up
4173 round towards +infinity
4174 @item near
4175 round to nearest
4176 @end table
4177 The default is @code{near}.
4178
4179 @item start_time
4180 Assume the first PTS should be the given value, in seconds. This allows for
4181 padding/trimming at the start of stream. By default, no assumption is made
4182 about the first frame's expected PTS, so no padding or trimming is done.
4183 For example, this could be set to 0 to pad the beginning with duplicates of
4184 the first frame if a video stream starts after the audio stream or to trim any
4185 frames with a negative PTS.
4186
4187 @end table
4188
4189 Alternatively, the options can be specified as a flat string:
4190 @var{fps}[:@var{round}].
4191
4192 See also the @ref{setpts} filter.
4193
4194 @subsection Examples
4195
4196 @itemize
4197 @item