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