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