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