doc/filters: add sepia example for colorchannelmixer
[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 @item
2375 Simulate sepia tones:
2376 @example
2377 colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131
2378 @end example
2379 @end itemize
2380
2381 @section colormatrix
2382
2383 Convert color matrix.
2384
2385 The filter accepts the following options:
2386
2387 @table @option
2388 @item src
2389 @item dst
2390 Specify the source and destination color matrix. Both values must be
2391 specified.
2392
2393 The accepted values are:
2394 @table @samp
2395 @item bt709
2396 BT.709
2397
2398 @item bt601
2399 BT.601
2400
2401 @item smpte240m
2402 SMPTE-240M
2403
2404 @item fcc
2405 FCC
2406 @end table
2407 @end table
2408
2409 For example to convert from BT.601 to SMPTE-240M, use the command:
2410 @example
2411 colormatrix=bt601:smpte240m
2412 @end example
2413
2414 @section copy
2415
2416 Copy the input source unchanged to the output. Mainly useful for
2417 testing purposes.
2418
2419 @section crop
2420
2421 Crop the input video to given dimensions.
2422
2423 The filter accepts the following options:
2424
2425 @table @option
2426 @item w, out_w
2427 Width of the output video. It defaults to @code{iw}.
2428 This expression is evaluated only once during the filter
2429 configuration.
2430
2431 @item h, out_h
2432 Height of the output video. It defaults to @code{ih}.
2433 This expression is evaluated only once during the filter
2434 configuration.
2435
2436 @item x
2437 Horizontal position, in the input video, of the left edge of the output video.
2438 It defaults to @code{(in_w-out_w)/2}.
2439 This expression is evaluated per-frame.
2440
2441 @item y
2442 Vertical position, in the input video, of the top edge of the output video.
2443 It defaults to @code{(in_h-out_h)/2}.
2444 This expression is evaluated per-frame.
2445
2446 @item keep_aspect
2447 If set to 1 will force the output display aspect ratio
2448 to be the same of the input, by changing the output sample aspect
2449 ratio. It defaults to 0.
2450 @end table
2451
2452 The @var{out_w}, @var{out_h}, @var{x}, @var{y} parameters are
2453 expressions containing the following constants:
2454
2455 @table @option
2456 @item x
2457 @item y
2458 the computed values for @var{x} and @var{y}. They are evaluated for
2459 each new frame.
2460
2461 @item in_w
2462 @item in_h
2463 the input width and height
2464
2465 @item iw
2466 @item ih
2467 same as @var{in_w} and @var{in_h}
2468
2469 @item out_w
2470 @item out_h
2471 the output (cropped) width and height
2472
2473 @item ow
2474 @item oh
2475 same as @var{out_w} and @var{out_h}
2476
2477 @item a
2478 same as @var{iw} / @var{ih}
2479
2480 @item sar
2481 input sample aspect ratio
2482
2483 @item dar
2484 input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
2485
2486 @item hsub
2487 @item vsub
2488 horizontal and vertical chroma subsample values. For example for the
2489 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
2490
2491 @item n
2492 the number of input frame, starting from 0
2493
2494 @item pos
2495 the position in the file of the input frame, NAN if unknown
2496
2497 @item t
2498 timestamp expressed in seconds, NAN if the input timestamp is unknown
2499
2500 @end table
2501
2502 The expression for @var{out_w} may depend on the value of @var{out_h},
2503 and the expression for @var{out_h} may depend on @var{out_w}, but they
2504 cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are
2505 evaluated after @var{out_w} and @var{out_h}.
2506
2507 The @var{x} and @var{y} parameters specify the expressions for the
2508 position of the top-left corner of the output (non-cropped) area. They
2509 are evaluated for each frame. If the evaluated value is not valid, it
2510 is approximated to the nearest valid value.
2511
2512 The expression for @var{x} may depend on @var{y}, and the expression
2513 for @var{y} may depend on @var{x}.
2514
2515 @subsection Examples
2516
2517 @itemize
2518 @item
2519 Crop area with size 100x100 at position (12,34).
2520 @example
2521 crop=100:100:12:34
2522 @end example
2523
2524 Using named options, the example above becomes:
2525 @example
2526 crop=w=100:h=100:x=12:y=34
2527 @end example
2528
2529 @item
2530 Crop the central input area with size 100x100:
2531 @example
2532 crop=100:100
2533 @end example
2534
2535 @item
2536 Crop the central input area with size 2/3 of the input video:
2537 @example
2538 crop=2/3*in_w:2/3*in_h
2539 @end example
2540
2541 @item
2542 Crop the input video central square:
2543 @example
2544 crop=out_w=in_h
2545 crop=in_h
2546 @end example
2547
2548 @item
2549 Delimit the rectangle with the top-left corner placed at position
2550 100:100 and the right-bottom corner corresponding to the right-bottom
2551 corner of the input image:
2552 @example
2553 crop=in_w-100:in_h-100:100:100
2554 @end example
2555
2556 @item
2557 Crop 10 pixels from the left and right borders, and 20 pixels from
2558 the top and bottom borders
2559 @example
2560 crop=in_w-2*10:in_h-2*20
2561 @end example
2562
2563 @item
2564 Keep only the bottom right quarter of the input image:
2565 @example
2566 crop=in_w/2:in_h/2:in_w/2:in_h/2
2567 @end example
2568
2569 @item
2570 Crop height for getting Greek harmony:
2571 @example
2572 crop=in_w:1/PHI*in_w
2573 @end example
2574
2575 @item
2576 Appply trembling effect:
2577 @example
2578 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)
2579 @end example
2580
2581 @item
2582 Apply erratic camera effect depending on timestamp:
2583 @example
2584 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)"
2585 @end example
2586
2587 @item
2588 Set x depending on the value of y:
2589 @example
2590 crop=in_w/2:in_h/2:y:10+10*sin(n/10)
2591 @end example
2592 @end itemize
2593
2594 @section cropdetect
2595
2596 Auto-detect crop size.
2597
2598 Calculate necessary cropping parameters and prints the recommended
2599 parameters through the logging system. The detected dimensions
2600 correspond to the non-black area of the input video.
2601
2602 The filter accepts the following options:
2603
2604 @table @option
2605
2606 @item limit
2607 Set higher black value threshold, which can be optionally specified
2608 from nothing (0) to everything (255). An intensity value greater
2609 to the set value is considered non-black. Default value is 24.
2610
2611 @item round
2612 Set the value for which the width/height should be divisible by. The
2613 offset is automatically adjusted to center the video. Use 2 to get
2614 only even dimensions (needed for 4:2:2 video). 16 is best when
2615 encoding to most video codecs. Default value is 16.
2616
2617 @item reset_count, reset
2618 Set the counter that determines after how many frames cropdetect will
2619 reset the previously detected largest video area and start over to
2620 detect the current optimal crop area. Default value is 0.
2621
2622 This can be useful when channel logos distort the video area. 0
2623 indicates never reset and return the largest area encountered during
2624 playback.
2625 @end table
2626
2627 @anchor{curves}
2628 @section curves
2629
2630 Apply color adjustments using curves.
2631
2632 This filter is similar to the Adobe Photoshop and GIMP curves tools. Each
2633 component (red, green and blue) has its values defined by @var{N} key points
2634 tied from each other using a smooth curve. The x-axis represents the pixel
2635 values from the input frame, and the y-axis the new pixel values to be set for
2636 the output frame.
2637
2638 By default, a component curve is defined by the two points @var{(0;0)} and
2639 @var{(1;1)}. This creates a straight line where each original pixel value is
2640 "adjusted" to its own value, which means no change to the image.
2641
2642 The filter allows you to redefine these two points and add some more. A new
2643 curve (using a natural cubic spline interpolation) will be define to pass
2644 smoothly through all these new coordinates. The new defined points needs to be
2645 strictly increasing over the x-axis, and their @var{x} and @var{y} values must
2646 be in the @var{[0;1]} interval.  If the computed curves happened to go outside
2647 the vector spaces, the values will be clipped accordingly.
2648
2649 If there is no key point defined in @code{x=0}, the filter will automatically
2650 insert a @var{(0;0)} point. In the same way, if there is no key point defined
2651 in @code{x=1}, the filter will automatically insert a @var{(1;1)} point.
2652
2653 The filter accepts the following options:
2654
2655 @table @option
2656 @item preset
2657 Select one of the available color presets. This option can be used in addition
2658 to the @option{r}, @option{g}, @option{b} parameters; in this case, the later
2659 options takes priority on the preset values.
2660 Available presets are:
2661 @table @samp
2662 @item none
2663 @item color_negative
2664 @item cross_process
2665 @item darker
2666 @item increase_contrast
2667 @item lighter
2668 @item linear_contrast
2669 @item medium_contrast
2670 @item negative
2671 @item strong_contrast
2672 @item vintage
2673 @end table
2674 Default is @code{none}.
2675 @item master, m
2676 Set the master key points. These points will define a second pass mapping. It
2677 is sometimes called a "luminance" or "value" mapping. It can be used with
2678 @option{r}, @option{g}, @option{b} or @option{all} since it acts like a
2679 post-processing LUT.
2680 @item red, r
2681 Set the key points for the red component.
2682 @item green, g
2683 Set the key points for the green component.
2684 @item blue, b
2685 Set the key points for the blue component.
2686 @item all
2687 Set the key points for all components (not including master).
2688 Can be used in addition to the other key points component
2689 options. In this case, the unset component(s) will fallback on this
2690 @option{all} setting.
2691 @item psfile
2692 Specify a Photoshop curves file (@code{.asv}) to import the settings from.
2693 @end table
2694
2695 To avoid some filtergraph syntax conflicts, each key points list need to be
2696 defined using the following syntax: @code{x0/y0 x1/y1 x2/y2 ...}.
2697
2698 @subsection Examples
2699
2700 @itemize
2701 @item
2702 Increase slightly the middle level of blue:
2703 @example
2704 curves=blue='0.5/0.58'
2705 @end example
2706
2707 @item
2708 Vintage effect:
2709 @example
2710 curves=r='0/0.11 .42/.51 1/0.95':g='0.50/0.48':b='0/0.22 .49/.44 1/0.8'
2711 @end example
2712 Here we obtain the following coordinates for each components:
2713 @table @var
2714 @item red
2715 @code{(0;0.11) (0.42;0.51) (1;0.95)}
2716 @item green
2717 @code{(0;0) (0.50;0.48) (1;1)}
2718 @item blue
2719 @code{(0;0.22) (0.49;0.44) (1;0.80)}
2720 @end table
2721
2722 @item
2723 The previous example can also be achieved with the associated built-in preset:
2724 @example
2725 curves=preset=vintage
2726 @end example
2727
2728 @item
2729 Or simply:
2730 @example
2731 curves=vintage
2732 @end example
2733
2734 @item
2735 Use a Photoshop preset and redefine the points of the green component:
2736 @example
2737 curves=psfile='MyCurvesPresets/purple.asv':green='0.45/0.53'
2738 @end example
2739 @end itemize
2740
2741 @section dctdnoiz
2742
2743 Denoise frames using 2D DCT (frequency domain filtering).
2744
2745 This filter is not designed for real time and can be extremely slow.
2746
2747 The filter accepts the following options:
2748
2749 @table @option
2750 @item sigma, s
2751 Set the noise sigma constant.
2752
2753 This @var{sigma} defines a hard threshold of @code{3 * sigma}; every DCT
2754 coefficient (absolute value) below this threshold with be dropped.
2755
2756 If you need a more advanced filtering, see @option{expr}.
2757
2758 Default is @code{0}.
2759
2760 @item overlap
2761 Set number overlapping pixels for each block. Each block is of size
2762 @code{16x16}. Since the filter can be slow, you may want to reduce this value,
2763 at the cost of a less effective filter and the risk of various artefacts.
2764
2765 If the overlapping value doesn't allow to process the whole input width or
2766 height, a warning will be displayed and according borders won't be denoised.
2767
2768 Default value is @code{15}.
2769
2770 @item expr, e
2771 Set the coefficient factor expression.
2772
2773 For each coefficient of a DCT block, this expression will be evaluated as a
2774 multiplier value for the coefficient.
2775
2776 If this is option is set, the @option{sigma} option will be ignored.
2777
2778 The absolute value of the coefficient can be accessed through the @var{c}
2779 variable.
2780 @end table
2781
2782 @subsection Examples
2783
2784 Apply a denoise with a @option{sigma} of @code{4.5}:
2785 @example
2786 dctdnoiz=4.5
2787 @end example
2788
2789 The same operation can be achieved using the expression system:
2790 @example
2791 dctdnoiz=e='gte(c, 4.5*3)'
2792 @end example
2793
2794 @anchor{decimate}
2795 @section decimate
2796
2797 Drop duplicated frames at regular intervals.
2798
2799 The filter accepts the following options:
2800
2801 @table @option
2802 @item cycle
2803 Set the number of frames from which one will be dropped. Setting this to
2804 @var{N} means one frame in every batch of @var{N} frames will be dropped.
2805 Default is @code{5}.
2806
2807 @item dupthresh
2808 Set the threshold for duplicate detection. If the difference metric for a frame
2809 is less than or equal to this value, then it is declared as duplicate. Default
2810 is @code{1.1}
2811
2812 @item scthresh
2813 Set scene change threshold. Default is @code{15}.
2814
2815 @item blockx
2816 @item blocky
2817 Set the size of the x and y-axis blocks used during metric calculations.
2818 Larger blocks give better noise suppression, but also give worse detection of
2819 small movements. Must be a power of two. Default is @code{32}.
2820
2821 @item ppsrc
2822 Mark main input as a pre-processed input and activate clean source input
2823 stream. This allows the input to be pre-processed with various filters to help
2824 the metrics calculation while keeping the frame selection lossless. When set to
2825 @code{1}, the first stream is for the pre-processed input, and the second
2826 stream is the clean source from where the kept frames are chosen. Default is
2827 @code{0}.
2828
2829 @item chroma
2830 Set whether or not chroma is considered in the metric calculations. Default is
2831 @code{1}.
2832 @end table
2833
2834 @section delogo
2835
2836 Suppress a TV station logo by a simple interpolation of the surrounding
2837 pixels. Just set a rectangle covering the logo and watch it disappear
2838 (and sometimes something even uglier appear - your mileage may vary).
2839
2840 This filter accepts the following options:
2841 @table @option
2842
2843 @item x
2844 @item y
2845 Specify the top left corner coordinates of the logo. They must be
2846 specified.
2847
2848 @item w
2849 @item h
2850 Specify the width and height of the logo to clear. They must be
2851 specified.
2852
2853 @item band, t
2854 Specify the thickness of the fuzzy edge of the rectangle (added to
2855 @var{w} and @var{h}). The default value is 4.
2856
2857 @item show
2858 When set to 1, a green rectangle is drawn on the screen to simplify
2859 finding the right @var{x}, @var{y}, @var{w}, and @var{h} parameters.
2860 The default value is 0.
2861
2862 The rectangle is drawn on the outermost pixels which will be (partly)
2863 replaced with interpolated values. The values of the next pixels
2864 immediately outside this rectangle in each direction will be used to
2865 compute the interpolated pixel values inside the rectangle.
2866
2867 @end table
2868
2869 @subsection Examples
2870
2871 @itemize
2872 @item
2873 Set a rectangle covering the area with top left corner coordinates 0,0
2874 and size 100x77, setting a band of size 10:
2875 @example
2876 delogo=x=0:y=0:w=100:h=77:band=10
2877 @end example
2878
2879 @end itemize
2880
2881 @section deshake
2882
2883 Attempt to fix small changes in horizontal and/or vertical shift. This
2884 filter helps remove camera shake from hand-holding a camera, bumping a
2885 tripod, moving on a vehicle, etc.
2886
2887 The filter accepts the following options:
2888
2889 @table @option
2890
2891 @item x
2892 @item y
2893 @item w
2894 @item h
2895 Specify a rectangular area where to limit the search for motion
2896 vectors.
2897 If desired the search for motion vectors can be limited to a
2898 rectangular area of the frame defined by its top left corner, width
2899 and height. These parameters have the same meaning as the drawbox
2900 filter which can be used to visualise the position of the bounding
2901 box.
2902
2903 This is useful when simultaneous movement of subjects within the frame
2904 might be confused for camera motion by the motion vector search.
2905
2906 If any or all of @var{x}, @var{y}, @var{w} and @var{h} are set to -1
2907 then the full frame is used. This allows later options to be set
2908 without specifying the bounding box for the motion vector search.
2909
2910 Default - search the whole frame.
2911
2912 @item rx
2913 @item ry
2914 Specify the maximum extent of movement in x and y directions in the
2915 range 0-64 pixels. Default 16.
2916
2917 @item edge
2918 Specify how to generate pixels to fill blanks at the edge of the
2919 frame. Available values are:
2920 @table @samp
2921 @item blank, 0
2922 Fill zeroes at blank locations
2923 @item original, 1
2924 Original image at blank locations
2925 @item clamp, 2
2926 Extruded edge value at blank locations
2927 @item mirror, 3
2928 Mirrored edge at blank locations
2929 @end table
2930 Default value is @samp{mirror}.
2931
2932 @item blocksize
2933 Specify the blocksize to use for motion search. Range 4-128 pixels,
2934 default 8.
2935
2936 @item contrast
2937 Specify the contrast threshold for blocks. Only blocks with more than
2938 the specified contrast (difference between darkest and lightest
2939 pixels) will be considered. Range 1-255, default 125.
2940
2941 @item search
2942 Specify the search strategy. Available values are:
2943 @table @samp
2944 @item exhaustive, 0
2945 Set exhaustive search
2946 @item less, 1
2947 Set less exhaustive search.
2948 @end table
2949 Default value is @samp{exhaustive}.
2950
2951 @item filename
2952 If set then a detailed log of the motion search is written to the
2953 specified file.
2954
2955 @item opencl
2956 If set to 1, specify using OpenCL capabilities, only available if
2957 FFmpeg was configured with @code{--enable-opencl}. Default value is 0.
2958
2959 @end table
2960
2961 @section drawbox
2962
2963 Draw a colored box on the input image.
2964
2965 This filter accepts the following options:
2966
2967 @table @option
2968 @item x
2969 @item y
2970 The expressions which specify the top left corner coordinates of the box. Default to 0.
2971
2972 @item width, w
2973 @item height, h
2974 The expressions which specify the width and height of the box, if 0 they are interpreted as
2975 the input width and height. Default to 0.
2976
2977 @item color, c
2978 Specify the color of the box to write, it can be the name of a color
2979 (case insensitive match) or a 0xRRGGBB[AA] sequence. If the special
2980 value @code{invert} is used, the box edge color is the same as the
2981 video with inverted luma.
2982
2983 @item thickness, t
2984 The expression which sets the thickness of the box edge. Default value is @code{3}.
2985
2986 See below for the list of accepted constants.
2987 @end table
2988
2989 The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
2990 following constants:
2991
2992 @table @option
2993 @item dar
2994 The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
2995
2996 @item hsub
2997 @item vsub
2998 horizontal and vertical chroma subsample values. For example for the
2999 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
3000
3001 @item in_h, ih
3002 @item in_w, iw
3003 The input width and height.
3004
3005 @item sar
3006 The input sample aspect ratio.
3007
3008 @item x
3009 @item y
3010 The x and y offset coordinates where the box is drawn.
3011
3012 @item w
3013 @item h
3014 The width and height of the drawn box.
3015
3016 @item t
3017 The thickness of the drawn box.
3018
3019 These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
3020 each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
3021
3022 @end table
3023
3024 @subsection Examples
3025
3026 @itemize
3027 @item
3028 Draw a black box around the edge of the input image:
3029 @example
3030 drawbox
3031 @end example
3032
3033 @item
3034 Draw a box with color red and an opacity of 50%:
3035 @example
3036 drawbox=10:20:200:60:red@@0.5
3037 @end example
3038
3039 The previous example can be specified as:
3040 @example
3041 drawbox=x=10:y=20:w=200:h=60:color=red@@0.5
3042 @end example
3043
3044 @item
3045 Fill the box with pink color:
3046 @example
3047 drawbox=x=10:y=10:w=100:h=100:color=pink@@0.5:t=max
3048 @end example
3049
3050 @item
3051 Draw a 2-pixel red 2.40:1 mask:
3052 @example
3053 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
3054 @end example
3055 @end itemize
3056
3057 @section drawgrid
3058
3059 Draw a grid on the input image.
3060
3061 This filter accepts the following options:
3062
3063 @table @option
3064 @item x
3065 @item y
3066 The expressions which specify the coordinates of some point of grid intersection (meant to configure offset). Both default to 0.
3067
3068 @item width, w
3069 @item height, h
3070 The expressions which specify the width and height of the grid cell, if 0 they are interpreted as the
3071 input width and height, respectively, minus @code{thickness}, so image gets
3072 framed. Default to 0.
3073
3074 @item color, c
3075 Specify the color of the grid, it can be the name of a color
3076 (case insensitive match) or a 0xRRGGBB[AA] sequence. If the special
3077 value @code{invert} is used, the grid color is the same as the
3078 video with inverted luma.
3079 Note that you can append opacity value (in range of 0.0 - 1.0)
3080 to color name after @@ sign.
3081
3082 @item thickness, t
3083 The expression which sets the thickness of the grid line. Default value is @code{1}.
3084
3085 See below for the list of accepted constants.
3086 @end table
3087
3088 The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
3089 following constants:
3090
3091 @table @option
3092 @item dar
3093 The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
3094
3095 @item hsub
3096 @item vsub
3097 horizontal and vertical chroma subsample values. For example for the
3098 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
3099
3100 @item in_h, ih
3101 @item in_w, iw
3102 The input grid cell width and height.
3103
3104 @item sar
3105 The input sample aspect ratio.
3106
3107 @item x
3108 @item y
3109 The x and y coordinates of some point of grid intersection (meant to configure offset).
3110
3111 @item w
3112 @item h
3113 The width and height of the drawn cell.
3114
3115 @item t
3116 The thickness of the drawn cell.
3117
3118 These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
3119 each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
3120
3121 @end table
3122
3123 @subsection Examples
3124
3125 @itemize
3126 @item
3127 Draw a grid with cell 100x100 pixels, thickness 2 pixels, with color red and an opacity of 50%:
3128 @example
3129 drawgrid=width=100:height=100:thickness=2:color=red@@0.5
3130 @end example
3131
3132 @item
3133 Draw a white 3x3 grid with an opacity of 50%:
3134 @example
3135 drawgrid=w=iw/3:h=ih/3:t=2:c=white@@0.5
3136 @end example
3137 @end itemize
3138
3139 @anchor{drawtext}
3140 @section drawtext
3141
3142 Draw text string or text from specified file on top of video using the
3143 libfreetype library.
3144
3145 To enable compilation of this filter you need to configure FFmpeg with
3146 @code{--enable-libfreetype}.
3147
3148 @subsection Syntax
3149
3150 The description of the accepted parameters follows.
3151
3152 @table @option
3153
3154 @item box
3155 Used to draw a box around text using background color.
3156 Value should be either 1 (enable) or 0 (disable).
3157 The default value of @var{box} is 0.
3158
3159 @item boxcolor
3160 The color to be used for drawing box around text.
3161 Either a string (e.g. "yellow") or in 0xRRGGBB[AA] format
3162 (e.g. "0xff00ff"), possibly followed by an alpha specifier.
3163 The default value of @var{boxcolor} is "white".
3164
3165 @item draw
3166 Set an expression which specifies if the text should be drawn. If the
3167 expression evaluates to 0, the text is not drawn. This is useful for
3168 specifying that the text should be drawn only when specific conditions
3169 are met.
3170
3171 Default value is "1".
3172
3173 See below for the list of accepted constants and functions.
3174
3175 @item expansion
3176 Select how the @var{text} is expanded. Can be either @code{none},
3177 @code{strftime} (deprecated) or
3178 @code{normal} (default). See the @ref{drawtext_expansion, Text expansion} section
3179 below for details.
3180
3181 @item fix_bounds
3182 If true, check and fix text coords to avoid clipping.
3183
3184 @item fontcolor
3185 The color to be used for drawing fonts.
3186 Either a string (e.g. "red") or in 0xRRGGBB[AA] format
3187 (e.g. "0xff000033"), possibly followed by an alpha specifier.
3188 The default value of @var{fontcolor} is "black".
3189
3190 @item fontfile
3191 The font file to be used for drawing text. Path must be included.
3192 This parameter is mandatory.
3193
3194 @item fontsize
3195 The font size to be used for drawing text.
3196 The default value of @var{fontsize} is 16.
3197
3198 @item ft_load_flags
3199 Flags to be used for loading the fonts.
3200
3201 The flags map the corresponding flags supported by libfreetype, and are
3202 a combination of the following values:
3203 @table @var
3204 @item default
3205 @item no_scale
3206 @item no_hinting
3207 @item render
3208 @item no_bitmap
3209 @item vertical_layout
3210 @item force_autohint
3211 @item crop_bitmap
3212 @item pedantic
3213 @item ignore_global_advance_width
3214 @item no_recurse
3215 @item ignore_transform
3216 @item monochrome
3217 @item linear_design
3218 @item no_autohint
3219 @end table
3220
3221 Default value is "render".
3222
3223 For more information consult the documentation for the FT_LOAD_*
3224 libfreetype flags.
3225
3226 @item shadowcolor
3227 The color to be used for drawing a shadow behind the drawn text.  It
3228 can be a color name (e.g. "yellow") or a string in the 0xRRGGBB[AA]
3229 form (e.g. "0xff00ff"), possibly followed by an alpha specifier.
3230 The default value of @var{shadowcolor} is "black".
3231
3232 @item shadowx
3233 @item shadowy
3234 The x and y offsets for the text shadow position with respect to the
3235 position of the text. They can be either positive or negative
3236 values. Default value for both is "0".
3237
3238 @item start_number
3239 The starting frame number for the n/frame_num variable. The default value
3240 is "0".
3241
3242 @item tabsize
3243 The size in number of spaces to use for rendering the tab.
3244 Default value is 4.
3245
3246 @item timecode
3247 Set the initial timecode representation in "hh:mm:ss[:;.]ff"
3248 format. It can be used with or without text parameter. @var{timecode_rate}
3249 option must be specified.
3250
3251 @item timecode_rate, rate, r
3252 Set the timecode frame rate (timecode only).
3253
3254 @item text
3255 The text string to be drawn. The text must be a sequence of UTF-8
3256 encoded characters.
3257 This parameter is mandatory if no file is specified with the parameter
3258 @var{textfile}.
3259
3260 @item textfile
3261 A text file containing text to be drawn. The text must be a sequence
3262 of UTF-8 encoded characters.
3263
3264 This parameter is mandatory if no text string is specified with the
3265 parameter @var{text}.
3266
3267 If both @var{text} and @var{textfile} are specified, an error is thrown.
3268
3269 @item reload
3270 If set to 1, the @var{textfile} will be reloaded before each frame.
3271 Be sure to update it atomically, or it may be read partially, or even fail.
3272
3273 @item x
3274 @item y
3275 The expressions which specify the offsets where text will be drawn
3276 within the video frame. They are relative to the top/left border of the
3277 output image.
3278
3279 The default value of @var{x} and @var{y} is "0".
3280
3281 See below for the list of accepted constants and functions.
3282 @end table
3283
3284 The parameters for @var{x} and @var{y} are expressions containing the
3285 following constants and functions:
3286
3287 @table @option
3288 @item dar
3289 input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
3290
3291 @item hsub
3292 @item vsub
3293 horizontal and vertical chroma subsample values. For example for the
3294 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
3295
3296 @item line_h, lh
3297 the height of each text line
3298
3299 @item main_h, h, H
3300 the input height
3301
3302 @item main_w, w, W
3303 the input width
3304
3305 @item max_glyph_a, ascent
3306 the maximum distance from the baseline to the highest/upper grid
3307 coordinate used to place a glyph outline point, for all the rendered
3308 glyphs.
3309 It is a positive value, due to the grid's orientation with the Y axis
3310 upwards.
3311
3312 @item max_glyph_d, descent
3313 the maximum distance from the baseline to the lowest grid coordinate
3314 used to place a glyph outline point, for all the rendered glyphs.
3315 This is a negative value, due to the grid's orientation, with the Y axis
3316 upwards.
3317
3318 @item max_glyph_h
3319 maximum glyph height, that is the maximum height for all the glyphs
3320 contained in the rendered text, it is equivalent to @var{ascent} -
3321 @var{descent}.
3322
3323 @item max_glyph_w
3324 maximum glyph width, that is the maximum width for all the glyphs
3325 contained in the rendered text
3326
3327 @item n
3328 the number of input frame, starting from 0
3329
3330 @item rand(min, max)
3331 return a random number included between @var{min} and @var{max}
3332
3333 @item sar
3334 input sample aspect ratio
3335
3336 @item t
3337 timestamp expressed in seconds, NAN if the input timestamp is unknown
3338
3339 @item text_h, th
3340 the height of the rendered text
3341
3342 @item text_w, tw
3343 the width of the rendered text
3344
3345 @item x
3346 @item y
3347 the x and y offset coordinates where the text is drawn.
3348
3349 These parameters allow the @var{x} and @var{y} expressions to refer
3350 each other, so you can for example specify @code{y=x/dar}.
3351 @end table
3352
3353 If libavfilter was built with @code{--enable-fontconfig}, then
3354 @option{fontfile} can be a fontconfig pattern or omitted.
3355
3356 @anchor{drawtext_expansion}
3357 @subsection Text expansion
3358
3359 If @option{expansion} is set to @code{strftime},
3360 the filter recognizes strftime() sequences in the provided text and
3361 expands them accordingly. Check the documentation of strftime(). This
3362 feature is deprecated.
3363
3364 If @option{expansion} is set to @code{none}, the text is printed verbatim.
3365
3366 If @option{expansion} is set to @code{normal} (which is the default),
3367 the following expansion mechanism is used.
3368
3369 The backslash character '\', followed by any character, always expands to
3370 the second character.
3371
3372 Sequence of the form @code{%@{...@}} are expanded. The text between the
3373 braces is a function name, possibly followed by arguments separated by ':'.
3374 If the arguments contain special characters or delimiters (':' or '@}'),
3375 they should be escaped.
3376
3377 Note that they probably must also be escaped as the value for the
3378 @option{text} option in the filter argument string and as the filter
3379 argument in the filtergraph description, and possibly also for the shell,
3380 that makes up to four levels of escaping; using a text file avoids these
3381 problems.
3382
3383 The following functions are available:
3384
3385 @table @command
3386
3387 @item expr, e
3388 The expression evaluation result.
3389
3390 It must take one argument specifying the expression to be evaluated,
3391 which accepts the same constants and functions as the @var{x} and
3392 @var{y} values. Note that not all constants should be used, for
3393 example the text size is not known when evaluating the expression, so
3394 the constants @var{text_w} and @var{text_h} will have an undefined
3395 value.
3396
3397 @item gmtime
3398 The time at which the filter is running, expressed in UTC.
3399 It can accept an argument: a strftime() format string.
3400
3401 @item localtime
3402 The time at which the filter is running, expressed in the local time zone.
3403 It can accept an argument: a strftime() format string.
3404
3405 @item metadata
3406 Frame metadata. It must take one argument specifying metadata key.
3407
3408 @item n, frame_num
3409 The frame number, starting from 0.
3410
3411 @item pict_type
3412 A 1 character description of the current picture type.
3413
3414 @item pts
3415 The timestamp of the current frame, in seconds, with microsecond accuracy.
3416
3417 @end table
3418
3419 @subsection Examples
3420
3421 @itemize
3422 @item
3423 Draw "Test Text" with font FreeSerif, using the default values for the
3424 optional parameters.
3425
3426 @example
3427 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"
3428 @end example
3429
3430 @item
3431 Draw 'Test Text' with font FreeSerif of size 24 at position x=100
3432 and y=50 (counting from the top-left corner of the screen), text is
3433 yellow with a red box around it. Both the text and the box have an
3434 opacity of 20%.
3435
3436 @example
3437 drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
3438           x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2"
3439 @end example
3440
3441 Note that the double quotes are not necessary if spaces are not used
3442 within the parameter list.
3443
3444 @item
3445 Show the text at the center of the video frame:
3446 @example
3447 drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h-line_h)/2"
3448 @end example
3449
3450 @item
3451 Show a text line sliding from right to left in the last row of the video
3452 frame. The file @file{LONG_LINE} is assumed to contain a single line
3453 with no newlines.
3454 @example
3455 drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t"
3456 @end example
3457
3458 @item
3459 Show the content of file @file{CREDITS} off the bottom of the frame and scroll up.
3460 @example
3461 drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t"
3462 @end example
3463
3464 @item
3465 Draw a single green letter "g", at the center of the input video.
3466 The glyph baseline is placed at half screen height.
3467 @example
3468 drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent"
3469 @end example
3470
3471 @item
3472 Show text for 1 second every 3 seconds:
3473 @example
3474 drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:draw=lt(mod(t\,3)\,1):text='blink'"
3475 @end example
3476
3477 @item
3478 Use fontconfig to set the font. Note that the colons need to be escaped.
3479 @example
3480 drawtext='fontfile=Linux Libertine O-40\:style=Semibold:text=FFmpeg'
3481 @end example
3482
3483 @item
3484 Print the date of a real-time encoding (see strftime(3)):
3485 @example
3486 drawtext='fontfile=FreeSans.ttf:text=%@{localtime:%a %b %d %Y@}'
3487 @end example
3488
3489 @end itemize
3490
3491 For more information about libfreetype, check:
3492 @url{http://www.freetype.org/}.
3493
3494 For more information about fontconfig, check:
3495 @url{http://freedesktop.org/software/fontconfig/fontconfig-user.html}.
3496
3497 @section edgedetect
3498
3499 Detect and draw edges. The filter uses the Canny Edge Detection algorithm.
3500
3501 The filter accepts the following options:
3502
3503 @table @option
3504 @item low
3505 @item high
3506 Set low and high threshold values used by the Canny thresholding
3507 algorithm.
3508
3509 The high threshold selects the "strong" edge pixels, which are then
3510 connected through 8-connectivity with the "weak" edge pixels selected
3511 by the low threshold.
3512
3513 @var{low} and @var{high} threshold values must be choosen in the range
3514 [0,1], and @var{low} should be lesser or equal to @var{high}.
3515
3516 Default value for @var{low} is @code{20/255}, and default value for @var{high}
3517 is @code{50/255}.
3518 @end table
3519
3520 Example:
3521 @example
3522 edgedetect=low=0.1:high=0.4
3523 @end example
3524
3525 @section extractplanes
3526
3527 Extract color channel components from input video stream into
3528 separate grayscale video streams.
3529
3530 The filter accepts the following option:
3531
3532 @table @option
3533 @item planes
3534 Set plane(s) to extract.
3535
3536 Available values for planes are:
3537 @table @samp
3538 @item y
3539 @item u
3540 @item v
3541 @item a
3542 @item r
3543 @item g
3544 @item b
3545 @end table
3546
3547 Choosing planes not available in the input will result in an error.
3548 That means you cannot select @code{r}, @code{g}, @code{b} planes
3549 with @code{y}, @code{u}, @code{v} planes at same time.
3550 @end table
3551
3552 @subsection Examples
3553
3554 @itemize
3555 @item
3556 Extract luma, u and v color channel component from input video frame
3557 into 3 grayscale outputs:
3558 @example
3559 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
3560 @end example
3561 @end itemize
3562
3563 @section fade
3564
3565 Apply fade-in/out effect to input video.
3566
3567 This filter accepts the following options:
3568
3569 @table @option
3570 @item type, t
3571 The effect type -- can be either "in" for fade-in, or "out" for a fade-out
3572 effect.
3573 Default is @code{in}.
3574
3575 @item start_frame, s
3576 Specify the number of the start frame for starting to apply the fade
3577 effect. Default is 0.
3578
3579 @item nb_frames, n
3580 The number of frames for which the fade effect has to last. At the end of the
3581 fade-in effect the output video will have the same intensity as the input video,
3582 at the end of the fade-out transition the output video will be completely black.
3583 Default is 25.
3584
3585 @item alpha
3586 If set to 1, fade only alpha channel, if one exists on the input.
3587 Default value is 0.
3588
3589 @item start_time, st
3590 Specify the timestamp (in seconds) of the frame to start to apply the fade
3591 effect. If both start_frame and start_time are specified, the fade will start at
3592 whichever comes last.  Default is 0.
3593
3594 @item duration, d
3595 The number of seconds for which the fade effect has to last. At the end of the
3596 fade-in effect the output video will have the same intensity as the input video,
3597 at the end of the fade-out transition the output video will be completely black.
3598 If both duration and nb_frames are specified, duration is used. Default is 0.
3599 @end table
3600
3601 @subsection Examples
3602
3603 @itemize
3604 @item
3605 Fade in first 30 frames of video:
3606 @example
3607 fade=in:0:30
3608 @end example
3609
3610 The command above is equivalent to:
3611 @example
3612 fade=t=in:s=0:n=30
3613 @end example
3614
3615 @item
3616 Fade out last 45 frames of a 200-frame video:
3617 @example
3618 fade=out:155:45
3619 fade=type=out:start_frame=155:nb_frames=45
3620 @end example
3621
3622 @item
3623 Fade in first 25 frames and fade out last 25 frames of a 1000-frame video:
3624 @example
3625 fade=in:0:25, fade=out:975:25
3626 @end example
3627
3628 @item
3629 Make first 5 frames black, then fade in from frame 5-24:
3630 @example
3631 fade=in:5:20
3632 @end example
3633
3634 @item
3635 Fade in alpha over first 25 frames of video:
3636 @example
3637 fade=in:0:25:alpha=1
3638 @end example
3639
3640 @item
3641 Make first 5.5 seconds black, then fade in for 0.5 seconds:
3642 @example
3643 fade=t=in:st=5.5:d=0.5
3644 @end example
3645
3646 @end itemize
3647
3648 @section field
3649
3650 Extract a single field from an interlaced image using stride
3651 arithmetic to avoid wasting CPU time. The output frames are marked as
3652 non-interlaced.
3653
3654 The filter accepts the following options:
3655
3656 @table @option
3657 @item type
3658 Specify whether to extract the top (if the value is @code{0} or
3659 @code{top}) or the bottom field (if the value is @code{1} or
3660 @code{bottom}).
3661 @end table
3662
3663 @section fieldmatch
3664
3665 Field matching filter for inverse telecine. It is meant to reconstruct the
3666 progressive frames from a telecined stream. The filter does not drop duplicated
3667 frames, so to achieve a complete inverse telecine @code{fieldmatch} needs to be
3668 followed by a decimation filter such as @ref{decimate} in the filtergraph.
3669
3670 The separation of the field matching and the decimation is notably motivated by
3671 the possibility of inserting a de-interlacing filter fallback between the two.
3672 If the source has mixed telecined and real interlaced content,
3673 @code{fieldmatch} will not be able to match fields for the interlaced parts.
3674 But these remaining combed frames will be marked as interlaced, and thus can be
3675 de-interlaced by a later filter such as @ref{yadif} before decimation.
3676
3677 In addition to the various configuration options, @code{fieldmatch} can take an
3678 optional second stream, activated through the @option{ppsrc} option. If
3679 enabled, the frames reconstruction will be based on the fields and frames from
3680 this second stream. This allows the first input to be pre-processed in order to
3681 help the various algorithms of the filter, while keeping the output lossless
3682 (assuming the fields are matched properly). Typically, a field-aware denoiser,
3683 or brightness/contrast adjustments can help.
3684
3685 Note that this filter uses the same algorithms as TIVTC/TFM (AviSynth project)
3686 and VIVTC/VFM (VapourSynth project). The later is a light clone of TFM from
3687 which @code{fieldmatch} is based on. While the semantic and usage are very
3688 close, some behaviour and options names can differ.
3689
3690 The filter accepts the following options:
3691
3692 @table @option
3693 @item order
3694 Specify the assumed field order of the input stream. Available values are:
3695
3696 @table @samp
3697 @item auto
3698 Auto detect parity (use FFmpeg's internal parity value).
3699 @item bff
3700 Assume bottom field first.
3701 @item tff
3702 Assume top field first.
3703 @end table
3704
3705 Note that it is sometimes recommended not to trust the parity announced by the
3706 stream.
3707
3708 Default value is @var{auto}.
3709
3710 @item mode
3711 Set the matching mode or strategy to use. @option{pc} mode is the safest in the
3712 sense that it won't risk creating jerkiness due to duplicate frames when
3713 possible, but if there are bad edits or blended fields it will end up
3714 outputting combed frames when a good match might actually exist. On the other
3715 hand, @option{pcn_ub} mode is the most risky in terms of creating jerkiness,
3716 but will almost always find a good frame if there is one. The other values are
3717 all somewhere in between @option{pc} and @option{pcn_ub} in terms of risking
3718 jerkiness and creating duplicate frames versus finding good matches in sections
3719 with bad edits, orphaned fields, blended fields, etc.
3720
3721 More details about p/c/n/u/b are available in @ref{p/c/n/u/b meaning} section.
3722
3723 Available values are:
3724
3725 @table @samp
3726 @item pc
3727 2-way matching (p/c)
3728 @item pc_n
3729 2-way matching, and trying 3rd match if still combed (p/c + n)
3730 @item pc_u
3731 2-way matching, and trying 3rd match (same order) if still combed (p/c + u)
3732 @item pc_n_ub
3733 2-way matching, trying 3rd match if still combed, and trying 4th/5th matches if
3734 still combed (p/c + n + u/b)
3735 @item pcn
3736 3-way matching (p/c/n)
3737 @item pcn_ub
3738 3-way matching, and trying 4th/5th matches if all 3 of the original matches are
3739 detected as combed (p/c/n + u/b)
3740 @end table
3741
3742 The parenthesis at the end indicate the matches that would be used for that
3743 mode assuming @option{order}=@var{tff} (and @option{field} on @var{auto} or
3744 @var{top}).
3745
3746 In terms of speed @option{pc} mode is by far the fastest and @option{pcn_ub} is
3747 the slowest.
3748
3749 Default value is @var{pc_n}.
3750
3751 @item ppsrc
3752 Mark the main input stream as a pre-processed input, and enable the secondary
3753 input stream as the clean source to pick the fields from. See the filter
3754 introduction for more details. It is similar to the @option{clip2} feature from
3755 VFM/TFM.
3756
3757 Default value is @code{0} (disabled).
3758
3759 @item field
3760 Set the field to match from. It is recommended to set this to the same value as
3761 @option{order} unless you experience matching failures with that setting. In
3762 certain circumstances changing the field that is used to match from can have a
3763 large impact on matching performance. Available values are:
3764
3765 @table @samp
3766 @item auto
3767 Automatic (same value as @option{order}).
3768 @item bottom
3769 Match from the bottom field.
3770 @item top
3771 Match from the top field.
3772 @end table
3773
3774 Default value is @var{auto}.
3775
3776 @item mchroma
3777 Set whether or not chroma is included during the match comparisons. In most
3778 cases it is recommended to leave this enabled. You should set this to @code{0}
3779 only if your clip has bad chroma problems such as heavy rainbowing or other
3780 artifacts. Setting this to @code{0} could also be used to speed things up at
3781 the cost of some accuracy.
3782
3783 Default value is @code{1}.
3784
3785 @item y0
3786 @item y1
3787 These define an exclusion band which excludes the lines between @option{y0} and
3788 @option{y1} from being included in the field matching decision. An exclusion
3789 band can be used to ignore subtitles, a logo, or other things that may
3790 interfere with the matching. @option{y0} sets the starting scan line and
3791 @option{y1} sets the ending line; all lines in between @option{y0} and
3792 @option{y1} (including @option{y0} and @option{y1}) will be ignored. Setting
3793 @option{y0} and @option{y1} to the same value will disable the feature.
3794 @option{y0} and @option{y1} defaults to @code{0}.
3795
3796 @item scthresh
3797 Set the scene change detection threshold as a percentage of maximum change on
3798 the luma plane. Good values are in the @code{[8.0, 14.0]} range. Scene change
3799 detection is only relevant in case @option{combmatch}=@var{sc}.  The range for
3800 @option{scthresh} is @code{[0.0, 100.0]}.
3801
3802 Default value is @code{12.0}.
3803
3804 @item combmatch
3805 When @option{combatch} is not @var{none}, @code{fieldmatch} will take into
3806 account the combed scores of matches when deciding what match to use as the
3807 final match. Available values are:
3808
3809 @table @samp
3810 @item none
3811 No final matching based on combed scores.
3812 @item sc
3813 Combed scores are only used when a scene change is detected.
3814 @item full
3815 Use combed scores all the time.
3816 @end table
3817
3818 Default is @var{sc}.
3819
3820 @item combdbg
3821 Force @code{fieldmatch} to calculate the combed metrics for certain matches and
3822 print them. This setting is known as @option{micout} in TFM/VFM vocabulary.
3823 Available values are:
3824
3825 @table @samp
3826 @item none
3827 No forced calculation.
3828 @item pcn
3829 Force p/c/n calculations.
3830 @item pcnub
3831 Force p/c/n/u/b calculations.
3832 @end table
3833
3834 Default value is @var{none}.
3835
3836 @item cthresh
3837 This is the area combing threshold used for combed frame detection. This
3838 essentially controls how "strong" or "visible" combing must be to be detected.
3839 Larger values mean combing must be more visible and smaller values mean combing
3840 can be less visible or strong and still be detected. Valid settings are from
3841 @code{-1} (every pixel will be detected as combed) to @code{255} (no pixel will
3842 be detected as combed). This is basically a pixel difference value. A good
3843 range is @code{[8, 12]}.
3844
3845 Default value is @code{9}.
3846
3847 @item chroma
3848 Sets whether or not chroma is considered in the combed frame decision.  Only
3849 disable this if your source has chroma problems (rainbowing, etc.) that are
3850 causing problems for the combed frame detection with chroma enabled. Actually,
3851 using @option{chroma}=@var{0} is usually more reliable, except for the case
3852 where there is chroma only combing in the source.
3853
3854 Default value is @code{0}.
3855
3856 @item blockx
3857 @item blocky
3858 Respectively set the x-axis and y-axis size of the window used during combed
3859 frame detection. This has to do with the size of the area in which
3860 @option{combpel} pixels are required to be detected as combed for a frame to be
3861 declared combed. See the @option{combpel} parameter description for more info.
3862 Possible values are any number that is a power of 2 starting at 4 and going up
3863 to 512.
3864
3865 Default value is @code{16}.
3866
3867 @item combpel
3868 The number of combed pixels inside any of the @option{blocky} by
3869 @option{blockx} size blocks on the frame for the frame to be detected as
3870 combed. While @option{cthresh} controls how "visible" the combing must be, this
3871 setting controls "how much" combing there must be in any localized area (a
3872 window defined by the @option{blockx} and @option{blocky} settings) on the
3873 frame. Minimum value is @code{0} and maximum is @code{blocky x blockx} (at
3874 which point no frames will ever be detected as combed). This setting is known
3875 as @option{MI} in TFM/VFM vocabulary.
3876
3877 Default value is @code{80}.
3878 @end table
3879
3880 @anchor{p/c/n/u/b meaning}
3881 @subsection p/c/n/u/b meaning
3882
3883 @subsubsection p/c/n
3884
3885 We assume the following telecined stream:
3886
3887 @example
3888 Top fields:     1 2 2 3 4
3889 Bottom fields:  1 2 3 4 4
3890 @end example
3891
3892 The numbers correspond to the progressive frame the fields relate to. Here, the
3893 first two frames are progressive, the 3rd and 4th are combed, and so on.
3894
3895 When @code{fieldmatch} is configured to run a matching from bottom
3896 (@option{field}=@var{bottom}) this is how this input stream get transformed:
3897
3898 @example
3899 Input stream:
3900                 T     1 2 2 3 4
3901                 B     1 2 3 4 4   <-- matching reference
3902
3903 Matches:              c c n n c
3904
3905 Output stream:
3906                 T     1 2 3 4 4
3907                 B     1 2 3 4 4
3908 @end example
3909
3910 As a result of the field matching, we can see that some frames get duplicated.
3911 To perform a complete inverse telecine, you need to rely on a decimation filter
3912 after this operation. See for instance the @ref{decimate} filter.
3913
3914 The same operation now matching from top fields (@option{field}=@var{top})
3915 looks like this:
3916
3917 @example
3918 Input stream:
3919                 T     1 2 2 3 4   <-- matching reference
3920                 B     1 2 3 4 4
3921
3922 Matches:              c c p p c
3923
3924 Output stream:
3925                 T     1 2 2 3 4
3926                 B     1 2 2 3 4
3927 @end example
3928
3929 In these examples, we can see what @var{p}, @var{c} and @var{n} mean;
3930 basically, they refer to the frame and field of the opposite parity:
3931
3932 @itemize
3933 @item @var{p} matches the field of the opposite parity in the previous frame
3934 @item @var{c} matches the field of the opposite parity in the current frame
3935 @item @var{n} matches the field of the opposite parity in the next frame
3936 @end itemize
3937
3938 @subsubsection u/b
3939
3940 The @var{u} and @var{b} matching are a bit special in the sense that they match
3941 from the opposite parity flag. In the following examples, we assume that we are
3942 currently matching the 2nd frame (Top:2, bottom:2). According to the match, a
3943 'x' is placed above and below each matched fields.
3944
3945 With bottom matching (@option{field}=@var{bottom}):
3946 @example
3947 Match:           c         p           n          b          u
3948
3949                  x       x               x        x          x
3950   Top          1 2 2     1 2 2       1 2 2      1 2 2      1 2 2
3951   Bottom       1 2 3     1 2 3       1 2 3      1 2 3      1 2 3
3952                  x         x           x        x              x
3953
3954 Output frames:
3955                  2          1          2          2          2
3956                  2          2          2          1          3
3957 @end example
3958
3959 With top matching (@option{field}=@var{top}):
3960 @example
3961 Match:           c         p           n          b          u
3962
3963                  x         x           x        x              x
3964   Top          1 2 2     1 2 2       1 2 2      1 2 2      1 2 2
3965   Bottom       1 2 3     1 2 3       1 2 3      1 2 3      1 2 3
3966                  x       x               x        x          x
3967
3968 Output frames:
3969                  2          2          2          1          2
3970                  2          1          3          2          2
3971 @end example
3972
3973 @subsection Examples
3974
3975 Simple IVTC of a top field first telecined stream:
3976 @example
3977 fieldmatch=order=tff:combmatch=none, decimate
3978 @end example
3979
3980 Advanced IVTC, with fallback on @ref{yadif} for still combed frames:
3981 @example
3982 fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate
3983 @end example
3984
3985 @section fieldorder
3986
3987 Transform the field order of the input video.
3988
3989 This filter accepts the following options:
3990
3991 @table @option
3992
3993 @item order
3994 Output field order. Valid values are @var{tff} for top field first or @var{bff}
3995 for bottom field first.
3996 @end table
3997
3998 Default value is @samp{tff}.
3999
4000 Transformation is achieved by shifting the picture content up or down
4001 by one line, and filling the remaining line with appropriate picture content.
4002 This method is consistent with most broadcast field order converters.
4003
4004 If the input video is not flagged as being interlaced, or it is already
4005 flagged as being of the required output field order then this filter does
4006 not alter the incoming video.
4007
4008 This filter is very useful when converting to or from PAL DV material,
4009 which is bottom field first.
4010
4011 For example:
4012 @example
4013 ffmpeg -i in.vob -vf "fieldorder=bff" out.dv
4014 @end example
4015
4016 @section fifo
4017
4018 Buffer input images and send them when they are requested.
4019
4020 This filter is mainly useful when auto-inserted by the libavfilter
4021 framework.
4022
4023 The filter does not take parameters.
4024
4025 @anchor{format}
4026 @section format
4027
4028 Convert the input video to one of the specified pixel formats.
4029 Libavfilter will try to pick one that is supported for the input to
4030 the next filter.
4031
4032 This filter accepts the following parameters:
4033 @table @option
4034
4035 @item pix_fmts
4036 A '|'-separated list of pixel format names, for example
4037 "pix_fmts=yuv420p|monow|rgb24".
4038
4039 @end table
4040
4041 @subsection Examples
4042
4043 @itemize
4044 @item
4045 Convert the input video to the format @var{yuv420p}
4046 @example
4047 format=pix_fmts=yuv420p
4048 @end example
4049
4050 Convert the input video to any of the formats in the list
4051 @example
4052 format=pix_fmts=yuv420p|yuv444p|yuv410p
4053 @end example
4054 @end itemize
4055
4056 @section fps
4057
4058 Convert the video to specified constant frame rate by duplicating or dropping
4059 frames as necessary.
4060
4061 This filter accepts the following named parameters:
4062 @table @option
4063
4064 @item fps
4065 Desired output frame rate. The default is @code{25}.
4066
4067 @item round
4068 Rounding method.
4069
4070 Possible values are:
4071 @table @option
4072 @item zero
4073 zero round towards 0
4074 @item inf
4075 round away from 0
4076 @item down
4077 round towards -infinity
4078 @item up
4079 round towards +infinity
4080 @item near
4081 round to nearest
4082 @end table
4083 The default is @code{near}.
4084
4085 @end table
4086
4087 Alternatively, the options can be specified as a flat string:
4088 @var{fps}[:@var{round}].
4089
4090 See also the @ref{setpts} filter.
4091
4092 @subsection Examples
4093
4094 @itemize
4095 @item
4096 A typical usage in order to set the fps to 25:
4097 @example
4098 fps=fps=25
4099 @end example
4100
4101 @item
4102 Sets the fps to 24, using abbreviation and rounding method to round to nearest:
4103 @example
4104 fps=fps=film:round=near
4105 @end example
4106 @end itemize
4107
4108 @section framestep
4109
4110 Select one frame every N-th frame.
4111
4112 This filter accepts the following option:
4113 @table @option
4114 @item step
4115 Select frame after every @code{step} frames.
4116 Allowed values are positive integers higher than 0. Default value is @code{1}.
4117 @end table
4118
4119 @anchor{frei0r}
4120 @section frei0r
4121
4122 Apply a frei0r effect to the input video.
4123
4124 To enable compilation of this filter you need to install the frei0r
4125 header and configure FFmpeg with @code{--enable-frei0r}.
4126
4127 This filter accepts the following options:
4128
4129 @table @option
4130
4131 @item filter_name
4132 The name to the frei0r effect to load. If the environment variable
4133 @env{FREI0R_PATH} is defined, the frei0r effect is searched in each one of the
4134 directories specified by the colon separated list in @env{FREIOR_PATH},
4135 otherwise in the standard frei0r paths, which are in this order:
4136 @file{HOME/.frei0r-1/lib/}, @file{/usr/local/lib/frei0r-1/},
4137 @file{/usr/lib/frei0r-1/}.
4138
4139 @item filter_params
4140 A '|'-separated list of parameters to pass to the frei0r effect.
4141
4142 @end table
4143
4144 A frei0r effect parameter can be a boolean (whose values are specified
4145 with "y" and "n"), a double, a color (specified by the syntax
4146 @var{R}/@var{G}/@var{B}, @var{R}, @var{G}, and @var{B} being float
4147 numbers from 0.0 to 1.0) or by an @code{av_parse_color()} color
4148 description), a position (specified by the syntax @var{X}/@var{Y},
4149 @var{X} and @var{Y} being float numbers) and a string.
4150
4151 The number and kind of parameters depend on the loaded effect. If an
4152 effect parameter is not specified the default value is set.
4153
4154 @subsection Examples
4155
4156 @itemize
4157 @item
4158 Apply the distort0r effect, set the first two double parameters:
4159 @example
4160 frei0r=filter_name=distort0r:filter_params=0.5|0.01
4161 @end example
4162
4163 @item
4164 Apply the colordistance effect, take a color as first parameter:
4165 @example
4166 frei0r=colordistance:0.2/0.3/0.4
4167 frei0r=colordistance:violet
4168 frei0r=colordistance:0x112233
4169 @end example
4170
4171 @item
4172 Apply the perspective effect, specify the top left and top right image
4173 positions:
4174 @example
4175 frei0r=perspective:0.2/0.2|0.8/0.2
4176 @end example
4177 @end itemize
4178
4179 For more information see:
4180 @url{http://frei0r.dyne.org}
4181
4182 @section geq
4183
4184 The filter accepts the following options:
4185
4186 @table @option
4187 @item lum_expr, lum
4188 Set the luminance expression.
4189 @item cb_expr, cb
4190 Set the chrominance blue expression.
4191 @item cr_expr, cr
4192 Set the chrominance red expression.
4193 @item alpha_expr, a
4194 Set the alpha expression.
4195 @item red_expr, r
4196 Set the red expression.
4197 @item green_expr, g
4198 Set the green expression.
4199 @item blue_expr, b
4200 Set the blue expression.
4201 @end table
4202
4203 The colorspace is selected according to the specified options. If one
4204 of the @option{lum_expr}, @option{cb_expr}, or @option{cr_expr}
4205 options is specified, t