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