9c7cc2284b9f51ab8bce216a6d130c74d6b21e39
[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{id}=@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 optionally followed by "@@@var{id}".
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{FILTER_NAME}      ::= @var{NAME}["@@"@var{NAME}]
216 @var{LINKLABEL}        ::= "[" @var{NAME} "]"
217 @var{LINKLABELS}       ::= @var{LINKLABEL} [@var{LINKLABELS}]
218 @var{FILTER_ARGUMENTS} ::= sequence of chars (possibly quoted)
219 @var{FILTER}           ::= [@var{LINKLABELS}] @var{FILTER_NAME} ["=" @var{FILTER_ARGUMENTS}] [@var{LINKLABELS}]
220 @var{FILTERCHAIN}      ::= @var{FILTER} [,@var{FILTERCHAIN}]
221 @var{FILTERGRAPH}      ::= [sws_flags=@var{flags};] @var{FILTERCHAIN} [;@var{FILTERGRAPH}]
222 @end example
223
224 @anchor{filtergraph escaping}
225 @section Notes on filtergraph escaping
226
227 Filtergraph description composition entails several levels of
228 escaping. See @ref{quoting_and_escaping,,the "Quoting and escaping"
229 section in the ffmpeg-utils(1) manual,ffmpeg-utils} for more
230 information about the employed escaping procedure.
231
232 A first level escaping affects the content of each filter option
233 value, which may contain the special character @code{:} used to
234 separate values, or one of the escaping characters @code{\'}.
235
236 A second level escaping affects the whole filter description, which
237 may contain the escaping characters @code{\'} or the special
238 characters @code{[],;} used by the filtergraph description.
239
240 Finally, when you specify a filtergraph on a shell commandline, you
241 need to perform a third level escaping for the shell special
242 characters contained within it.
243
244 For example, consider the following string to be embedded in
245 the @ref{drawtext} filter description @option{text} value:
246 @example
247 this is a 'string': may contain one, or more, special characters
248 @end example
249
250 This string contains the @code{'} special escaping character, and the
251 @code{:} special character, so it needs to be escaped in this way:
252 @example
253 text=this is a \'string\'\: may contain one, or more, special characters
254 @end example
255
256 A second level of escaping is required when embedding the filter
257 description in a filtergraph description, in order to escape all the
258 filtergraph special characters. Thus the example above becomes:
259 @example
260 drawtext=text=this is a \\\'string\\\'\\: may contain one\, or more\, special characters
261 @end example
262 (note that in addition to the @code{\'} escaping special characters,
263 also @code{,} needs to be escaped).
264
265 Finally an additional level of escaping is needed when writing the
266 filtergraph description in a shell command, which depends on the
267 escaping rules of the adopted shell. For example, assuming that
268 @code{\} is special and needs to be escaped with another @code{\}, the
269 previous string will finally result in:
270 @example
271 -vf "drawtext=text=this is a \\\\\\'string\\\\\\'\\\\: may contain one\\, or more\\, special characters"
272 @end example
273
274 @chapter Timeline editing
275
276 Some filters support a generic @option{enable} option. For the filters
277 supporting timeline editing, this option can be set to an expression which is
278 evaluated before sending a frame to the filter. If the evaluation is non-zero,
279 the filter will be enabled, otherwise the frame will be sent unchanged to the
280 next filter in the filtergraph.
281
282 The expression accepts the following values:
283 @table @samp
284 @item t
285 timestamp expressed in seconds, NAN if the input timestamp is unknown
286
287 @item n
288 sequential number of the input frame, starting from 0
289
290 @item pos
291 the position in the file of the input frame, NAN if unknown
292
293 @item w
294 @item h
295 width and height of the input frame if video
296 @end table
297
298 Additionally, these filters support an @option{enable} command that can be used
299 to re-define the expression.
300
301 Like any other filtering option, the @option{enable} option follows the same
302 rules.
303
304 For example, to enable a blur filter (@ref{smartblur}) from 10 seconds to 3
305 minutes, and a @ref{curves} filter starting at 3 seconds:
306 @example
307 smartblur = enable='between(t,10,3*60)',
308 curves    = enable='gte(t,3)' : preset=cross_process
309 @end example
310
311 See @code{ffmpeg -filters} to view which filters have timeline support.
312
313 @c man end FILTERGRAPH DESCRIPTION
314
315 @anchor{framesync}
316 @chapter Options for filters with several inputs (framesync)
317 @c man begin OPTIONS FOR FILTERS WITH SEVERAL INPUTS
318
319 Some filters with several inputs support a common set of options.
320 These options can only be set by name, not with the short notation.
321
322 @table @option
323 @item eof_action
324 The action to take when EOF is encountered on the secondary input; it accepts
325 one of the following values:
326
327 @table @option
328 @item repeat
329 Repeat the last frame (the default).
330 @item endall
331 End both streams.
332 @item pass
333 Pass the main input through.
334 @end table
335
336 @item shortest
337 If set to 1, force the output to terminate when the shortest input
338 terminates. Default value is 0.
339
340 @item repeatlast
341 If set to 1, force the filter to extend the last frame of secondary streams
342 until the end of the primary stream. A value of 0 disables this behavior.
343 Default value is 1.
344 @end table
345
346 @c man end OPTIONS FOR FILTERS WITH SEVERAL INPUTS
347
348 @chapter Audio Filters
349 @c man begin AUDIO FILTERS
350
351 When you configure your FFmpeg build, you can disable any of the
352 existing filters using @code{--disable-filters}.
353 The configure output will show the audio filters included in your
354 build.
355
356 Below is a description of the currently available audio filters.
357
358 @section acompressor
359
360 A compressor is mainly used to reduce the dynamic range of a signal.
361 Especially modern music is mostly compressed at a high ratio to
362 improve the overall loudness. It's done to get the highest attention
363 of a listener, "fatten" the sound and bring more "power" to the track.
364 If a signal is compressed too much it may sound dull or "dead"
365 afterwards or it may start to "pump" (which could be a powerful effect
366 but can also destroy a track completely).
367 The right compression is the key to reach a professional sound and is
368 the high art of mixing and mastering. Because of its complex settings
369 it may take a long time to get the right feeling for this kind of effect.
370
371 Compression is done by detecting the volume above a chosen level
372 @code{threshold} and dividing it by the factor set with @code{ratio}.
373 So if you set the threshold to -12dB and your signal reaches -6dB a ratio
374 of 2:1 will result in a signal at -9dB. Because an exact manipulation of
375 the signal would cause distortion of the waveform the reduction can be
376 levelled over the time. This is done by setting "Attack" and "Release".
377 @code{attack} determines how long the signal has to rise above the threshold
378 before any reduction will occur and @code{release} sets the time the signal
379 has to fall below the threshold to reduce the reduction again. Shorter signals
380 than the chosen attack time will be left untouched.
381 The overall reduction of the signal can be made up afterwards with the
382 @code{makeup} setting. So compressing the peaks of a signal about 6dB and
383 raising the makeup to this level results in a signal twice as loud than the
384 source. To gain a softer entry in the compression the @code{knee} flattens the
385 hard edge at the threshold in the range of the chosen decibels.
386
387 The filter accepts the following options:
388
389 @table @option
390 @item level_in
391 Set input gain. Default is 1. Range is between 0.015625 and 64.
392
393 @item threshold
394 If a signal of stream rises above this level it will affect the gain
395 reduction.
396 By default it is 0.125. Range is between 0.00097563 and 1.
397
398 @item ratio
399 Set a ratio by which the signal is reduced. 1:2 means that if the level
400 rose 4dB above the threshold, it will be only 2dB above after the reduction.
401 Default is 2. Range is between 1 and 20.
402
403 @item attack
404 Amount of milliseconds the signal has to rise above the threshold before gain
405 reduction starts. Default is 20. Range is between 0.01 and 2000.
406
407 @item release
408 Amount of milliseconds the signal has to fall below the threshold before
409 reduction is decreased again. Default is 250. Range is between 0.01 and 9000.
410
411 @item makeup
412 Set the amount by how much signal will be amplified after processing.
413 Default is 1. Range is from 1 to 64.
414
415 @item knee
416 Curve the sharp knee around the threshold to enter gain reduction more softly.
417 Default is 2.82843. Range is between 1 and 8.
418
419 @item link
420 Choose if the @code{average} level between all channels of input stream
421 or the louder(@code{maximum}) channel of input stream affects the
422 reduction. Default is @code{average}.
423
424 @item detection
425 Should the exact signal be taken in case of @code{peak} or an RMS one in case
426 of @code{rms}. Default is @code{rms} which is mostly smoother.
427
428 @item mix
429 How much to use compressed signal in output. Default is 1.
430 Range is between 0 and 1.
431 @end table
432
433 @section acontrast
434 Simple audio dynamic range commpression/expansion filter.
435
436 The filter accepts the following options:
437
438 @table @option
439 @item contrast
440 Set contrast. Default is 33. Allowed range is between 0 and 100.
441 @end table
442
443 @section acopy
444
445 Copy the input audio source unchanged to the output. This is mainly useful for
446 testing purposes.
447
448 @section acrossfade
449
450 Apply cross fade from one input audio stream to another input audio stream.
451 The cross fade is applied for specified duration near the end of first stream.
452
453 The filter accepts the following options:
454
455 @table @option
456 @item nb_samples, ns
457 Specify the number of samples for which the cross fade effect has to last.
458 At the end of the cross fade effect the first input audio will be completely
459 silent. Default is 44100.
460
461 @item duration, d
462 Specify the duration of the cross fade effect. See
463 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
464 for the accepted syntax.
465 By default the duration is determined by @var{nb_samples}.
466 If set this option is used instead of @var{nb_samples}.
467
468 @item overlap, o
469 Should first stream end overlap with second stream start. Default is enabled.
470
471 @item curve1
472 Set curve for cross fade transition for first stream.
473
474 @item curve2
475 Set curve for cross fade transition for second stream.
476
477 For description of available curve types see @ref{afade} filter description.
478 @end table
479
480 @subsection Examples
481
482 @itemize
483 @item
484 Cross fade from one input to another:
485 @example
486 ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:c1=exp:c2=exp output.flac
487 @end example
488
489 @item
490 Cross fade from one input to another but without overlapping:
491 @example
492 ffmpeg -i first.flac -i second.flac -filter_complex acrossfade=d=10:o=0:c1=exp:c2=exp output.flac
493 @end example
494 @end itemize
495
496 @section acrossover
497 Split audio stream into several bands.
498
499 This filter splits audio stream into two or more frequency ranges.
500 Summing all streams back will give flat output.
501
502 The filter accepts the following options:
503
504 @table @option
505 @item split
506 Set split frequencies. Those must be positive and increasing.
507
508 @item order
509 Set filter order, can be @var{2nd}, @var{4th} or @var{8th}.
510 Default is @var{4th}.
511 @end table
512
513 @section acrusher
514
515 Reduce audio bit resolution.
516
517 This filter is bit crusher with enhanced functionality. A bit crusher
518 is used to audibly reduce number of bits an audio signal is sampled
519 with. This doesn't change the bit depth at all, it just produces the
520 effect. Material reduced in bit depth sounds more harsh and "digital".
521 This filter is able to even round to continuous values instead of discrete
522 bit depths.
523 Additionally it has a D/C offset which results in different crushing of
524 the lower and the upper half of the signal.
525 An Anti-Aliasing setting is able to produce "softer" crushing sounds.
526
527 Another feature of this filter is the logarithmic mode.
528 This setting switches from linear distances between bits to logarithmic ones.
529 The result is a much more "natural" sounding crusher which doesn't gate low
530 signals for example. The human ear has a logarithmic perception,
531 so this kind of crushing is much more pleasant.
532 Logarithmic crushing is also able to get anti-aliased.
533
534 The filter accepts the following options:
535
536 @table @option
537 @item level_in
538 Set level in.
539
540 @item level_out
541 Set level out.
542
543 @item bits
544 Set bit reduction.
545
546 @item mix
547 Set mixing amount.
548
549 @item mode
550 Can be linear: @code{lin} or logarithmic: @code{log}.
551
552 @item dc
553 Set DC.
554
555 @item aa
556 Set anti-aliasing.
557
558 @item samples
559 Set sample reduction.
560
561 @item lfo
562 Enable LFO. By default disabled.
563
564 @item lforange
565 Set LFO range.
566
567 @item lforate
568 Set LFO rate.
569 @end table
570
571 @section acue
572
573 Delay audio filtering until a given wallclock timestamp. See the @ref{cue}
574 filter.
575
576 @section adeclick
577 Remove impulsive noise from input audio.
578
579 Samples detected as impulsive noise are replaced by interpolated samples using
580 autoregressive modelling.
581
582 @table @option
583 @item w
584 Set window size, in milliseconds. Allowed range is from @code{10} to
585 @code{100}. Default value is @code{55} milliseconds.
586 This sets size of window which will be processed at once.
587
588 @item o
589 Set window overlap, in percentage of window size. Allowed range is from
590 @code{50} to @code{95}. Default value is @code{75} percent.
591 Setting this to a very high value increases impulsive noise removal but makes
592 whole process much slower.
593
594 @item a
595 Set autoregression order, in percentage of window size. Allowed range is from
596 @code{0} to @code{25}. Default value is @code{2} percent. This option also
597 controls quality of interpolated samples using neighbour good samples.
598
599 @item t
600 Set threshold value. Allowed range is from @code{1} to @code{100}.
601 Default value is @code{2}.
602 This controls the strength of impulsive noise which is going to be removed.
603 The lower value, the more samples will be detected as impulsive noise.
604
605 @item b
606 Set burst fusion, in percentage of window size. Allowed range is @code{0} to
607 @code{10}. Default value is @code{2}.
608 If any two samples deteced as noise are spaced less than this value then any
609 sample inbetween those two samples will be also detected as noise.
610
611 @item m
612 Set overlap method.
613
614 It accepts the following values:
615 @table @option
616 @item a
617 Select overlap-add method. Even not interpolated samples are slightly
618 changed with this method.
619
620 @item s
621 Select overlap-save method. Not interpolated samples remain unchanged.
622 @end table
623
624 Default value is @code{a}.
625 @end table
626
627 @section adeclip
628 Remove clipped samples from input audio.
629
630 Samples detected as clipped are replaced by interpolated samples using
631 autoregressive modelling.
632
633 @table @option
634 @item w
635 Set window size, in milliseconds. Allowed range is from @code{10} to @code{100}.
636 Default value is @code{55} milliseconds.
637 This sets size of window which will be processed at once.
638
639 @item o
640 Set window overlap, in percentage of window size. Allowed range is from @code{50}
641 to @code{95}. Default value is @code{75} percent.
642
643 @item a
644 Set autoregression order, in percentage of window size. Allowed range is from
645 @code{0} to @code{25}. Default value is @code{8} percent. This option also controls
646 quality of interpolated samples using neighbour good samples.
647
648 @item t
649 Set threshold value. Allowed range is from @code{1} to @code{100}.
650 Default value is @code{10}. Higher values make clip detection less aggressive.
651
652 @item n
653 Set size of histogram used to detect clips. Allowed range is from @code{100} to @code{9999}.
654 Default value is @code{1000}. Higher values make clip detection less aggressive.
655
656 @item m
657 Set overlap method.
658
659 It accepts the following values:
660 @table @option
661 @item a
662 Select overlap-add method. Even not interpolated samples are slightly changed
663 with this method.
664
665 @item s
666 Select overlap-save method. Not interpolated samples remain unchanged.
667 @end table
668
669 Default value is @code{a}.
670 @end table
671
672 @section adelay
673
674 Delay one or more audio channels.
675
676 Samples in delayed channel are filled with silence.
677
678 The filter accepts the following option:
679
680 @table @option
681 @item delays
682 Set list of delays in milliseconds for each channel separated by '|'.
683 Unused delays will be silently ignored. If number of given delays is
684 smaller than number of channels all remaining channels will not be delayed.
685 If you want to delay exact number of samples, append 'S' to number.
686 @end table
687
688 @subsection Examples
689
690 @itemize
691 @item
692 Delay first channel by 1.5 seconds, the third channel by 0.5 seconds and leave
693 the second channel (and any other channels that may be present) unchanged.
694 @example
695 adelay=1500|0|500
696 @end example
697
698 @item
699 Delay second channel by 500 samples, the third channel by 700 samples and leave
700 the first channel (and any other channels that may be present) unchanged.
701 @example
702 adelay=0|500S|700S
703 @end example
704 @end itemize
705
706 @section aderivative, aintegral
707
708 Compute derivative/integral of audio stream.
709
710 Applying both filters one after another produces original audio.
711
712 @section aecho
713
714 Apply echoing to the input audio.
715
716 Echoes are reflected sound and can occur naturally amongst mountains
717 (and sometimes large buildings) when talking or shouting; digital echo
718 effects emulate this behaviour and are often used to help fill out the
719 sound of a single instrument or vocal. The time difference between the
720 original signal and the reflection is the @code{delay}, and the
721 loudness of the reflected signal is the @code{decay}.
722 Multiple echoes can have different delays and decays.
723
724 A description of the accepted parameters follows.
725
726 @table @option
727 @item in_gain
728 Set input gain of reflected signal. Default is @code{0.6}.
729
730 @item out_gain
731 Set output gain of reflected signal. Default is @code{0.3}.
732
733 @item delays
734 Set list of time intervals in milliseconds between original signal and reflections
735 separated by '|'. Allowed range for each @code{delay} is @code{(0 - 90000.0]}.
736 Default is @code{1000}.
737
738 @item decays
739 Set list of loudness of reflected signals separated by '|'.
740 Allowed range for each @code{decay} is @code{(0 - 1.0]}.
741 Default is @code{0.5}.
742 @end table
743
744 @subsection Examples
745
746 @itemize
747 @item
748 Make it sound as if there are twice as many instruments as are actually playing:
749 @example
750 aecho=0.8:0.88:60:0.4
751 @end example
752
753 @item
754 If delay is very short, then it sound like a (metallic) robot playing music:
755 @example
756 aecho=0.8:0.88:6:0.4
757 @end example
758
759 @item
760 A longer delay will sound like an open air concert in the mountains:
761 @example
762 aecho=0.8:0.9:1000:0.3
763 @end example
764
765 @item
766 Same as above but with one more mountain:
767 @example
768 aecho=0.8:0.9:1000|1800:0.3|0.25
769 @end example
770 @end itemize
771
772 @section aemphasis
773 Audio emphasis filter creates or restores material directly taken from LPs or
774 emphased CDs with different filter curves. E.g. to store music on vinyl the
775 signal has to be altered by a filter first to even out the disadvantages of
776 this recording medium.
777 Once the material is played back the inverse filter has to be applied to
778 restore the distortion of the frequency response.
779
780 The filter accepts the following options:
781
782 @table @option
783 @item level_in
784 Set input gain.
785
786 @item level_out
787 Set output gain.
788
789 @item mode
790 Set filter mode. For restoring material use @code{reproduction} mode, otherwise
791 use @code{production} mode. Default is @code{reproduction} mode.
792
793 @item type
794 Set filter type. Selects medium. Can be one of the following:
795
796 @table @option
797 @item col
798 select Columbia.
799 @item emi
800 select EMI.
801 @item bsi
802 select BSI (78RPM).
803 @item riaa
804 select RIAA.
805 @item cd
806 select Compact Disc (CD).
807 @item 50fm
808 select 50µs (FM).
809 @item 75fm
810 select 75µs (FM).
811 @item 50kf
812 select 50µs (FM-KF).
813 @item 75kf
814 select 75µs (FM-KF).
815 @end table
816 @end table
817
818 @section aeval
819
820 Modify an audio signal according to the specified expressions.
821
822 This filter accepts one or more expressions (one for each channel),
823 which are evaluated and used to modify a corresponding audio signal.
824
825 It accepts the following parameters:
826
827 @table @option
828 @item exprs
829 Set the '|'-separated expressions list for each separate channel. If
830 the number of input channels is greater than the number of
831 expressions, the last specified expression is used for the remaining
832 output channels.
833
834 @item channel_layout, c
835 Set output channel layout. If not specified, the channel layout is
836 specified by the number of expressions. If set to @samp{same}, it will
837 use by default the same input channel layout.
838 @end table
839
840 Each expression in @var{exprs} can contain the following constants and functions:
841
842 @table @option
843 @item ch
844 channel number of the current expression
845
846 @item n
847 number of the evaluated sample, starting from 0
848
849 @item s
850 sample rate
851
852 @item t
853 time of the evaluated sample expressed in seconds
854
855 @item nb_in_channels
856 @item nb_out_channels
857 input and output number of channels
858
859 @item val(CH)
860 the value of input channel with number @var{CH}
861 @end table
862
863 Note: this filter is slow. For faster processing you should use a
864 dedicated filter.
865
866 @subsection Examples
867
868 @itemize
869 @item
870 Half volume:
871 @example
872 aeval=val(ch)/2:c=same
873 @end example
874
875 @item
876 Invert phase of the second channel:
877 @example
878 aeval=val(0)|-val(1)
879 @end example
880 @end itemize
881
882 @anchor{afade}
883 @section afade
884
885 Apply fade-in/out effect to input audio.
886
887 A description of the accepted parameters follows.
888
889 @table @option
890 @item type, t
891 Specify the effect type, can be either @code{in} for fade-in, or
892 @code{out} for a fade-out effect. Default is @code{in}.
893
894 @item start_sample, ss
895 Specify the number of the start sample for starting to apply the fade
896 effect. Default is 0.
897
898 @item nb_samples, ns
899 Specify the number of samples for which the fade effect has to last. At
900 the end of the fade-in effect the output audio will have the same
901 volume as the input audio, at the end of the fade-out transition
902 the output audio will be silence. Default is 44100.
903
904 @item start_time, st
905 Specify the start time of the fade effect. Default is 0.
906 The value must be specified as a time duration; see
907 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
908 for the accepted syntax.
909 If set this option is used instead of @var{start_sample}.
910
911 @item duration, d
912 Specify the duration of the fade effect. See
913 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
914 for the accepted syntax.
915 At the end of the fade-in effect the output audio will have the same
916 volume as the input audio, at the end of the fade-out transition
917 the output audio will be silence.
918 By default the duration is determined by @var{nb_samples}.
919 If set this option is used instead of @var{nb_samples}.
920
921 @item curve
922 Set curve for fade transition.
923
924 It accepts the following values:
925 @table @option
926 @item tri
927 select triangular, linear slope (default)
928 @item qsin
929 select quarter of sine wave
930 @item hsin
931 select half of sine wave
932 @item esin
933 select exponential sine wave
934 @item log
935 select logarithmic
936 @item ipar
937 select inverted parabola
938 @item qua
939 select quadratic
940 @item cub
941 select cubic
942 @item squ
943 select square root
944 @item cbr
945 select cubic root
946 @item par
947 select parabola
948 @item exp
949 select exponential
950 @item iqsin
951 select inverted quarter of sine wave
952 @item ihsin
953 select inverted half of sine wave
954 @item dese
955 select double-exponential seat
956 @item desi
957 select double-exponential sigmoid
958 @item losi
959 select logistic sigmoid
960 @end table
961 @end table
962
963 @subsection Examples
964
965 @itemize
966 @item
967 Fade in first 15 seconds of audio:
968 @example
969 afade=t=in:ss=0:d=15
970 @end example
971
972 @item
973 Fade out last 25 seconds of a 900 seconds audio:
974 @example
975 afade=t=out:st=875:d=25
976 @end example
977 @end itemize
978
979 @section afftdn
980 Denoise audio samples with FFT.
981
982 A description of the accepted parameters follows.
983
984 @table @option
985 @item nr
986 Set the noise reduction in dB, allowed range is 0.01 to 97.
987 Default value is 12 dB.
988
989 @item nf
990 Set the noise floor in dB, allowed range is -80 to -20.
991 Default value is -50 dB.
992
993 @item nt
994 Set the noise type.
995
996 It accepts the following values:
997 @table @option
998 @item w
999 Select white noise.
1000
1001 @item v
1002 Select vinyl noise.
1003
1004 @item s
1005 Select shellac noise.
1006
1007 @item c
1008 Select custom noise, defined in @code{bn} option.
1009
1010 Default value is white noise.
1011 @end table
1012
1013 @item bn
1014 Set custom band noise for every one of 15 bands.
1015 Bands are separated by ' ' or '|'.
1016
1017 @item rf
1018 Set the residual floor in dB, allowed range is -80 to -20.
1019 Default value is -38 dB.
1020
1021 @item tn
1022 Enable noise tracking. By default is disabled.
1023 With this enabled, noise floor is automatically adjusted.
1024
1025 @item tr
1026 Enable residual tracking. By default is disabled.
1027
1028 @item om
1029 Set the output mode.
1030
1031 It accepts the following values:
1032 @table @option
1033 @item i
1034 Pass input unchanged.
1035
1036 @item o
1037 Pass noise filtered out.
1038
1039 @item n
1040 Pass only noise.
1041
1042 Default value is @var{o}.
1043 @end table
1044 @end table
1045
1046 @subsection Commands
1047
1048 This filter supports the following commands:
1049 @table @option
1050 @item sample_noise, sn
1051 Start or stop measuring noise profile.
1052 Syntax for the command is : "start" or "stop" string.
1053 After measuring noise profile is stopped it will be
1054 automatically applied in filtering.
1055
1056 @item noise_reduction, nr
1057 Change noise reduction. Argument is single float number.
1058 Syntax for the command is : "@var{noise_reduction}"
1059
1060 @item noise_floor, nf
1061 Change noise floor. Argument is single float number.
1062 Syntax for the command is : "@var{noise_floor}"
1063
1064 @item output_mode, om
1065 Change output mode operation.
1066 Syntax for the command is : "i", "o" or "n" string.
1067 @end table
1068
1069 @section afftfilt
1070 Apply arbitrary expressions to samples in frequency domain.
1071
1072 @table @option
1073 @item real
1074 Set frequency domain real expression for each separate channel separated
1075 by '|'. Default is "1".
1076 If the number of input channels is greater than the number of
1077 expressions, the last specified expression is used for the remaining
1078 output channels.
1079
1080 @item imag
1081 Set frequency domain imaginary expression for each separate channel
1082 separated by '|'. If not set, @var{real} option is used.
1083
1084 Each expression in @var{real} and @var{imag} can contain the following
1085 constants:
1086
1087 @table @option
1088 @item sr
1089 sample rate
1090
1091 @item b
1092 current frequency bin number
1093
1094 @item nb
1095 number of available bins
1096
1097 @item ch
1098 channel number of the current expression
1099
1100 @item chs
1101 number of channels
1102
1103 @item pts
1104 current frame pts
1105 @end table
1106
1107 @item win_size
1108 Set window size.
1109
1110 It accepts the following values:
1111 @table @samp
1112 @item w16
1113 @item w32
1114 @item w64
1115 @item w128
1116 @item w256
1117 @item w512
1118 @item w1024
1119 @item w2048
1120 @item w4096
1121 @item w8192
1122 @item w16384
1123 @item w32768
1124 @item w65536
1125 @end table
1126 Default is @code{w4096}
1127
1128 @item win_func
1129 Set window function. Default is @code{hann}.
1130
1131 @item overlap
1132 Set window overlap. If set to 1, the recommended overlap for selected
1133 window function will be picked. Default is @code{0.75}.
1134 @end table
1135
1136 @subsection Examples
1137
1138 @itemize
1139 @item
1140 Leave almost only low frequencies in audio:
1141 @example
1142 afftfilt="1-clip((b/nb)*b,0,1)"
1143 @end example
1144 @end itemize
1145
1146 @anchor{afir}
1147 @section afir
1148
1149 Apply an arbitrary Frequency Impulse Response filter.
1150
1151 This filter is designed for applying long FIR filters,
1152 up to 60 seconds long.
1153
1154 It can be used as component for digital crossover filters,
1155 room equalization, cross talk cancellation, wavefield synthesis,
1156 auralization, ambiophonics and ambisonics.
1157
1158 This filter uses second stream as FIR coefficients.
1159 If second stream holds single channel, it will be used
1160 for all input channels in first stream, otherwise
1161 number of channels in second stream must be same as
1162 number of channels in first stream.
1163
1164 It accepts the following parameters:
1165
1166 @table @option
1167 @item dry
1168 Set dry gain. This sets input gain.
1169
1170 @item wet
1171 Set wet gain. This sets final output gain.
1172
1173 @item length
1174 Set Impulse Response filter length. Default is 1, which means whole IR is processed.
1175
1176 @item gtype
1177 Enable applying gain measured from power of IR.
1178
1179 Set which approach to use for auto gain measurement.
1180
1181 @table @option
1182 @item none
1183 Do not apply any gain.
1184
1185 @item peak
1186 select peak gain, very conservative approach. This is default value.
1187
1188 @item dc
1189 select DC gain, limited application.
1190
1191 @item gn
1192 select gain to noise approach, this is most popular one.
1193 @end table
1194
1195 @item irgain
1196 Set gain to be applied to IR coefficients before filtering.
1197 Allowed range is 0 to 1. This gain is applied after any gain applied with @var{gtype} option.
1198
1199 @item irfmt
1200 Set format of IR stream. Can be @code{mono} or @code{input}.
1201 Default is @code{input}.
1202
1203 @item maxir
1204 Set max allowed Impulse Response filter duration in seconds. Default is 30 seconds.
1205 Allowed range is 0.1 to 60 seconds.
1206
1207 @item response
1208 Show IR frequency reponse, magnitude(magenta) and phase(green) and group delay(yellow) in additional video stream.
1209 By default it is disabled.
1210
1211 @item channel
1212 Set for which IR channel to display frequency response. By default is first channel
1213 displayed. This option is used only when @var{response} is enabled.
1214
1215 @item size
1216 Set video stream size. This option is used only when @var{response} is enabled.
1217 @end table
1218
1219 @subsection Examples
1220
1221 @itemize
1222 @item
1223 Apply reverb to stream using mono IR file as second input, complete command using ffmpeg:
1224 @example
1225 ffmpeg -i input.wav -i middle_tunnel_1way_mono.wav -lavfi afir output.wav
1226 @end example
1227 @end itemize
1228
1229 @anchor{aformat}
1230 @section aformat
1231
1232 Set output format constraints for the input audio. The framework will
1233 negotiate the most appropriate format to minimize conversions.
1234
1235 It accepts the following parameters:
1236 @table @option
1237
1238 @item sample_fmts
1239 A '|'-separated list of requested sample formats.
1240
1241 @item sample_rates
1242 A '|'-separated list of requested sample rates.
1243
1244 @item channel_layouts
1245 A '|'-separated list of requested channel layouts.
1246
1247 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
1248 for the required syntax.
1249 @end table
1250
1251 If a parameter is omitted, all values are allowed.
1252
1253 Force the output to either unsigned 8-bit or signed 16-bit stereo
1254 @example
1255 aformat=sample_fmts=u8|s16:channel_layouts=stereo
1256 @end example
1257
1258 @section agate
1259
1260 A gate is mainly used to reduce lower parts of a signal. This kind of signal
1261 processing reduces disturbing noise between useful signals.
1262
1263 Gating is done by detecting the volume below a chosen level @var{threshold}
1264 and dividing it by the factor set with @var{ratio}. The bottom of the noise
1265 floor is set via @var{range}. Because an exact manipulation of the signal
1266 would cause distortion of the waveform the reduction can be levelled over
1267 time. This is done by setting @var{attack} and @var{release}.
1268
1269 @var{attack} determines how long the signal has to fall below the threshold
1270 before any reduction will occur and @var{release} sets the time the signal
1271 has to rise above the threshold to reduce the reduction again.
1272 Shorter signals than the chosen attack time will be left untouched.
1273
1274 @table @option
1275 @item level_in
1276 Set input level before filtering.
1277 Default is 1. Allowed range is from 0.015625 to 64.
1278
1279 @item range
1280 Set the level of gain reduction when the signal is below the threshold.
1281 Default is 0.06125. Allowed range is from 0 to 1.
1282
1283 @item threshold
1284 If a signal rises above this level the gain reduction is released.
1285 Default is 0.125. Allowed range is from 0 to 1.
1286
1287 @item ratio
1288 Set a ratio by which the signal is reduced.
1289 Default is 2. Allowed range is from 1 to 9000.
1290
1291 @item attack
1292 Amount of milliseconds the signal has to rise above the threshold before gain
1293 reduction stops.
1294 Default is 20 milliseconds. Allowed range is from 0.01 to 9000.
1295
1296 @item release
1297 Amount of milliseconds the signal has to fall below the threshold before the
1298 reduction is increased again. Default is 250 milliseconds.
1299 Allowed range is from 0.01 to 9000.
1300
1301 @item makeup
1302 Set amount of amplification of signal after processing.
1303 Default is 1. Allowed range is from 1 to 64.
1304
1305 @item knee
1306 Curve the sharp knee around the threshold to enter gain reduction more softly.
1307 Default is 2.828427125. Allowed range is from 1 to 8.
1308
1309 @item detection
1310 Choose if exact signal should be taken for detection or an RMS like one.
1311 Default is @code{rms}. Can be @code{peak} or @code{rms}.
1312
1313 @item link
1314 Choose if the average level between all channels or the louder channel affects
1315 the reduction.
1316 Default is @code{average}. Can be @code{average} or @code{maximum}.
1317 @end table
1318
1319 @section aiir
1320
1321 Apply an arbitrary Infinite Impulse Response filter.
1322
1323 It accepts the following parameters:
1324
1325 @table @option
1326 @item z
1327 Set numerator/zeros coefficients.
1328
1329 @item p
1330 Set denominator/poles coefficients.
1331
1332 @item k
1333 Set channels gains.
1334
1335 @item dry_gain
1336 Set input gain.
1337
1338 @item wet_gain
1339 Set output gain.
1340
1341 @item f
1342 Set coefficients format.
1343
1344 @table @samp
1345 @item tf
1346 transfer function
1347 @item zp
1348 Z-plane zeros/poles, cartesian (default)
1349 @item pr
1350 Z-plane zeros/poles, polar radians
1351 @item pd
1352 Z-plane zeros/poles, polar degrees
1353 @end table
1354
1355 @item r
1356 Set kind of processing.
1357 Can be @code{d} - direct or @code{s} - serial cascading. Defauls is @code{s}.
1358
1359 @item e
1360 Set filtering precision.
1361
1362 @table @samp
1363 @item dbl
1364 double-precision floating-point (default)
1365 @item flt
1366 single-precision floating-point
1367 @item i32
1368 32-bit integers
1369 @item i16
1370 16-bit integers
1371 @end table
1372
1373 @item response
1374 Show IR frequency reponse, magnitude and phase in additional video stream.
1375 By default it is disabled.
1376
1377 @item channel
1378 Set for which IR channel to display frequency response. By default is first channel
1379 displayed. This option is used only when @var{response} is enabled.
1380
1381 @item size
1382 Set video stream size. This option is used only when @var{response} is enabled.
1383 @end table
1384
1385 Coefficients in @code{tf} format are separated by spaces and are in ascending
1386 order.
1387
1388 Coefficients in @code{zp} format are separated by spaces and order of coefficients
1389 doesn't matter. Coefficients in @code{zp} format are complex numbers with @var{i}
1390 imaginary unit.
1391
1392 Different coefficients and gains can be provided for every channel, in such case
1393 use '|' to separate coefficients or gains. Last provided coefficients will be
1394 used for all remaining channels.
1395
1396 @subsection Examples
1397
1398 @itemize
1399 @item
1400 Apply 2 pole elliptic notch at arround 5000Hz for 48000 Hz sample rate:
1401 @example
1402 aiir=k=1:z=7.957584807809675810E-1 -2.575128568908332300 3.674839853930788710 -2.57512875289799137 7.957586296317130880E-1:p=1 -2.86950072432325953 3.63022088054647218 -2.28075678147272232 6.361362326477423500E-1:f=tf:r=d
1403 @end example
1404
1405 @item
1406 Same as above but in @code{zp} format:
1407 @example
1408 aiir=k=0.79575848078096756:z=0.80918701+0.58773007i 0.80918701-0.58773007i 0.80884700+0.58784055i 0.80884700-0.58784055i:p=0.63892345+0.59951235i 0.63892345-0.59951235i 0.79582691+0.44198673i 0.79582691-0.44198673i:f=zp:r=s
1409 @end example
1410 @end itemize
1411
1412 @section alimiter
1413
1414 The limiter prevents an input signal from rising over a desired threshold.
1415 This limiter uses lookahead technology to prevent your signal from distorting.
1416 It means that there is a small delay after the signal is processed. Keep in mind
1417 that the delay it produces is the attack time you set.
1418
1419 The filter accepts the following options:
1420
1421 @table @option
1422 @item level_in
1423 Set input gain. Default is 1.
1424
1425 @item level_out
1426 Set output gain. Default is 1.
1427
1428 @item limit
1429 Don't let signals above this level pass the limiter. Default is 1.
1430
1431 @item attack
1432 The limiter will reach its attenuation level in this amount of time in
1433 milliseconds. Default is 5 milliseconds.
1434
1435 @item release
1436 Come back from limiting to attenuation 1.0 in this amount of milliseconds.
1437 Default is 50 milliseconds.
1438
1439 @item asc
1440 When gain reduction is always needed ASC takes care of releasing to an
1441 average reduction level rather than reaching a reduction of 0 in the release
1442 time.
1443
1444 @item asc_level
1445 Select how much the release time is affected by ASC, 0 means nearly no changes
1446 in release time while 1 produces higher release times.
1447
1448 @item level
1449 Auto level output signal. Default is enabled.
1450 This normalizes audio back to 0dB if enabled.
1451 @end table
1452
1453 Depending on picked setting it is recommended to upsample input 2x or 4x times
1454 with @ref{aresample} before applying this filter.
1455
1456 @section allpass
1457
1458 Apply a two-pole all-pass filter with central frequency (in Hz)
1459 @var{frequency}, and filter-width @var{width}.
1460 An all-pass filter changes the audio's frequency to phase relationship
1461 without changing its frequency to amplitude relationship.
1462
1463 The filter accepts the following options:
1464
1465 @table @option
1466 @item frequency, f
1467 Set frequency in Hz.
1468
1469 @item width_type, t
1470 Set method to specify band-width of filter.
1471 @table @option
1472 @item h
1473 Hz
1474 @item q
1475 Q-Factor
1476 @item o
1477 octave
1478 @item s
1479 slope
1480 @item k
1481 kHz
1482 @end table
1483
1484 @item width, w
1485 Specify the band-width of a filter in width_type units.
1486
1487 @item channels, c
1488 Specify which channels to filter, by default all available are filtered.
1489 @end table
1490
1491 @subsection Commands
1492
1493 This filter supports the following commands:
1494 @table @option
1495 @item frequency, f
1496 Change allpass frequency.
1497 Syntax for the command is : "@var{frequency}"
1498
1499 @item width_type, t
1500 Change allpass width_type.
1501 Syntax for the command is : "@var{width_type}"
1502
1503 @item width, w
1504 Change allpass width.
1505 Syntax for the command is : "@var{width}"
1506 @end table
1507
1508 @section aloop
1509
1510 Loop audio samples.
1511
1512 The filter accepts the following options:
1513
1514 @table @option
1515 @item loop
1516 Set the number of loops. Setting this value to -1 will result in infinite loops.
1517 Default is 0.
1518
1519 @item size
1520 Set maximal number of samples. Default is 0.
1521
1522 @item start
1523 Set first sample of loop. Default is 0.
1524 @end table
1525
1526 @anchor{amerge}
1527 @section amerge
1528
1529 Merge two or more audio streams into a single multi-channel stream.
1530
1531 The filter accepts the following options:
1532
1533 @table @option
1534
1535 @item inputs
1536 Set the number of inputs. Default is 2.
1537
1538 @end table
1539
1540 If the channel layouts of the inputs are disjoint, and therefore compatible,
1541 the channel layout of the output will be set accordingly and the channels
1542 will be reordered as necessary. If the channel layouts of the inputs are not
1543 disjoint, the output will have all the channels of the first input then all
1544 the channels of the second input, in that order, and the channel layout of
1545 the output will be the default value corresponding to the total number of
1546 channels.
1547
1548 For example, if the first input is in 2.1 (FL+FR+LF) and the second input
1549 is FC+BL+BR, then the output will be in 5.1, with the channels in the
1550 following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the
1551 first input, b1 is the first channel of the second input).
1552
1553 On the other hand, if both input are in stereo, the output channels will be
1554 in the default order: a1, a2, b1, b2, and the channel layout will be
1555 arbitrarily set to 4.0, which may or may not be the expected value.
1556
1557 All inputs must have the same sample rate, and format.
1558
1559 If inputs do not have the same duration, the output will stop with the
1560 shortest.
1561
1562 @subsection Examples
1563
1564 @itemize
1565 @item
1566 Merge two mono files into a stereo stream:
1567 @example
1568 amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge
1569 @end example
1570
1571 @item
1572 Multiple merges assuming 1 video stream and 6 audio streams in @file{input.mkv}:
1573 @example
1574 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
1575 @end example
1576 @end itemize
1577
1578 @section amix
1579
1580 Mixes multiple audio inputs into a single output.
1581
1582 Note that this filter only supports float samples (the @var{amerge}
1583 and @var{pan} audio filters support many formats). If the @var{amix}
1584 input has integer samples then @ref{aresample} will be automatically
1585 inserted to perform the conversion to float samples.
1586
1587 For example
1588 @example
1589 ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT
1590 @end example
1591 will mix 3 input audio streams to a single output with the same duration as the
1592 first input and a dropout transition time of 3 seconds.
1593
1594 It accepts the following parameters:
1595 @table @option
1596
1597 @item inputs
1598 The number of inputs. If unspecified, it defaults to 2.
1599
1600 @item duration
1601 How to determine the end-of-stream.
1602 @table @option
1603
1604 @item longest
1605 The duration of the longest input. (default)
1606
1607 @item shortest
1608 The duration of the shortest input.
1609
1610 @item first
1611 The duration of the first input.
1612
1613 @end table
1614
1615 @item dropout_transition
1616 The transition time, in seconds, for volume renormalization when an input
1617 stream ends. The default value is 2 seconds.
1618
1619 @item weights
1620 Specify weight of each input audio stream as sequence.
1621 Each weight is separated by space. By default all inputs have same weight.
1622 @end table
1623
1624 @section amultiply
1625
1626 Multiply first audio stream with second audio stream and store result
1627 in output audio stream. Multiplication is done by multiplying each
1628 sample from first stream with sample at same position from second stream.
1629
1630 With this element-wise multiplication one can create amplitude fades and
1631 amplitude modulations.
1632
1633 @section anequalizer
1634
1635 High-order parametric multiband equalizer for each channel.
1636
1637 It accepts the following parameters:
1638 @table @option
1639 @item params
1640
1641 This option string is in format:
1642 "c@var{chn} f=@var{cf} w=@var{w} g=@var{g} t=@var{f} | ..."
1643 Each equalizer band is separated by '|'.
1644
1645 @table @option
1646 @item chn
1647 Set channel number to which equalization will be applied.
1648 If input doesn't have that channel the entry is ignored.
1649
1650 @item f
1651 Set central frequency for band.
1652 If input doesn't have that frequency the entry is ignored.
1653
1654 @item w
1655 Set band width in hertz.
1656
1657 @item g
1658 Set band gain in dB.
1659
1660 @item t
1661 Set filter type for band, optional, can be:
1662
1663 @table @samp
1664 @item 0
1665 Butterworth, this is default.
1666
1667 @item 1
1668 Chebyshev type 1.
1669
1670 @item 2
1671 Chebyshev type 2.
1672 @end table
1673 @end table
1674
1675 @item curves
1676 With this option activated frequency response of anequalizer is displayed
1677 in video stream.
1678
1679 @item size
1680 Set video stream size. Only useful if curves option is activated.
1681
1682 @item mgain
1683 Set max gain that will be displayed. Only useful if curves option is activated.
1684 Setting this to a reasonable value makes it possible to display gain which is derived from
1685 neighbour bands which are too close to each other and thus produce higher gain
1686 when both are activated.
1687
1688 @item fscale
1689 Set frequency scale used to draw frequency response in video output.
1690 Can be linear or logarithmic. Default is logarithmic.
1691
1692 @item colors
1693 Set color for each channel curve which is going to be displayed in video stream.
1694 This is list of color names separated by space or by '|'.
1695 Unrecognised or missing colors will be replaced by white color.
1696 @end table
1697
1698 @subsection Examples
1699
1700 @itemize
1701 @item
1702 Lower gain by 10 of central frequency 200Hz and width 100 Hz
1703 for first 2 channels using Chebyshev type 1 filter:
1704 @example
1705 anequalizer=c0 f=200 w=100 g=-10 t=1|c1 f=200 w=100 g=-10 t=1
1706 @end example
1707 @end itemize
1708
1709 @subsection Commands
1710
1711 This filter supports the following commands:
1712 @table @option
1713 @item change
1714 Alter existing filter parameters.
1715 Syntax for the commands is : "@var{fN}|f=@var{freq}|w=@var{width}|g=@var{gain}"
1716
1717 @var{fN} is existing filter number, starting from 0, if no such filter is available
1718 error is returned.
1719 @var{freq} set new frequency parameter.
1720 @var{width} set new width parameter in herz.
1721 @var{gain} set new gain parameter in dB.
1722
1723 Full filter invocation with asendcmd may look like this:
1724 asendcmd=c='4.0 anequalizer change 0|f=200|w=50|g=1',anequalizer=...
1725 @end table
1726
1727 @section anull
1728
1729 Pass the audio source unchanged to the output.
1730
1731 @section apad
1732
1733 Pad the end of an audio stream with silence.
1734
1735 This can be used together with @command{ffmpeg} @option{-shortest} to
1736 extend audio streams to the same length as the video stream.
1737
1738 A description of the accepted options follows.
1739
1740 @table @option
1741 @item packet_size
1742 Set silence packet size. Default value is 4096.
1743
1744 @item pad_len
1745 Set the number of samples of silence to add to the end. After the
1746 value is reached, the stream is terminated. This option is mutually
1747 exclusive with @option{whole_len}.
1748
1749 @item whole_len
1750 Set the minimum total number of samples in the output audio stream. If
1751 the value is longer than the input audio length, silence is added to
1752 the end, until the value is reached. This option is mutually exclusive
1753 with @option{pad_len}.
1754 @end table
1755
1756 If neither the @option{pad_len} nor the @option{whole_len} option is
1757 set, the filter will add silence to the end of the input stream
1758 indefinitely.
1759
1760 @subsection Examples
1761
1762 @itemize
1763 @item
1764 Add 1024 samples of silence to the end of the input:
1765 @example
1766 apad=pad_len=1024
1767 @end example
1768
1769 @item
1770 Make sure the audio output will contain at least 10000 samples, pad
1771 the input with silence if required:
1772 @example
1773 apad=whole_len=10000
1774 @end example
1775
1776 @item
1777 Use @command{ffmpeg} to pad the audio input with silence, so that the
1778 video stream will always result the shortest and will be converted
1779 until the end in the output file when using the @option{shortest}
1780 option:
1781 @example
1782 ffmpeg -i VIDEO -i AUDIO -filter_complex "[1:0]apad" -shortest OUTPUT
1783 @end example
1784 @end itemize
1785
1786 @section aphaser
1787 Add a phasing effect to the input audio.
1788
1789 A phaser filter creates series of peaks and troughs in the frequency spectrum.
1790 The position of the peaks and troughs are modulated so that they vary over time, creating a sweeping effect.
1791
1792 A description of the accepted parameters follows.
1793
1794 @table @option
1795 @item in_gain
1796 Set input gain. Default is 0.4.
1797
1798 @item out_gain
1799 Set output gain. Default is 0.74
1800
1801 @item delay
1802 Set delay in milliseconds. Default is 3.0.
1803
1804 @item decay
1805 Set decay. Default is 0.4.
1806
1807 @item speed
1808 Set modulation speed in Hz. Default is 0.5.
1809
1810 @item type
1811 Set modulation type. Default is triangular.
1812
1813 It accepts the following values:
1814 @table @samp
1815 @item triangular, t
1816 @item sinusoidal, s
1817 @end table
1818 @end table
1819
1820 @section apulsator
1821
1822 Audio pulsator is something between an autopanner and a tremolo.
1823 But it can produce funny stereo effects as well. Pulsator changes the volume
1824 of the left and right channel based on a LFO (low frequency oscillator) with
1825 different waveforms and shifted phases.
1826 This filter have the ability to define an offset between left and right
1827 channel. An offset of 0 means that both LFO shapes match each other.
1828 The left and right channel are altered equally - a conventional tremolo.
1829 An offset of 50% means that the shape of the right channel is exactly shifted
1830 in phase (or moved backwards about half of the frequency) - pulsator acts as
1831 an autopanner. At 1 both curves match again. Every setting in between moves the
1832 phase shift gapless between all stages and produces some "bypassing" sounds with
1833 sine and triangle waveforms. The more you set the offset near 1 (starting from
1834 the 0.5) the faster the signal passes from the left to the right speaker.
1835
1836 The filter accepts the following options:
1837
1838 @table @option
1839 @item level_in
1840 Set input gain. By default it is 1. Range is [0.015625 - 64].
1841
1842 @item level_out
1843 Set output gain. By default it is 1. Range is [0.015625 - 64].
1844
1845 @item mode
1846 Set waveform shape the LFO will use. Can be one of: sine, triangle, square,
1847 sawup or sawdown. Default is sine.
1848
1849 @item amount
1850 Set modulation. Define how much of original signal is affected by the LFO.
1851
1852 @item offset_l
1853 Set left channel offset. Default is 0. Allowed range is [0 - 1].
1854
1855 @item offset_r
1856 Set right channel offset. Default is 0.5. Allowed range is [0 - 1].
1857
1858 @item width
1859 Set pulse width. Default is 1. Allowed range is [0 - 2].
1860
1861 @item timing
1862 Set possible timing mode. Can be one of: bpm, ms or hz. Default is hz.
1863
1864 @item bpm
1865 Set bpm. Default is 120. Allowed range is [30 - 300]. Only used if timing
1866 is set to bpm.
1867
1868 @item ms
1869 Set ms. Default is 500. Allowed range is [10 - 2000]. Only used if timing
1870 is set to ms.
1871
1872 @item hz
1873 Set frequency in Hz. Default is 2. Allowed range is [0.01 - 100]. Only used
1874 if timing is set to hz.
1875 @end table
1876
1877 @anchor{aresample}
1878 @section aresample
1879
1880 Resample the input audio to the specified parameters, using the
1881 libswresample library. If none are specified then the filter will
1882 automatically convert between its input and output.
1883
1884 This filter is also able to stretch/squeeze the audio data to make it match
1885 the timestamps or to inject silence / cut out audio to make it match the
1886 timestamps, do a combination of both or do neither.
1887
1888 The filter accepts the syntax
1889 [@var{sample_rate}:]@var{resampler_options}, where @var{sample_rate}
1890 expresses a sample rate and @var{resampler_options} is a list of
1891 @var{key}=@var{value} pairs, separated by ":". See the
1892 @ref{Resampler Options,,"Resampler Options" section in the
1893 ffmpeg-resampler(1) manual,ffmpeg-resampler}
1894 for the complete list of supported options.
1895
1896 @subsection Examples
1897
1898 @itemize
1899 @item
1900 Resample the input audio to 44100Hz:
1901 @example
1902 aresample=44100
1903 @end example
1904
1905 @item
1906 Stretch/squeeze samples to the given timestamps, with a maximum of 1000
1907 samples per second compensation:
1908 @example
1909 aresample=async=1000
1910 @end example
1911 @end itemize
1912
1913 @section areverse
1914
1915 Reverse an audio clip.
1916
1917 Warning: This filter requires memory to buffer the entire clip, so trimming
1918 is suggested.
1919
1920 @subsection Examples
1921
1922 @itemize
1923 @item
1924 Take the first 5 seconds of a clip, and reverse it.
1925 @example
1926 atrim=end=5,areverse
1927 @end example
1928 @end itemize
1929
1930 @section asetnsamples
1931
1932 Set the number of samples per each output audio frame.
1933
1934 The last output packet may contain a different number of samples, as
1935 the filter will flush all the remaining samples when the input audio
1936 signals its end.
1937
1938 The filter accepts the following options:
1939
1940 @table @option
1941
1942 @item nb_out_samples, n
1943 Set the number of frames per each output audio frame. The number is
1944 intended as the number of samples @emph{per each channel}.
1945 Default value is 1024.
1946
1947 @item pad, p
1948 If set to 1, the filter will pad the last audio frame with zeroes, so
1949 that the last frame will contain the same number of samples as the
1950 previous ones. Default value is 1.
1951 @end table
1952
1953 For example, to set the number of per-frame samples to 1234 and
1954 disable padding for the last frame, use:
1955 @example
1956 asetnsamples=n=1234:p=0
1957 @end example
1958
1959 @section asetrate
1960
1961 Set the sample rate without altering the PCM data.
1962 This will result in a change of speed and pitch.
1963
1964 The filter accepts the following options:
1965
1966 @table @option
1967 @item sample_rate, r
1968 Set the output sample rate. Default is 44100 Hz.
1969 @end table
1970
1971 @section ashowinfo
1972
1973 Show a line containing various information for each input audio frame.
1974 The input audio is not modified.
1975
1976 The shown line contains a sequence of key/value pairs of the form
1977 @var{key}:@var{value}.
1978
1979 The following values are shown in the output:
1980
1981 @table @option
1982 @item n
1983 The (sequential) number of the input frame, starting from 0.
1984
1985 @item pts
1986 The presentation timestamp of the input frame, in time base units; the time base
1987 depends on the filter input pad, and is usually 1/@var{sample_rate}.
1988
1989 @item pts_time
1990 The presentation timestamp of the input frame in seconds.
1991
1992 @item pos
1993 position of the frame in the input stream, -1 if this information in
1994 unavailable and/or meaningless (for example in case of synthetic audio)
1995
1996 @item fmt
1997 The sample format.
1998
1999 @item chlayout
2000 The channel layout.
2001
2002 @item rate
2003 The sample rate for the audio frame.
2004
2005 @item nb_samples
2006 The number of samples (per channel) in the frame.
2007
2008 @item checksum
2009 The Adler-32 checksum (printed in hexadecimal) of the audio data. For planar
2010 audio, the data is treated as if all the planes were concatenated.
2011
2012 @item plane_checksums
2013 A list of Adler-32 checksums for each data plane.
2014 @end table
2015
2016 @anchor{astats}
2017 @section astats
2018
2019 Display time domain statistical information about the audio channels.
2020 Statistics are calculated and displayed for each audio channel and,
2021 where applicable, an overall figure is also given.
2022
2023 It accepts the following option:
2024 @table @option
2025 @item length
2026 Short window length in seconds, used for peak and trough RMS measurement.
2027 Default is @code{0.05} (50 milliseconds). Allowed range is @code{[0.01 - 10]}.
2028
2029 @item metadata
2030
2031 Set metadata injection. All the metadata keys are prefixed with @code{lavfi.astats.X},
2032 where @code{X} is channel number starting from 1 or string @code{Overall}. Default is
2033 disabled.
2034
2035 Available keys for each channel are:
2036 DC_offset
2037 Min_level
2038 Max_level
2039 Min_difference
2040 Max_difference
2041 Mean_difference
2042 RMS_difference
2043 Peak_level
2044 RMS_peak
2045 RMS_trough
2046 Crest_factor
2047 Flat_factor
2048 Peak_count
2049 Bit_depth
2050 Dynamic_range
2051 Zero_crossings
2052 Zero_crossings_rate
2053
2054 and for Overall:
2055 DC_offset
2056 Min_level
2057 Max_level
2058 Min_difference
2059 Max_difference
2060 Mean_difference
2061 RMS_difference
2062 Peak_level
2063 RMS_level
2064 RMS_peak
2065 RMS_trough
2066 Flat_factor
2067 Peak_count
2068 Bit_depth
2069 Number_of_samples
2070
2071 For example full key look like this @code{lavfi.astats.1.DC_offset} or
2072 this @code{lavfi.astats.Overall.Peak_count}.
2073
2074 For description what each key means read below.
2075
2076 @item reset
2077 Set number of frame after which stats are going to be recalculated.
2078 Default is disabled.
2079 @end table
2080
2081 A description of each shown parameter follows:
2082
2083 @table @option
2084 @item DC offset
2085 Mean amplitude displacement from zero.
2086
2087 @item Min level
2088 Minimal sample level.
2089
2090 @item Max level
2091 Maximal sample level.
2092
2093 @item Min difference
2094 Minimal difference between two consecutive samples.
2095
2096 @item Max difference
2097 Maximal difference between two consecutive samples.
2098
2099 @item Mean difference
2100 Mean difference between two consecutive samples.
2101 The average of each difference between two consecutive samples.
2102
2103 @item RMS difference
2104 Root Mean Square difference between two consecutive samples.
2105
2106 @item Peak level dB
2107 @item RMS level dB
2108 Standard peak and RMS level measured in dBFS.
2109
2110 @item RMS peak dB
2111 @item RMS trough dB
2112 Peak and trough values for RMS level measured over a short window.
2113
2114 @item Crest factor
2115 Standard ratio of peak to RMS level (note: not in dB).
2116
2117 @item Flat factor
2118 Flatness (i.e. consecutive samples with the same value) of the signal at its peak levels
2119 (i.e. either @var{Min level} or @var{Max level}).
2120
2121 @item Peak count
2122 Number of occasions (not the number of samples) that the signal attained either
2123 @var{Min level} or @var{Max level}.
2124
2125 @item Bit depth
2126 Overall bit depth of audio. Number of bits used for each sample.
2127
2128 @item Dynamic range
2129 Measured dynamic range of audio in dB.
2130
2131 @item Zero crossings
2132 Number of points where the waveform crosses the zero level axis.
2133
2134 @item Zero crossings rate
2135 Rate of Zero crossings and number of audio samples.
2136 @end table
2137
2138 @section atempo
2139
2140 Adjust audio tempo.
2141
2142 The filter accepts exactly one parameter, the audio tempo. If not
2143 specified then the filter will assume nominal 1.0 tempo. Tempo must
2144 be in the [0.5, 100.0] range.
2145
2146 Note that tempo greater than 2 will skip some samples rather than
2147 blend them in.  If for any reason this is a concern it is always
2148 possible to daisy-chain several instances of atempo to achieve the
2149 desired product tempo.
2150
2151 @subsection Examples
2152
2153 @itemize
2154 @item
2155 Slow down audio to 80% tempo:
2156 @example
2157 atempo=0.8
2158 @end example
2159
2160 @item
2161 To speed up audio to 300% tempo:
2162 @example
2163 atempo=3
2164 @end example
2165
2166 @item
2167 To speed up audio to 300% tempo by daisy-chaining two atempo instances:
2168 @example
2169 atempo=sqrt(3),atempo=sqrt(3)
2170 @end example
2171 @end itemize
2172
2173 @section atrim
2174
2175 Trim the input so that the output contains one continuous subpart of the input.
2176
2177 It accepts the following parameters:
2178 @table @option
2179 @item start
2180 Timestamp (in seconds) of the start of the section to keep. I.e. the audio
2181 sample with the timestamp @var{start} will be the first sample in the output.
2182
2183 @item end
2184 Specify time of the first audio sample that will be dropped, i.e. the
2185 audio sample immediately preceding the one with the timestamp @var{end} will be
2186 the last sample in the output.
2187
2188 @item start_pts
2189 Same as @var{start}, except this option sets the start timestamp in samples
2190 instead of seconds.
2191
2192 @item end_pts
2193 Same as @var{end}, except this option sets the end timestamp in samples instead
2194 of seconds.
2195
2196 @item duration
2197 The maximum duration of the output in seconds.
2198
2199 @item start_sample
2200 The number of the first sample that should be output.
2201
2202 @item end_sample
2203 The number of the first sample that should be dropped.
2204 @end table
2205
2206 @option{start}, @option{end}, and @option{duration} are expressed as time
2207 duration specifications; see
2208 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}.
2209
2210 Note that the first two sets of the start/end options and the @option{duration}
2211 option look at the frame timestamp, while the _sample options simply count the
2212 samples that pass through the filter. So start/end_pts and start/end_sample will
2213 give different results when the timestamps are wrong, inexact or do not start at
2214 zero. Also note that this filter does not modify the timestamps. If you wish
2215 to have the output timestamps start at zero, insert the asetpts filter after the
2216 atrim filter.
2217
2218 If multiple start or end options are set, this filter tries to be greedy and
2219 keep all samples that match at least one of the specified constraints. To keep
2220 only the part that matches all the constraints at once, chain multiple atrim
2221 filters.
2222
2223 The defaults are such that all the input is kept. So it is possible to set e.g.
2224 just the end values to keep everything before the specified time.
2225
2226 Examples:
2227 @itemize
2228 @item
2229 Drop everything except the second minute of input:
2230 @example
2231 ffmpeg -i INPUT -af atrim=60:120
2232 @end example
2233
2234 @item
2235 Keep only the first 1000 samples:
2236 @example
2237 ffmpeg -i INPUT -af atrim=end_sample=1000
2238 @end example
2239
2240 @end itemize
2241
2242 @section bandpass
2243
2244 Apply a two-pole Butterworth band-pass filter with central
2245 frequency @var{frequency}, and (3dB-point) band-width width.
2246 The @var{csg} option selects a constant skirt gain (peak gain = Q)
2247 instead of the default: constant 0dB peak gain.
2248 The filter roll off at 6dB per octave (20dB per decade).
2249
2250 The filter accepts the following options:
2251
2252 @table @option
2253 @item frequency, f
2254 Set the filter's central frequency. Default is @code{3000}.
2255
2256 @item csg
2257 Constant skirt gain if set to 1. Defaults to 0.
2258
2259 @item width_type, t
2260 Set method to specify band-width of filter.
2261 @table @option
2262 @item h
2263 Hz
2264 @item q
2265 Q-Factor
2266 @item o
2267 octave
2268 @item s
2269 slope
2270 @item k
2271 kHz
2272 @end table
2273
2274 @item width, w
2275 Specify the band-width of a filter in width_type units.
2276
2277 @item channels, c
2278 Specify which channels to filter, by default all available are filtered.
2279 @end table
2280
2281 @subsection Commands
2282
2283 This filter supports the following commands:
2284 @table @option
2285 @item frequency, f
2286 Change bandpass frequency.
2287 Syntax for the command is : "@var{frequency}"
2288
2289 @item width_type, t
2290 Change bandpass width_type.
2291 Syntax for the command is : "@var{width_type}"
2292
2293 @item width, w
2294 Change bandpass width.
2295 Syntax for the command is : "@var{width}"
2296 @end table
2297
2298 @section bandreject
2299
2300 Apply a two-pole Butterworth band-reject filter with central
2301 frequency @var{frequency}, and (3dB-point) band-width @var{width}.
2302 The filter roll off at 6dB per octave (20dB per decade).
2303
2304 The filter accepts the following options:
2305
2306 @table @option
2307 @item frequency, f
2308 Set the filter's central frequency. Default is @code{3000}.
2309
2310 @item width_type, t
2311 Set method to specify band-width of filter.
2312 @table @option
2313 @item h
2314 Hz
2315 @item q
2316 Q-Factor
2317 @item o
2318 octave
2319 @item s
2320 slope
2321 @item k
2322 kHz
2323 @end table
2324
2325 @item width, w
2326 Specify the band-width of a filter in width_type units.
2327
2328 @item channels, c
2329 Specify which channels to filter, by default all available are filtered.
2330 @end table
2331
2332 @subsection Commands
2333
2334 This filter supports the following commands:
2335 @table @option
2336 @item frequency, f
2337 Change bandreject frequency.
2338 Syntax for the command is : "@var{frequency}"
2339
2340 @item width_type, t
2341 Change bandreject width_type.
2342 Syntax for the command is : "@var{width_type}"
2343
2344 @item width, w
2345 Change bandreject width.
2346 Syntax for the command is : "@var{width}"
2347 @end table
2348
2349 @section bass, lowshelf
2350
2351 Boost or cut the bass (lower) frequencies of the audio using a two-pole
2352 shelving filter with a response similar to that of a standard
2353 hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
2354
2355 The filter accepts the following options:
2356
2357 @table @option
2358 @item gain, g
2359 Give the gain at 0 Hz. Its useful range is about -20
2360 (for a large cut) to +20 (for a large boost).
2361 Beware of clipping when using a positive gain.
2362
2363 @item frequency, f
2364 Set the filter's central frequency and so can be used
2365 to extend or reduce the frequency range to be boosted or cut.
2366 The default value is @code{100} Hz.
2367
2368 @item width_type, t
2369 Set method to specify band-width of filter.
2370 @table @option
2371 @item h
2372 Hz
2373 @item q
2374 Q-Factor
2375 @item o
2376 octave
2377 @item s
2378 slope
2379 @item k
2380 kHz
2381 @end table
2382
2383 @item width, w
2384 Determine how steep is the filter's shelf transition.
2385
2386 @item channels, c
2387 Specify which channels to filter, by default all available are filtered.
2388 @end table
2389
2390 @subsection Commands
2391
2392 This filter supports the following commands:
2393 @table @option
2394 @item frequency, f
2395 Change bass frequency.
2396 Syntax for the command is : "@var{frequency}"
2397
2398 @item width_type, t
2399 Change bass width_type.
2400 Syntax for the command is : "@var{width_type}"
2401
2402 @item width, w
2403 Change bass width.
2404 Syntax for the command is : "@var{width}"
2405
2406 @item gain, g
2407 Change bass gain.
2408 Syntax for the command is : "@var{gain}"
2409 @end table
2410
2411 @section biquad
2412
2413 Apply a biquad IIR filter with the given coefficients.
2414 Where @var{b0}, @var{b1}, @var{b2} and @var{a0}, @var{a1}, @var{a2}
2415 are the numerator and denominator coefficients respectively.
2416 and @var{channels}, @var{c} specify which channels to filter, by default all
2417 available are filtered.
2418
2419 @subsection Commands
2420
2421 This filter supports the following commands:
2422 @table @option
2423 @item a0
2424 @item a1
2425 @item a2
2426 @item b0
2427 @item b1
2428 @item b2
2429 Change biquad parameter.
2430 Syntax for the command is : "@var{value}"
2431 @end table
2432
2433 @section bs2b
2434 Bauer stereo to binaural transformation, which improves headphone listening of
2435 stereo audio records.
2436
2437 To enable compilation of this filter you need to configure FFmpeg with
2438 @code{--enable-libbs2b}.
2439
2440 It accepts the following parameters:
2441 @table @option
2442
2443 @item profile
2444 Pre-defined crossfeed level.
2445 @table @option
2446
2447 @item default
2448 Default level (fcut=700, feed=50).
2449
2450 @item cmoy
2451 Chu Moy circuit (fcut=700, feed=60).
2452
2453 @item jmeier
2454 Jan Meier circuit (fcut=650, feed=95).
2455
2456 @end table
2457
2458 @item fcut
2459 Cut frequency (in Hz).
2460
2461 @item feed
2462 Feed level (in Hz).
2463
2464 @end table
2465
2466 @section channelmap
2467
2468 Remap input channels to new locations.
2469
2470 It accepts the following parameters:
2471 @table @option
2472 @item map
2473 Map channels from input to output. The argument is a '|'-separated list of
2474 mappings, each in the @code{@var{in_channel}-@var{out_channel}} or
2475 @var{in_channel} form. @var{in_channel} can be either the name of the input
2476 channel (e.g. FL for front left) or its index in the input channel layout.
2477 @var{out_channel} is the name of the output channel or its index in the output
2478 channel layout. If @var{out_channel} is not given then it is implicitly an
2479 index, starting with zero and increasing by one for each mapping.
2480
2481 @item channel_layout
2482 The channel layout of the output stream.
2483 @end table
2484
2485 If no mapping is present, the filter will implicitly map input channels to
2486 output channels, preserving indices.
2487
2488 @subsection Examples
2489
2490 @itemize
2491 @item
2492 For example, assuming a 5.1+downmix input MOV file,
2493 @example
2494 ffmpeg -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav
2495 @end example
2496 will create an output WAV file tagged as stereo from the downmix channels of
2497 the input.
2498
2499 @item
2500 To fix a 5.1 WAV improperly encoded in AAC's native channel order
2501 @example
2502 ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:5.1' out.wav
2503 @end example
2504 @end itemize
2505
2506 @section channelsplit
2507
2508 Split each channel from an input audio stream into a separate output stream.
2509
2510 It accepts the following parameters:
2511 @table @option
2512 @item channel_layout
2513 The channel layout of the input stream. The default is "stereo".
2514 @item channels
2515 A channel layout describing the channels to be extracted as separate output streams
2516 or "all" to extract each input channel as a separate stream. The default is "all".
2517
2518 Choosing channels not present in channel layout in the input will result in an error.
2519 @end table
2520
2521 @subsection Examples
2522
2523 @itemize
2524 @item
2525 For example, assuming a stereo input MP3 file,
2526 @example
2527 ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv
2528 @end example
2529 will create an output Matroska file with two audio streams, one containing only
2530 the left channel and the other the right channel.
2531
2532 @item
2533 Split a 5.1 WAV file into per-channel files:
2534 @example
2535 ffmpeg -i in.wav -filter_complex
2536 'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]'
2537 -map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]'
2538 front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]'
2539 side_right.wav
2540 @end example
2541
2542 @item
2543 Extract only LFE from a 5.1 WAV file:
2544 @example
2545 ffmpeg -i in.wav -filter_complex 'channelsplit=channel_layout=5.1:channels=LFE[LFE]'
2546 -map '[LFE]' lfe.wav
2547 @end example
2548 @end itemize
2549
2550 @section chorus
2551 Add a chorus effect to the audio.
2552
2553 Can make a single vocal sound like a chorus, but can also be applied to instrumentation.
2554
2555 Chorus resembles an echo effect with a short delay, but whereas with echo the delay is
2556 constant, with chorus, it is varied using using sinusoidal or triangular modulation.
2557 The modulation depth defines the range the modulated delay is played before or after
2558 the delay. Hence the delayed sound will sound slower or faster, that is the delayed
2559 sound tuned around the original one, like in a chorus where some vocals are slightly
2560 off key.
2561
2562 It accepts the following parameters:
2563 @table @option
2564 @item in_gain
2565 Set input gain. Default is 0.4.
2566
2567 @item out_gain
2568 Set output gain. Default is 0.4.
2569
2570 @item delays
2571 Set delays. A typical delay is around 40ms to 60ms.
2572
2573 @item decays
2574 Set decays.
2575
2576 @item speeds
2577 Set speeds.
2578
2579 @item depths
2580 Set depths.
2581 @end table
2582
2583 @subsection Examples
2584
2585 @itemize
2586 @item
2587 A single delay:
2588 @example
2589 chorus=0.7:0.9:55:0.4:0.25:2
2590 @end example
2591
2592 @item
2593 Two delays:
2594 @example
2595 chorus=0.6:0.9:50|60:0.4|0.32:0.25|0.4:2|1.3
2596 @end example
2597
2598 @item
2599 Fuller sounding chorus with three delays:
2600 @example
2601 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
2602 @end example
2603 @end itemize
2604
2605 @section compand
2606 Compress or expand the audio's dynamic range.
2607
2608 It accepts the following parameters:
2609
2610 @table @option
2611
2612 @item attacks
2613 @item decays
2614 A list of times in seconds for each channel over which the instantaneous level
2615 of the input signal is averaged to determine its volume. @var{attacks} refers to
2616 increase of volume and @var{decays} refers to decrease of volume. For most
2617 situations, the attack time (response to the audio getting louder) should be
2618 shorter than the decay time, because the human ear is more sensitive to sudden
2619 loud audio than sudden soft audio. A typical value for attack is 0.3 seconds and
2620 a typical value for decay is 0.8 seconds.
2621 If specified number of attacks & decays is lower than number of channels, the last
2622 set attack/decay will be used for all remaining channels.
2623
2624 @item points
2625 A list of points for the transfer function, specified in dB relative to the
2626 maximum possible signal amplitude. Each key points list must be defined using
2627 the following syntax: @code{x0/y0|x1/y1|x2/y2|....} or
2628 @code{x0/y0 x1/y1 x2/y2 ....}
2629
2630 The input values must be in strictly increasing order but the transfer function
2631 does not have to be monotonically rising. The point @code{0/0} is assumed but
2632 may be overridden (by @code{0/out-dBn}). Typical values for the transfer
2633 function are @code{-70/-70|-60/-20|1/0}.
2634
2635 @item soft-knee
2636 Set the curve radius in dB for all joints. It defaults to 0.01.
2637
2638 @item gain
2639 Set the additional gain in dB to be applied at all points on the transfer
2640 function. This allows for easy adjustment of the overall gain.
2641 It defaults to 0.
2642
2643 @item volume
2644 Set an initial volume, in dB, to be assumed for each channel when filtering
2645 starts. This permits the user to supply a nominal level initially, so that, for
2646 example, a very large gain is not applied to initial signal levels before the
2647 companding has begun to operate. A typical value for audio which is initially
2648 quiet is -90 dB. It defaults to 0.
2649
2650 @item delay
2651 Set a delay, in seconds. The input audio is analyzed immediately, but audio is
2652 delayed before being fed to the volume adjuster. Specifying a delay
2653 approximately equal to the attack/decay times allows the filter to effectively
2654 operate in predictive rather than reactive mode. It defaults to 0.
2655
2656 @end table
2657
2658 @subsection Examples
2659
2660 @itemize
2661 @item
2662 Make music with both quiet and loud passages suitable for listening to in a
2663 noisy environment:
2664 @example
2665 compand=.3|.3:1|1:-90/-60|-60/-40|-40/-30|-20/-20:6:0:-90:0.2
2666 @end example
2667
2668 Another example for audio with whisper and explosion parts:
2669 @example
2670 compand=0|0:1|1:-90/-900|-70/-70|-30/-9|0/-3:6:0:0:0
2671 @end example
2672
2673 @item
2674 A noise gate for when the noise is at a lower level than the signal:
2675 @example
2676 compand=.1|.1:.2|.2:-900/-900|-50.1/-900|-50/-50:.01:0:-90:.1
2677 @end example
2678
2679 @item
2680 Here is another noise gate, this time for when the noise is at a higher level
2681 than the signal (making it, in some ways, similar to squelch):
2682 @example
2683 compand=.1|.1:.1|.1:-45.1/-45.1|-45/-900|0/-900:.01:45:-90:.1
2684 @end example
2685
2686 @item
2687 2:1 compression starting at -6dB:
2688 @example
2689 compand=points=-80/-80|-6/-6|0/-3.8|20/3.5
2690 @end example
2691
2692 @item
2693 2:1 compression starting at -9dB:
2694 @example
2695 compand=points=-80/-80|-9/-9|0/-5.3|20/2.9
2696 @end example
2697
2698 @item
2699 2:1 compression starting at -12dB:
2700 @example
2701 compand=points=-80/-80|-12/-12|0/-6.8|20/1.9
2702 @end example
2703
2704 @item
2705 2:1 compression starting at -18dB:
2706 @example
2707 compand=points=-80/-80|-18/-18|0/-9.8|20/0.7
2708 @end example
2709
2710 @item
2711 3:1 compression starting at -15dB:
2712 @example
2713 compand=points=-80/-80|-15/-15|0/-10.8|20/-5.2
2714 @end example
2715
2716 @item
2717 Compressor/Gate:
2718 @example
2719 compand=points=-80/-105|-62/-80|-15.4/-15.4|0/-12|20/-7.6
2720 @end example
2721
2722 @item
2723 Expander:
2724 @example
2725 compand=attacks=0:points=-80/-169|-54/-80|-49.5/-64.6|-41.1/-41.1|-25.8/-15|-10.8/-4.5|0/0|20/8.3
2726 @end example
2727
2728 @item
2729 Hard limiter at -6dB:
2730 @example
2731 compand=attacks=0:points=-80/-80|-6/-6|20/-6
2732 @end example
2733
2734 @item
2735 Hard limiter at -12dB:
2736 @example
2737 compand=attacks=0:points=-80/-80|-12/-12|20/-12
2738 @end example
2739
2740 @item
2741 Hard noise gate at -35 dB:
2742 @example
2743 compand=attacks=0:points=-80/-115|-35.1/-80|-35/-35|20/20
2744 @end example
2745
2746 @item
2747 Soft limiter:
2748 @example
2749 compand=attacks=0:points=-80/-80|-12.4/-12.4|-6/-8|0/-6.8|20/-2.8
2750 @end example
2751 @end itemize
2752
2753 @section compensationdelay
2754
2755 Compensation Delay Line is a metric based delay to compensate differing
2756 positions of microphones or speakers.
2757
2758 For example, you have recorded guitar with two microphones placed in
2759 different location. Because the front of sound wave has fixed speed in
2760 normal conditions, the phasing of microphones can vary and depends on
2761 their location and interposition. The best sound mix can be achieved when
2762 these microphones are in phase (synchronized). Note that distance of
2763 ~30 cm between microphones makes one microphone to capture signal in
2764 antiphase to another microphone. That makes the final mix sounding moody.
2765 This filter helps to solve phasing problems by adding different delays
2766 to each microphone track and make them synchronized.
2767
2768 The best result can be reached when you take one track as base and
2769 synchronize other tracks one by one with it.
2770 Remember that synchronization/delay tolerance depends on sample rate, too.
2771 Higher sample rates will give more tolerance.
2772
2773 It accepts the following parameters:
2774
2775 @table @option
2776 @item mm
2777 Set millimeters distance. This is compensation distance for fine tuning.
2778 Default is 0.
2779
2780 @item cm
2781 Set cm distance. This is compensation distance for tightening distance setup.
2782 Default is 0.
2783
2784 @item m
2785 Set meters distance. This is compensation distance for hard distance setup.
2786 Default is 0.
2787
2788 @item dry
2789 Set dry amount. Amount of unprocessed (dry) signal.
2790 Default is 0.
2791
2792 @item wet
2793 Set wet amount. Amount of processed (wet) signal.
2794 Default is 1.
2795
2796 @item temp
2797 Set temperature degree in Celsius. This is the temperature of the environment.
2798 Default is 20.
2799 @end table
2800
2801 @section crossfeed
2802 Apply headphone crossfeed filter.
2803
2804 Crossfeed is the process of blending the left and right channels of stereo
2805 audio recording.
2806 It is mainly used to reduce extreme stereo separation of low frequencies.
2807
2808 The intent is to produce more speaker like sound to the listener.
2809
2810 The filter accepts the following options:
2811
2812 @table @option
2813 @item strength
2814 Set strength of crossfeed. Default is 0.2. Allowed range is from 0 to 1.
2815 This sets gain of low shelf filter for side part of stereo image.
2816 Default is -6dB. Max allowed is -30db when strength is set to 1.
2817
2818 @item range
2819 Set soundstage wideness. Default is 0.5. Allowed range is from 0 to 1.
2820 This sets cut off frequency of low shelf filter. Default is cut off near
2821 1550 Hz. With range set to 1 cut off frequency is set to 2100 Hz.
2822
2823 @item level_in
2824 Set input gain. Default is 0.9.
2825
2826 @item level_out
2827 Set output gain. Default is 1.
2828 @end table
2829
2830 @section crystalizer
2831 Simple algorithm to expand audio dynamic range.
2832
2833 The filter accepts the following options:
2834
2835 @table @option
2836 @item i
2837 Sets the intensity of effect (default: 2.0). Must be in range between 0.0
2838 (unchanged sound) to 10.0 (maximum effect).
2839
2840 @item c
2841 Enable clipping. By default is enabled.
2842 @end table
2843
2844 @section dcshift
2845 Apply a DC shift to the audio.
2846
2847 This can be useful to remove a DC offset (caused perhaps by a hardware problem
2848 in the recording chain) from the audio. The effect of a DC offset is reduced
2849 headroom and hence volume. The @ref{astats} filter can be used to determine if
2850 a signal has a DC offset.
2851
2852 @table @option
2853 @item shift
2854 Set the DC shift, allowed range is [-1, 1]. It indicates the amount to shift
2855 the audio.
2856
2857 @item limitergain
2858 Optional. It should have a value much less than 1 (e.g. 0.05 or 0.02) and is
2859 used to prevent clipping.
2860 @end table
2861
2862 @section drmeter
2863 Measure audio dynamic range.
2864
2865 DR values of 14 and higher is found in very dynamic material. DR of 8 to 13
2866 is found in transition material. And anything less that 8 have very poor dynamics
2867 and is very compressed.
2868
2869 The filter accepts the following options:
2870
2871 @table @option
2872 @item length
2873 Set window length in seconds used to split audio into segments of equal length.
2874 Default is 3 seconds.
2875 @end table
2876
2877 @section dynaudnorm
2878 Dynamic Audio Normalizer.
2879
2880 This filter applies a certain amount of gain to the input audio in order
2881 to bring its peak magnitude to a target level (e.g. 0 dBFS). However, in
2882 contrast to more "simple" normalization algorithms, the Dynamic Audio
2883 Normalizer *dynamically* re-adjusts the gain factor to the input audio.
2884 This allows for applying extra gain to the "quiet" sections of the audio
2885 while avoiding distortions or clipping the "loud" sections. In other words:
2886 The Dynamic Audio Normalizer will "even out" the volume of quiet and loud
2887 sections, in the sense that the volume of each section is brought to the
2888 same target level. Note, however, that the Dynamic Audio Normalizer achieves
2889 this goal *without* applying "dynamic range compressing". It will retain 100%
2890 of the dynamic range *within* each section of the audio file.
2891
2892 @table @option
2893 @item f
2894 Set the frame length in milliseconds. In range from 10 to 8000 milliseconds.
2895 Default is 500 milliseconds.
2896 The Dynamic Audio Normalizer processes the input audio in small chunks,
2897 referred to as frames. This is required, because a peak magnitude has no
2898 meaning for just a single sample value. Instead, we need to determine the
2899 peak magnitude for a contiguous sequence of sample values. While a "standard"
2900 normalizer would simply use the peak magnitude of the complete file, the
2901 Dynamic Audio Normalizer determines the peak magnitude individually for each
2902 frame. The length of a frame is specified in milliseconds. By default, the
2903 Dynamic Audio Normalizer uses a frame length of 500 milliseconds, which has
2904 been found to give good results with most files.
2905 Note that the exact frame length, in number of samples, will be determined
2906 automatically, based on the sampling rate of the individual input audio file.
2907
2908 @item g
2909 Set the Gaussian filter window size. In range from 3 to 301, must be odd
2910 number. Default is 31.
2911 Probably the most important parameter of the Dynamic Audio Normalizer is the
2912 @code{window size} of the Gaussian smoothing filter. The filter's window size
2913 is specified in frames, centered around the current frame. For the sake of
2914 simplicity, this must be an odd number. Consequently, the default value of 31
2915 takes into account the current frame, as well as the 15 preceding frames and
2916 the 15 subsequent frames. Using a larger window results in a stronger
2917 smoothing effect and thus in less gain variation, i.e. slower gain
2918 adaptation. Conversely, using a smaller window results in a weaker smoothing
2919 effect and thus in more gain variation, i.e. faster gain adaptation.
2920 In other words, the more you increase this value, the more the Dynamic Audio
2921 Normalizer will behave like a "traditional" normalization filter. On the
2922 contrary, the more you decrease this value, the more the Dynamic Audio
2923 Normalizer will behave like a dynamic range compressor.
2924
2925 @item p
2926 Set the target peak value. This specifies the highest permissible magnitude
2927 level for the normalized audio input. This filter will try to approach the
2928 target peak magnitude as closely as possible, but at the same time it also
2929 makes sure that the normalized signal will never exceed the peak magnitude.
2930 A frame's maximum local gain factor is imposed directly by the target peak
2931 magnitude. The default value is 0.95 and thus leaves a headroom of 5%*.
2932 It is not recommended to go above this value.
2933
2934 @item m
2935 Set the maximum gain factor. In range from 1.0 to 100.0. Default is 10.0.
2936 The Dynamic Audio Normalizer determines the maximum possible (local) gain
2937 factor for each input frame, i.e. the maximum gain factor that does not
2938 result in clipping or distortion. The maximum gain factor is determined by
2939 the frame's highest magnitude sample. However, the Dynamic Audio Normalizer
2940 additionally bounds the frame's maximum gain factor by a predetermined
2941 (global) maximum gain factor. This is done in order to avoid excessive gain
2942 factors in "silent" or almost silent frames. By default, the maximum gain
2943 factor is 10.0, For most inputs the default value should be sufficient and
2944 it usually is not recommended to increase this value. Though, for input
2945 with an extremely low overall volume level, it may be necessary to allow even
2946 higher gain factors. Note, however, that the Dynamic Audio Normalizer does
2947 not simply apply a "hard" threshold (i.e. cut off values above the threshold).
2948 Instead, a "sigmoid" threshold function will be applied. This way, the
2949 gain factors will smoothly approach the threshold value, but never exceed that
2950 value.
2951
2952 @item r
2953 Set the target RMS. In range from 0.0 to 1.0. Default is 0.0 - disabled.
2954 By default, the Dynamic Audio Normalizer performs "peak" normalization.
2955 This means that the maximum local gain factor for each frame is defined
2956 (only) by the frame's highest magnitude sample. This way, the samples can
2957 be amplified as much as possible without exceeding the maximum signal
2958 level, i.e. without clipping. Optionally, however, the Dynamic Audio
2959 Normalizer can also take into account the frame's root mean square,
2960 abbreviated RMS. In electrical engineering, the RMS is commonly used to
2961 determine the power of a time-varying signal. It is therefore considered
2962 that the RMS is a better approximation of the "perceived loudness" than
2963 just looking at the signal's peak magnitude. Consequently, by adjusting all
2964 frames to a constant RMS value, a uniform "perceived loudness" can be
2965 established. If a target RMS value has been specified, a frame's local gain
2966 factor is defined as the factor that would result in exactly that RMS value.
2967 Note, however, that the maximum local gain factor is still restricted by the
2968 frame's highest magnitude sample, in order to prevent clipping.
2969
2970 @item n
2971 Enable channels coupling. By default is enabled.
2972 By default, the Dynamic Audio Normalizer will amplify all channels by the same
2973 amount. This means the same gain factor will be applied to all channels, i.e.
2974 the maximum possible gain factor is determined by the "loudest" channel.
2975 However, in some recordings, it may happen that the volume of the different
2976 channels is uneven, e.g. one channel may be "quieter" than the other one(s).
2977 In this case, this option can be used to disable the channel coupling. This way,
2978 the gain factor will be determined independently for each channel, depending
2979 only on the individual channel's highest magnitude sample. This allows for
2980 harmonizing the volume of the different channels.
2981
2982 @item c
2983 Enable DC bias correction. By default is disabled.
2984 An audio signal (in the time domain) is a sequence of sample values.
2985 In the Dynamic Audio Normalizer these sample values are represented in the
2986 -1.0 to 1.0 range, regardless of the original input format. Normally, the
2987 audio signal, or "waveform", should be centered around the zero point.
2988 That means if we calculate the mean value of all samples in a file, or in a
2989 single frame, then the result should be 0.0 or at least very close to that
2990 value. If, however, there is a significant deviation of the mean value from
2991 0.0, in either positive or negative direction, this is referred to as a
2992 DC bias or DC offset. Since a DC bias is clearly undesirable, the Dynamic
2993 Audio Normalizer provides optional DC bias correction.
2994 With DC bias correction enabled, the Dynamic Audio Normalizer will determine
2995 the mean value, or "DC correction" offset, of each input frame and subtract
2996 that value from all of the frame's sample values which ensures those samples
2997 are centered around 0.0 again. Also, in order to avoid "gaps" at the frame
2998 boundaries, the DC correction offset values will be interpolated smoothly
2999 between neighbouring frames.
3000
3001 @item b
3002 Enable alternative boundary mode. By default is disabled.
3003 The Dynamic Audio Normalizer takes into account a certain neighbourhood
3004 around each frame. This includes the preceding frames as well as the
3005 subsequent frames. However, for the "boundary" frames, located at the very
3006 beginning and at the very end of the audio file, not all neighbouring
3007 frames are available. In particular, for the first few frames in the audio
3008 file, the preceding frames are not known. And, similarly, for the last few
3009 frames in the audio file, the subsequent frames are not known. Thus, the
3010 question arises which gain factors should be assumed for the missing frames
3011 in the "boundary" region. The Dynamic Audio Normalizer implements two modes
3012 to deal with this situation. The default boundary mode assumes a gain factor
3013 of exactly 1.0 for the missing frames, resulting in a smooth "fade in" and
3014 "fade out" at the beginning and at the end of the input, respectively.
3015
3016 @item s
3017 Set the compress factor. In range from 0.0 to 30.0. Default is 0.0.
3018 By default, the Dynamic Audio Normalizer does not apply "traditional"
3019 compression. This means that signal peaks will not be pruned and thus the
3020 full dynamic range will be retained within each local neighbourhood. However,
3021 in some cases it may be desirable to combine the Dynamic Audio Normalizer's
3022 normalization algorithm with a more "traditional" compression.
3023 For this purpose, the Dynamic Audio Normalizer provides an optional compression
3024 (thresholding) function. If (and only if) the compression feature is enabled,
3025 all input frames will be processed by a soft knee thresholding function prior
3026 to the actual normalization process. Put simply, the thresholding function is
3027 going to prune all samples whose magnitude exceeds a certain threshold value.
3028 However, the Dynamic Audio Normalizer does not simply apply a fixed threshold
3029 value. Instead, the threshold value will be adjusted for each individual
3030 frame.
3031 In general, smaller parameters result in stronger compression, and vice versa.
3032 Values below 3.0 are not recommended, because audible distortion may appear.
3033 @end table
3034
3035 @section earwax
3036
3037 Make audio easier to listen to on headphones.
3038
3039 This filter adds `cues' to 44.1kHz stereo (i.e. audio CD format) audio
3040 so that when listened to on headphones the stereo image is moved from
3041 inside your head (standard for headphones) to outside and in front of
3042 the listener (standard for speakers).
3043
3044 Ported from SoX.
3045
3046 @section equalizer
3047
3048 Apply a two-pole peaking equalisation (EQ) filter. With this
3049 filter, the signal-level at and around a selected frequency can
3050 be increased or decreased, whilst (unlike bandpass and bandreject
3051 filters) that at all other frequencies is unchanged.
3052
3053 In order to produce complex equalisation curves, this filter can
3054 be given several times, each with a different central frequency.
3055
3056 The filter accepts the following options:
3057
3058 @table @option
3059 @item frequency, f
3060 Set the filter's central frequency in Hz.
3061
3062 @item width_type, t
3063 Set method to specify band-width of filter.
3064 @table @option
3065 @item h
3066 Hz
3067 @item q
3068 Q-Factor
3069 @item o
3070 octave
3071 @item s
3072 slope
3073 @item k
3074 kHz
3075 @end table
3076
3077 @item width, w
3078 Specify the band-width of a filter in width_type units.
3079
3080 @item gain, g
3081 Set the required gain or attenuation in dB.
3082 Beware of clipping when using a positive gain.
3083
3084 @item channels, c
3085 Specify which channels to filter, by default all available are filtered.
3086 @end table
3087
3088 @subsection Examples
3089 @itemize
3090 @item
3091 Attenuate 10 dB at 1000 Hz, with a bandwidth of 200 Hz:
3092 @example
3093 equalizer=f=1000:t=h:width=200:g=-10
3094 @end example
3095
3096 @item
3097 Apply 2 dB gain at 1000 Hz with Q 1 and attenuate 5 dB at 100 Hz with Q 2:
3098 @example
3099 equalizer=f=1000:t=q:w=1:g=2,equalizer=f=100:t=q:w=2:g=-5
3100 @end example
3101 @end itemize
3102
3103 @subsection Commands
3104
3105 This filter supports the following commands:
3106 @table @option
3107 @item frequency, f
3108 Change equalizer frequency.
3109 Syntax for the command is : "@var{frequency}"
3110
3111 @item width_type, t
3112 Change equalizer width_type.
3113 Syntax for the command is : "@var{width_type}"
3114
3115 @item width, w
3116 Change equalizer width.
3117 Syntax for the command is : "@var{width}"
3118
3119 @item gain, g
3120 Change equalizer gain.
3121 Syntax for the command is : "@var{gain}"
3122 @end table
3123
3124 @section extrastereo
3125
3126 Linearly increases the difference between left and right channels which
3127 adds some sort of "live" effect to playback.
3128
3129 The filter accepts the following options:
3130
3131 @table @option
3132 @item m
3133 Sets the difference coefficient (default: 2.5). 0.0 means mono sound
3134 (average of both channels), with 1.0 sound will be unchanged, with
3135 -1.0 left and right channels will be swapped.
3136
3137 @item c
3138 Enable clipping. By default is enabled.
3139 @end table
3140
3141 @section firequalizer
3142 Apply FIR Equalization using arbitrary frequency response.
3143
3144 The filter accepts the following option:
3145
3146 @table @option
3147 @item gain
3148 Set gain curve equation (in dB). The expression can contain variables:
3149 @table @option
3150 @item f
3151 the evaluated frequency
3152 @item sr
3153 sample rate
3154 @item ch
3155 channel number, set to 0 when multichannels evaluation is disabled
3156 @item chid
3157 channel id, see libavutil/channel_layout.h, set to the first channel id when
3158 multichannels evaluation is disabled
3159 @item chs
3160 number of channels
3161 @item chlayout
3162 channel_layout, see libavutil/channel_layout.h
3163
3164 @end table
3165 and functions:
3166 @table @option
3167 @item gain_interpolate(f)
3168 interpolate gain on frequency f based on gain_entry
3169 @item cubic_interpolate(f)
3170 same as gain_interpolate, but smoother
3171 @end table
3172 This option is also available as command. Default is @code{gain_interpolate(f)}.
3173
3174 @item gain_entry
3175 Set gain entry for gain_interpolate function. The expression can
3176 contain functions:
3177 @table @option
3178 @item entry(f, g)
3179 store gain entry at frequency f with value g
3180 @end table
3181 This option is also available as command.
3182
3183 @item delay
3184 Set filter delay in seconds. Higher value means more accurate.
3185 Default is @code{0.01}.
3186
3187 @item accuracy
3188 Set filter accuracy in Hz. Lower value means more accurate.
3189 Default is @code{5}.
3190
3191 @item wfunc
3192 Set window function. Acceptable values are:
3193 @table @option
3194 @item rectangular
3195 rectangular window, useful when gain curve is already smooth
3196 @item hann
3197 hann window (default)
3198 @item hamming
3199 hamming window
3200 @item blackman
3201 blackman window
3202 @item nuttall3
3203 3-terms continuous 1st derivative nuttall window
3204 @item mnuttall3
3205 minimum 3-terms discontinuous nuttall window
3206 @item nuttall
3207 4-terms continuous 1st derivative nuttall window
3208 @item bnuttall
3209 minimum 4-terms discontinuous nuttall (blackman-nuttall) window
3210 @item bharris
3211 blackman-harris window
3212 @item tukey
3213 tukey window
3214 @end table
3215
3216 @item fixed
3217 If enabled, use fixed number of audio samples. This improves speed when
3218 filtering with large delay. Default is disabled.
3219
3220 @item multi
3221 Enable multichannels evaluation on gain. Default is disabled.
3222
3223 @item zero_phase
3224 Enable zero phase mode by subtracting timestamp to compensate delay.
3225 Default is disabled.
3226
3227 @item scale
3228 Set scale used by gain. Acceptable values are:
3229 @table @option
3230 @item linlin
3231 linear frequency, linear gain
3232 @item linlog
3233 linear frequency, logarithmic (in dB) gain (default)
3234 @item loglin
3235 logarithmic (in octave scale where 20 Hz is 0) frequency, linear gain
3236 @item loglog
3237 logarithmic frequency, logarithmic gain
3238 @end table
3239
3240 @item dumpfile
3241 Set file for dumping, suitable for gnuplot.
3242
3243 @item dumpscale
3244 Set scale for dumpfile. Acceptable values are same with scale option.
3245 Default is linlog.
3246
3247 @item fft2
3248 Enable 2-channel convolution using complex FFT. This improves speed significantly.
3249 Default is disabled.
3250
3251 @item min_phase
3252 Enable minimum phase impulse response. Default is disabled.
3253 @end table
3254
3255 @subsection Examples
3256 @itemize
3257 @item
3258 lowpass at 1000 Hz:
3259 @example
3260 firequalizer=gain='if(lt(f,1000), 0, -INF)'
3261 @end example
3262 @item
3263 lowpass at 1000 Hz with gain_entry:
3264 @example
3265 firequalizer=gain_entry='entry(1000,0); entry(1001, -INF)'
3266 @end example
3267 @item
3268 custom equalization:
3269 @example
3270 firequalizer=gain_entry='entry(100,0); entry(400, -4); entry(1000, -6); entry(2000, 0)'
3271 @end example
3272 @item
3273 higher delay with zero phase to compensate delay:
3274 @example
3275 firequalizer=delay=0.1:fixed=on:zero_phase=on
3276 @end example
3277 @item
3278 lowpass on left channel, highpass on right channel:
3279 @example
3280 firequalizer=gain='if(eq(chid,1), gain_interpolate(f), if(eq(chid,2), gain_interpolate(1e6+f), 0))'
3281 :gain_entry='entry(1000, 0); entry(1001,-INF); entry(1e6+1000,0)':multi=on
3282 @end example
3283 @end itemize
3284
3285 @section flanger
3286 Apply a flanging effect to the audio.
3287
3288 The filter accepts the following options:
3289
3290 @table @option
3291 @item delay
3292 Set base delay in milliseconds. Range from 0 to 30. Default value is 0.
3293
3294 @item depth
3295 Set added sweep delay in milliseconds. Range from 0 to 10. Default value is 2.
3296
3297 @item regen
3298 Set percentage regeneration (delayed signal feedback). Range from -95 to 95.
3299 Default value is 0.
3300
3301 @item width
3302 Set percentage of delayed signal mixed with original. Range from 0 to 100.
3303 Default value is 71.
3304
3305 @item speed
3306 Set sweeps per second (Hz). Range from 0.1 to 10. Default value is 0.5.
3307
3308 @item shape
3309 Set swept wave shape, can be @var{triangular} or @var{sinusoidal}.
3310 Default value is @var{sinusoidal}.
3311
3312 @item phase
3313 Set swept wave percentage-shift for multi channel. Range from 0 to 100.
3314 Default value is 25.
3315
3316 @item interp
3317 Set delay-line interpolation, @var{linear} or @var{quadratic}.
3318 Default is @var{linear}.
3319 @end table
3320
3321 @section haas
3322 Apply Haas effect to audio.
3323
3324 Note that this makes most sense to apply on mono signals.
3325 With this filter applied to mono signals it give some directionality and
3326 stretches its stereo image.
3327
3328 The filter accepts the following options:
3329
3330 @table @option
3331 @item level_in
3332 Set input level. By default is @var{1}, or 0dB
3333
3334 @item level_out
3335 Set output level. By default is @var{1}, or 0dB.
3336
3337 @item side_gain
3338 Set gain applied to side part of signal. By default is @var{1}.
3339
3340 @item middle_source
3341 Set kind of middle source. Can be one of the following:
3342
3343 @table @samp
3344 @item left
3345 Pick left channel.
3346
3347 @item right
3348 Pick right channel.
3349
3350 @item mid
3351 Pick middle part signal of stereo image.
3352
3353 @item side
3354 Pick side part signal of stereo image.
3355 @end table
3356
3357 @item middle_phase
3358 Change middle phase. By default is disabled.
3359
3360 @item left_delay
3361 Set left channel delay. By default is @var{2.05} milliseconds.
3362
3363 @item left_balance
3364 Set left channel balance. By default is @var{-1}.
3365
3366 @item left_gain
3367 Set left channel gain. By default is @var{1}.
3368
3369 @item left_phase
3370 Change left phase. By default is disabled.
3371
3372 @item right_delay
3373 Set right channel delay. By defaults is @var{2.12} milliseconds.
3374
3375 @item right_balance
3376 Set right channel balance. By default is @var{1}.
3377
3378 @item right_gain
3379 Set right channel gain. By default is @var{1}.
3380
3381 @item right_phase
3382 Change right phase. By default is enabled.
3383 @end table
3384
3385 @section hdcd
3386
3387 Decodes High Definition Compatible Digital (HDCD) data. A 16-bit PCM stream with
3388 embedded HDCD codes is expanded into a 20-bit PCM stream.
3389
3390 The filter supports the Peak Extend and Low-level Gain Adjustment features
3391 of HDCD, and detects the Transient Filter flag.
3392
3393 @example
3394 ffmpeg -i HDCD16.flac -af hdcd OUT24.flac
3395 @end example
3396
3397 When using the filter with wav, note the default encoding for wav is 16-bit,
3398 so the resulting 20-bit stream will be truncated back to 16-bit. Use something
3399 like @command{-acodec pcm_s24le} after the filter to get 24-bit PCM output.
3400 @example
3401 ffmpeg -i HDCD16.wav -af hdcd OUT16.wav
3402 ffmpeg -i HDCD16.wav -af hdcd -c:a pcm_s24le OUT24.wav
3403 @end example
3404
3405 The filter accepts the following options:
3406
3407 @table @option
3408 @item disable_autoconvert
3409 Disable any automatic format conversion or resampling in the filter graph.
3410
3411 @item process_stereo
3412 Process the stereo channels together. If target_gain does not match between
3413 channels, consider it invalid and use the last valid target_gain.
3414
3415 @item cdt_ms
3416 Set the code detect timer period in ms.
3417
3418 @item force_pe
3419 Always extend peaks above -3dBFS even if PE isn't signaled.
3420
3421 @item analyze_mode
3422 Replace audio with a solid tone and adjust the amplitude to signal some
3423 specific aspect of the decoding process. The output file can be loaded in
3424 an audio editor alongside the original to aid analysis.
3425
3426 @code{analyze_mode=pe:force_pe=true} can be used to see all samples above the PE level.
3427
3428 Modes are:
3429 @table @samp
3430 @item 0, off
3431 Disabled
3432 @item 1, lle
3433 Gain adjustment level at each sample
3434 @item 2, pe
3435 Samples where peak extend occurs
3436 @item 3, cdt
3437 Samples where the code detect timer is active
3438 @item 4, tgm
3439 Samples where the target gain does not match between channels
3440 @end table
3441 @end table
3442
3443 @section headphone
3444
3445 Apply head-related transfer functions (HRTFs) to create virtual
3446 loudspeakers around the user for binaural listening via headphones.
3447 The HRIRs are provided via additional streams, for each channel
3448 one stereo input stream is needed.
3449
3450 The filter accepts the following options:
3451
3452 @table @option
3453 @item map
3454 Set mapping of input streams for convolution.
3455 The argument is a '|'-separated list of channel names in order as they
3456 are given as additional stream inputs for filter.
3457 This also specify number of input streams. Number of input streams
3458 must be not less than number of channels in first stream plus one.
3459
3460 @item gain
3461 Set gain applied to audio. Value is in dB. Default is 0.
3462
3463 @item type
3464 Set processing type. Can be @var{time} or @var{freq}. @var{time} is
3465 processing audio in time domain which is slow.
3466 @var{freq} is processing audio in frequency domain which is fast.
3467 Default is @var{freq}.
3468
3469 @item lfe
3470 Set custom gain for LFE channels. Value is in dB. Default is 0.
3471
3472 @item size
3473 Set size of frame in number of samples which will be processed at once.
3474 Default value is @var{1024}. Allowed range is from 1024 to 96000.
3475
3476 @item hrir
3477 Set format of hrir stream.
3478 Default value is @var{stereo}. Alternative value is @var{multich}.
3479 If value is set to @var{stereo}, number of additional streams should
3480 be greater or equal to number of input channels in first input stream.
3481 Also each additional stream should have stereo number of channels.
3482 If value is set to @var{multich}, number of additional streams should
3483 be exactly one. Also number of input channels of additional stream
3484 should be equal or greater than twice number of channels of first input
3485 stream.
3486 @end table
3487
3488 @subsection Examples
3489
3490 @itemize
3491 @item
3492 Full example using wav files as coefficients with amovie filters for 7.1 downmix,
3493 each amovie filter use stereo file with IR coefficients as input.
3494 The files give coefficients for each position of virtual loudspeaker:
3495 @example
3496 ffmpeg -i input.wav -lavfi-complex "amovie=azi_270_ele_0_DFC.wav[sr],amovie=azi_90_ele_0_DFC.wav[sl],amovie=azi_225_ele_0_DFC.wav[br],amovie=azi_135_ele_0_DFC.wav[bl],amovie=azi_0_ele_0_DFC.wav,asplit[fc][lfe],amovie=azi_35_ele_0_DFC.wav[fl],amovie=azi_325_ele_0_DFC.wav[fr],[a:0][fl][fr][fc][lfe][bl][br][sl][sr]headphone=FL|FR|FC|LFE|BL|BR|SL|SR"
3497 output.wav
3498 @end example
3499
3500 @item
3501 Full example using wav files as coefficients with amovie filters for 7.1 downmix,
3502 but now in @var{multich} @var{hrir} format.
3503 @example
3504 ffmpeg -i input.wav -lavfi-complex "amovie=minp.wav[hrirs],[a:0][hrirs]headphone=map=FL|FR|FC|LFE|BL|BR|SL|SR:hrir=multich"
3505 output.wav
3506 @end example
3507 @end itemize
3508
3509 @section highpass
3510
3511 Apply a high-pass filter with 3dB point frequency.
3512 The filter can be either single-pole, or double-pole (the default).
3513 The filter roll off at 6dB per pole per octave (20dB per pole per decade).
3514
3515 The filter accepts the following options:
3516
3517 @table @option
3518 @item frequency, f
3519 Set frequency in Hz. Default is 3000.
3520
3521 @item poles, p
3522 Set number of poles. Default is 2.
3523
3524 @item width_type, t
3525 Set method to specify band-width of filter.
3526 @table @option
3527 @item h
3528 Hz
3529 @item q
3530 Q-Factor
3531 @item o
3532 octave
3533 @item s
3534 slope
3535 @item k
3536 kHz
3537 @end table
3538
3539 @item width, w
3540 Specify the band-width of a filter in width_type units.
3541 Applies only to double-pole filter.
3542 The default is 0.707q and gives a Butterworth response.
3543
3544 @item channels, c
3545 Specify which channels to filter, by default all available are filtered.
3546 @end table
3547
3548 @subsection Commands
3549
3550 This filter supports the following commands:
3551 @table @option
3552 @item frequency, f
3553 Change highpass frequency.
3554 Syntax for the command is : "@var{frequency}"
3555
3556 @item width_type, t
3557 Change highpass width_type.
3558 Syntax for the command is : "@var{width_type}"
3559
3560 @item width, w
3561 Change highpass width.
3562 Syntax for the command is : "@var{width}"
3563 @end table
3564
3565 @section join
3566
3567 Join multiple input streams into one multi-channel stream.
3568
3569 It accepts the following parameters:
3570 @table @option
3571
3572 @item inputs
3573 The number of input streams. It defaults to 2.
3574
3575 @item channel_layout
3576 The desired output channel layout. It defaults to stereo.
3577
3578 @item map
3579 Map channels from inputs to output. The argument is a '|'-separated list of
3580 mappings, each in the @code{@var{input_idx}.@var{in_channel}-@var{out_channel}}
3581 form. @var{input_idx} is the 0-based index of the input stream. @var{in_channel}
3582 can be either the name of the input channel (e.g. FL for front left) or its
3583 index in the specified input stream. @var{out_channel} is the name of the output
3584 channel.
3585 @end table
3586
3587 The filter will attempt to guess the mappings when they are not specified
3588 explicitly. It does so by first trying to find an unused matching input channel
3589 and if that fails it picks the first unused input channel.
3590
3591 Join 3 inputs (with properly set channel layouts):
3592 @example
3593 ffmpeg -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT
3594 @end example
3595
3596 Build a 5.1 output from 6 single-channel streams:
3597 @example
3598 ffmpeg -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex
3599 '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'
3600 out
3601 @end example
3602
3603 @section ladspa
3604
3605 Load a LADSPA (Linux Audio Developer's Simple Plugin API) plugin.
3606
3607 To enable compilation of this filter you need to configure FFmpeg with
3608 @code{--enable-ladspa}.
3609
3610 @table @option
3611 @item file, f
3612 Specifies the name of LADSPA plugin library to load. If the environment
3613 variable @env{LADSPA_PATH} is defined, the LADSPA plugin is searched in
3614 each one of the directories specified by the colon separated list in
3615 @env{LADSPA_PATH}, otherwise in the standard LADSPA paths, which are in
3616 this order: @file{HOME/.ladspa/lib/}, @file{/usr/local/lib/ladspa/},
3617 @file{/usr/lib/ladspa/}.
3618
3619 @item plugin, p
3620 Specifies the plugin within the library. Some libraries contain only
3621 one plugin, but others contain many of them. If this is not set filter
3622 will list all available plugins within the specified library.
3623
3624 @item controls, c
3625 Set the '|' separated list of controls which are zero or more floating point
3626 values that determine the behavior of the loaded plugin (for example delay,
3627 threshold or gain).
3628 Controls need to be defined using the following syntax:
3629 c0=@var{value0}|c1=@var{value1}|c2=@var{value2}|..., where
3630 @var{valuei} is the value set on the @var{i}-th control.
3631 Alternatively they can be also defined using the following syntax:
3632 @var{value0}|@var{value1}|@var{value2}|..., where
3633 @var{valuei} is the value set on the @var{i}-th control.
3634 If @option{controls} is set to @code{help}, all available controls and
3635 their valid ranges are printed.
3636
3637 @item sample_rate, s
3638 Specify the sample rate, default to 44100. Only used if plugin have
3639 zero inputs.
3640
3641 @item nb_samples, n
3642 Set the number of samples per channel per each output frame, default
3643 is 1024. Only used if plugin have zero inputs.
3644
3645 @item duration, d
3646 Set the minimum duration of the sourced audio. See
3647 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
3648 for the accepted syntax.
3649 Note that the resulting duration may be greater than the specified duration,
3650 as the generated audio is always cut at the end of a complete frame.
3651 If not specified, or the expressed duration is negative, the audio is
3652 supposed to be generated forever.
3653 Only used if plugin have zero inputs.
3654
3655 @end table
3656
3657 @subsection Examples
3658
3659 @itemize
3660 @item
3661 List all available plugins within amp (LADSPA example plugin) library:
3662 @example
3663 ladspa=file=amp
3664 @end example
3665
3666 @item
3667 List all available controls and their valid ranges for @code{vcf_notch}
3668 plugin from @code{VCF} library:
3669 @example
3670 ladspa=f=vcf:p=vcf_notch:c=help
3671 @end example
3672
3673 @item
3674 Simulate low quality audio equipment using @code{Computer Music Toolkit} (CMT)
3675 plugin library:
3676 @example
3677 ladspa=file=cmt:plugin=lofi:controls=c0=22|c1=12|c2=12
3678 @end example
3679
3680 @item
3681 Add reverberation to the audio using TAP-plugins
3682 (Tom's Audio Processing plugins):
3683 @example
3684 ladspa=file=tap_reverb:tap_reverb
3685 @end example
3686
3687 @item
3688 Generate white noise, with 0.2 amplitude:
3689 @example
3690 ladspa=file=cmt:noise_source_white:c=c0=.2
3691 @end example
3692
3693 @item
3694 Generate 20 bpm clicks using plugin @code{C* Click - Metronome} from the
3695 @code{C* Audio Plugin Suite} (CAPS) library:
3696 @example
3697 ladspa=file=caps:Click:c=c1=20'
3698 @end example
3699
3700 @item
3701 Apply @code{C* Eq10X2 - Stereo 10-band equaliser} effect:
3702 @example
3703 ladspa=caps:Eq10X2:c=c0=-48|c9=-24|c3=12|c4=2
3704 @end example
3705
3706 @item
3707 Increase volume by 20dB using fast lookahead limiter from Steve Harris
3708 @code{SWH Plugins} collection:
3709 @example
3710 ladspa=fast_lookahead_limiter_1913:fastLookaheadLimiter:20|0|2
3711 @end example
3712
3713 @item
3714 Attenuate low frequencies using Multiband EQ from Steve Harris
3715 @code{SWH Plugins} collection:
3716 @example
3717 ladspa=mbeq_1197:mbeq:-24|-24|-24|0|0|0|0|0|0|0|0|0|0|0|0
3718 @end example
3719
3720 @item
3721 Reduce stereo image using @code{Narrower} from the @code{C* Audio Plugin Suite}
3722 (CAPS) library:
3723 @example
3724 ladspa=caps:Narrower
3725 @end example
3726
3727 @item
3728 Another white noise, now using @code{C* Audio Plugin Suite} (CAPS) library:
3729 @example
3730 ladspa=caps:White:.2
3731 @end example
3732
3733 @item
3734 Some fractal noise, using @code{C* Audio Plugin Suite} (CAPS) library:
3735 @example
3736 ladspa=caps:Fractal:c=c1=1
3737 @end example
3738
3739 @item
3740 Dynamic volume normalization using @code{VLevel} plugin:
3741 @example
3742 ladspa=vlevel-ladspa:vlevel_mono
3743 @end example
3744 @end itemize
3745
3746 @subsection Commands
3747
3748 This filter supports the following commands:
3749 @table @option
3750 @item cN
3751 Modify the @var{N}-th control value.
3752
3753 If the specified value is not valid, it is ignored and prior one is kept.
3754 @end table
3755
3756 @section loudnorm
3757
3758 EBU R128 loudness normalization. Includes both dynamic and linear normalization modes.
3759 Support for both single pass (livestreams, files) and double pass (files) modes.
3760 This algorithm can target IL, LRA, and maximum true peak. To accurately detect true peaks,
3761 the audio stream will be upsampled to 192 kHz unless the normalization mode is linear.
3762 Use the @code{-ar} option or @code{aresample} filter to explicitly set an output sample rate.
3763
3764 The filter accepts the following options:
3765
3766 @table @option
3767 @item I, i
3768 Set integrated loudness target.
3769 Range is -70.0 - -5.0. Default value is -24.0.
3770
3771 @item LRA, lra
3772 Set loudness range target.
3773 Range is 1.0 - 20.0. Default value is 7.0.
3774
3775 @item TP, tp
3776 Set maximum true peak.
3777 Range is -9.0 - +0.0. Default value is -2.0.
3778
3779 @item measured_I, measured_i
3780 Measured IL of input file.
3781 Range is -99.0 - +0.0.
3782
3783 @item measured_LRA, measured_lra
3784 Measured LRA of input file.
3785 Range is  0.0 - 99.0.
3786
3787 @item measured_TP, measured_tp
3788 Measured true peak of input file.
3789 Range is  -99.0 - +99.0.
3790
3791 @item measured_thresh
3792 Measured threshold of input file.
3793 Range is -99.0 - +0.0.
3794
3795 @item offset
3796 Set offset gain. Gain is applied before the true-peak limiter.
3797 Range is  -99.0 - +99.0. Default is +0.0.
3798
3799 @item linear
3800 Normalize linearly if possible.
3801 measured_I, measured_LRA, measured_TP, and measured_thresh must also
3802 to be specified in order to use this mode.
3803 Options are true or false. Default is true.
3804
3805 @item dual_mono
3806 Treat mono input files as "dual-mono". If a mono file is intended for playback
3807 on a stereo system, its EBU R128 measurement will be perceptually incorrect.
3808 If set to @code{true}, this option will compensate for this effect.
3809 Multi-channel input files are not affected by this option.
3810 Options are true or false. Default is false.
3811
3812 @item print_format
3813 Set print format for stats. Options are summary, json, or none.
3814 Default value is none.
3815 @end table
3816
3817 @section lowpass
3818
3819 Apply a low-pass filter with 3dB point frequency.
3820 The filter can be either single-pole or double-pole (the default).
3821 The filter roll off at 6dB per pole per octave (20dB per pole per decade).
3822
3823 The filter accepts the following options:
3824
3825 @table @option
3826 @item frequency, f
3827 Set frequency in Hz. Default is 500.
3828
3829 @item poles, p
3830 Set number of poles. Default is 2.
3831
3832 @item width_type, t
3833 Set method to specify band-width of filter.
3834 @table @option
3835 @item h
3836 Hz
3837 @item q
3838 Q-Factor
3839 @item o
3840 octave
3841 @item s
3842 slope
3843 @item k
3844 kHz
3845 @end table
3846
3847 @item width, w
3848 Specify the band-width of a filter in width_type units.
3849 Applies only to double-pole filter.
3850 The default is 0.707q and gives a Butterworth response.
3851
3852 @item channels, c
3853 Specify which channels to filter, by default all available are filtered.
3854 @end table
3855
3856 @subsection Examples
3857 @itemize
3858 @item
3859 Lowpass only LFE channel, it LFE is not present it does nothing:
3860 @example
3861 lowpass=c=LFE
3862 @end example
3863 @end itemize
3864
3865 @subsection Commands
3866
3867 This filter supports the following commands:
3868 @table @option
3869 @item frequency, f
3870 Change lowpass frequency.
3871 Syntax for the command is : "@var{frequency}"
3872
3873 @item width_type, t
3874 Change lowpass width_type.
3875 Syntax for the command is : "@var{width_type}"
3876
3877 @item width, w
3878 Change lowpass width.
3879 Syntax for the command is : "@var{width}"
3880 @end table
3881
3882 @section lv2
3883
3884 Load a LV2 (LADSPA Version 2) plugin.
3885
3886 To enable compilation of this filter you need to configure FFmpeg with
3887 @code{--enable-lv2}.
3888
3889 @table @option
3890 @item plugin, p
3891 Specifies the plugin URI. You may need to escape ':'.
3892
3893 @item controls, c
3894 Set the '|' separated list of controls which are zero or more floating point
3895 values that determine the behavior of the loaded plugin (for example delay,
3896 threshold or gain).
3897 If @option{controls} is set to @code{help}, all available controls and
3898 their valid ranges are printed.
3899
3900 @item sample_rate, s
3901 Specify the sample rate, default to 44100. Only used if plugin have
3902 zero inputs.
3903
3904 @item nb_samples, n
3905 Set the number of samples per channel per each output frame, default
3906 is 1024. Only used if plugin have zero inputs.
3907
3908 @item duration, d
3909 Set the minimum duration of the sourced audio. See
3910 @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
3911 for the accepted syntax.
3912 Note that the resulting duration may be greater than the specified duration,
3913 as the generated audio is always cut at the end of a complete frame.
3914 If not specified, or the expressed duration is negative, the audio is
3915 supposed to be generated forever.
3916 Only used if plugin have zero inputs.
3917 @end table
3918
3919 @subsection Examples
3920
3921 @itemize
3922 @item
3923 Apply bass enhancer plugin from Calf:
3924 @example
3925 lv2=p=http\\\\://calf.sourceforge.net/plugins/BassEnhancer:c=amount=2
3926 @end example
3927
3928 @item
3929 Apply vinyl plugin from Calf:
3930 @example
3931 lv2=p=http\\\\://calf.sourceforge.net/plugins/Vinyl:c=drone=0.2|aging=0.5
3932 @end example
3933
3934 @item
3935 Apply bit crusher plugin from ArtyFX:
3936 @example
3937 lv2=p=http\\\\://www.openavproductions.com/artyfx#bitta:c=crush=0.3
3938 @end example
3939 @end itemize
3940
3941 @section mcompand
3942 Multiband Compress or expand the audio's dynamic range.
3943
3944 The input audio is divided into bands using 4th order Linkwitz-Riley IIRs.
3945 This is akin to the crossover of a loudspeaker, and results in flat frequency
3946 response when absent compander action.
3947
3948 It accepts the following parameters:
3949
3950 @table @option
3951 @item args
3952 This option syntax is:
3953 attack,decay,[attack,decay..] soft-knee points crossover_frequency [delay [initial_volume [gain]]] | attack,decay ...
3954 For explanation of each item refer to compand filter documentation.
3955 @end table
3956
3957 @anchor{pan}
3958 @section pan
3959
3960 Mix channels with specific gain levels. The filter accepts the output
3961 channel layout followed by a set of channels definitions.
3962
3963 This filter is also designed to efficiently remap the channels of an audio
3964 stream.
3965
3966 The filter accepts parameters of the form:
3967 "@var{l}|@var{outdef}|@var{outdef}|..."
3968
3969 @table @option
3970 @item l
3971 output channel layout or number of channels
3972
3973 @item outdef
3974 output channel specification, of the form:
3975 "@var{out_name}=[@var{gain}*]@var{in_name}[(+-)[@var{gain}*]@var{in_name}...]"
3976
3977 @item out_name
3978 output channel to define, either a channel name (FL, FR, etc.) or a channel
3979 number (c0, c1, etc.)
3980
3981 @item gain
3982 multiplicative coefficient for the channel, 1 leaving the volume unchanged
3983
3984 @item in_name
3985 input channel to use, see out_name for details; it is not possible to mix
3986 named and numbered input channels
3987 @end table
3988
3989 If the `=' in a channel specification is replaced by `<', then the gains for
3990 that specification will be renormalized so that the total is 1, thus
3991 avoiding clipping noise.
3992
3993 @subsection Mixing examples
3994
3995 For example, if you want to down-mix from stereo to mono, but with a bigger
3996 factor for the left channel:
3997 @example
3998 pan=1c|c0=0.9*c0+0.1*c1
3999 @end example
4000
4001 A customized down-mix to stereo that works automatically for 3-, 4-, 5- and
4002 7-channels surround:
4003 @example
4004 pan=stereo| FL < FL + 0.5*FC + 0.6*BL + 0.6*SL | FR < FR + 0.5*FC + 0.6*BR + 0.6*SR
4005 @end example
4006
4007 Note that @command{ffmpeg} integrates a default down-mix (and up-mix) system
4008 that should be preferred (see "-ac" option) unless you have very specific
4009 needs.
4010
4011 @subsection Remapping examples
4012
4013 The channel remapping will be effective if, and only if:
4014
4015 @itemize
4016 @item gain coefficients are zeroes or ones,
4017 @item only one input per channel output,
4018 @end itemize
4019
4020 If all these conditions are satisfied, the filter will notify the user ("Pure
4021 channel mapping detected"), and use an optimized and lossless method to do the
4022 remapping.
4023
4024 For example, if you have a 5.1 source and want a stereo audio stream by
4025 dropping the extra channels:
4026 @example
4027 pan="stereo| c0=FL | c1=FR"
4028 @end example
4029
4030 Given the same source, you can also switch front left and front right channels
4031 and keep the input channel layout:
4032 @example
4033 pan="5.1| c0=c1 | c1=c0 | c2=c2 | c3=c3 | c4=c4 | c5=c5"
4034 @end example
4035
4036 If the input is a stereo audio stream, you can mute the front left channel (and
4037 still keep the stereo channel layout) with:
4038 @example
4039 pan="stereo|c1=c1"
4040 @end example
4041
4042 Still with a stereo audio stream input, you can copy the right channel in both
4043 front left and right:
4044 @example
4045 pan="stereo| c0=FR | c1=FR"
4046 @end example
4047
4048 @section replaygain
4049
4050 ReplayGain scanner filter. This filter takes an audio stream as an input and
4051 outputs it unchanged.
4052 At end of filtering it displays @code{track_gain} and @code{track_peak}.
4053
4054 @section resample
4055
4056 Convert the audio sample format, sample rate and channel layout. It is
4057 not meant to be used directly.
4058
4059 @section rubberband
4060 Apply time-stretching and pitch-shifting with librubberband.
4061
4062 To enable compilation of this filter, you need to configure FFmpeg with
4063 @code{--enable-librubberband}.
4064
4065 The filter accepts the following options:
4066
4067 @table @option
4068 @item tempo
4069 Set tempo scale factor.
4070
4071 @item pitch
4072 Set pitch scale factor.
4073
4074 @item transients
4075 Set transients detector.
4076 Possible values are:
4077 @table @var
4078 @item crisp
4079 @item mixed
4080 @item smooth
4081 @end table
4082
4083 @item detector
4084 Set detector.
4085 Possible values are:
4086 @table @var
4087 @item compound
4088 @item percussive
4089 @item soft
4090 @end table
4091
4092 @item phase
4093 Set phase.
4094 Possible values are:
4095 @table @var
4096 @item laminar
4097 @item independent
4098 @end table
4099
4100 @item window
4101 Set processing window size.
4102 Possible values are:
4103 @table @var
4104 @item standard
4105 @item short
4106 @item long
4107 @end table
4108
4109 @item smoothing
4110 Set smoothing.
4111 Possible values are:
4112 @table @var
4113 @item off
4114 @item on
4115 @end table
4116
4117 @item formant
4118 Enable formant preservation when shift pitching.
4119 Possible values are:
4120 @table @var
4121 @item shifted
4122 @item preserved
4123 @end table
4124
4125 @item pitchq
4126 Set pitch quality.
4127 Possible values are:
4128 @table @var
4129 @item quality
4130 @item speed
4131 @item consistency
4132 @end table
4133
4134 @item channels
4135 Set channels.
4136 Possible values are:
4137 @table @var
4138 @item apart
4139 @item together
4140 @end table
4141 @end table
4142
4143 @section sidechaincompress
4144
4145 This filter acts like normal compressor but has the ability to compress
4146 detected signal using second input signal.
4147 It needs two input streams and returns one output stream.
4148 First input stream will be processed depending on second stream signal.
4149 The filtered signal then can be filtered with other filters in later stages of
4150 processing. See @ref{pan} and @ref{amerge} filter.
4151
4152 The filter accepts the following options:
4153
4154 @table @option
4155 @item level_in
4156 Set input gain. Default is 1. Range is between 0.015625 and 64.
4157
4158 @item threshold
4159 If a signal of second stream raises above this level it will affect the gain
4160 reduction of first stream.
4161 By default is 0.125. Range is between 0.00097563 and 1.
4162
4163 @item ratio
4164 Set a ratio about which the signal is reduced. 1:2 means that if the level
4165 raised 4dB above the threshold, it will be only 2dB above after the reduction.
4166 Default is 2. Range is between 1 and 20.
4167
4168 @item attack
4169 Amount of milliseconds the signal has to rise above the threshold before gain
4170 reduction starts. Default is 20. Range is between 0.01 and 2000.
4171
4172 @item release
4173 Amount of milliseconds the signal has to fall below the threshold before
4174 reduction is decreased again. Default is 250. Range is between 0.01 and 9000.
4175
4176 @item makeup
4177 Set the amount by how much signal will be amplified after processing.
4178 Default is 1. Range is from 1 to 64.
4179
4180 @item knee
4181 Curve the sharp knee around the threshold to enter gain reduction more softly.
4182 Default is 2.82843. Range is between 1 and 8.
4183
4184 @item link
4185 Choose if the @code{average} level between all channels of side-chain stream
4186 or the louder(@code{maximum}) channel of side-chain stream affects the
4187 reduction. Default is @code{average}.
4188
4189 @item detection
4190 Should the exact signal be taken in case of @code{peak} or an RMS one in case
4191 of @code{rms}. Default is @code{rms} which is mainly smoother.
4192
4193 @item level_sc
4194 Set sidechain gain. Default is 1. Range is between 0.015625 and 64.
4195
4196 @item mix
4197 How much to use compressed signal in output. Default is 1.
4198 Range is between 0 and 1.
4199 @end table
4200
4201 @subsection Examples
4202
4203 @itemize
4204 @item
4205 Full ffmpeg example taking 2 audio inputs, 1st input to be compressed
4206 depending on the signal of 2nd input and later compressed signal to be
4207 merged with 2nd input:
4208 @example
4209 ffmpeg -i main.flac -i sidechain.flac -filter_complex "[1:a]asplit=2[sc][mix];[0:a][sc]sidechaincompress[compr];[compr][mix]amerge"
4210 @end example
4211 @end itemize
4212
4213 @section sidechaingate
4214
4215 A sidechain gate acts like a normal (wideband) gate but has the ability to
4216 filter the detected signal before sending it to the gain reduction stage.
4217 Normally a gate uses the full range signal to detect a level above the
4218 threshold.
4219 For example: If you cut all lower frequencies from your sidechain signal
4220 the gate will decrease the volume of your track only if not enough highs
4221 appear. With this technique you are able to reduce the resonation of a
4222 natural drum or remove "rumbling" of muted strokes from a heavily distorted
4223 guitar.
4224 It needs two input streams and returns one output stream.
4225 First input stream will be processed depending on second stream signal.
4226
4227 The filter accepts the following options:
4228
4229 @table @option
4230 @item level_in
4231 Set input level before filtering.
4232 Default is 1. Allowed range is from 0.015625 to 64.
4233
4234 @item range
4235 Set the level of gain reduction when the signal is below the threshold.
4236 Default is 0.06125. Allowed range is from 0 to 1.
4237
4238 @item threshold
4239 If a signal rises above this level the gain reduction is released.
4240 Default is 0.125. Allowed range is from 0 to 1.
4241
4242 @item ratio
4243 Set a ratio about which the signal is reduced.
4244 Default is 2. Allowed range is from 1 to 9000.
4245
4246 @item attack
4247 Amount of milliseconds the signal has to rise above the threshold before gain
4248 reduction stops.
4249 Default is 20 milliseconds. Allowed range is from 0.01 to 9000.
4250
4251 @item release
4252 Amount of milliseconds the signal has to fall below the threshold before the
4253 reduction is increased again. Default is 250 milliseconds.
4254 Allowed range is from 0.01 to 9000.
4255
4256 @item makeup
4257 Set amount of amplification of signal after processing.
4258 Default is 1. Allowed range is from 1 to 64.
4259
4260 @item knee
4261 Curve the sharp knee around the threshold to enter gain reduction more softly.
4262 Default is 2.828427125. Allowed range is from 1 to 8.
4263
4264 @item detection
4265 Choose if exact signal should be taken for detection or an RMS like one.
4266 Default is rms. Can be peak or rms.
4267
4268 @item link
4269 Choose if the average level between all channels or the louder channel affects
4270 the reduction.
4271 Default is average. Can be average or maximum.
4272
4273 @item level_sc
4274 Set sidechain gain. Default is 1. Range is from 0.015625 to 64.
4275 @end table
4276
4277 @section silencedetect
4278
4279 Detect silence in an audio stream.
4280
4281 This filter logs a message when it detects that the input audio volume is less
4282 or equal to a noise tolerance value for a duration greater or equal to the
4283 minimum detected noise duration.
4284
4285 The printed times and duration are expressed in seconds.
4286
4287 The filter accepts the following options:
4288
4289 @table @option
4290 @item noise, n
4291 Set noise tolerance. Can be specified in dB (in case "dB" is appended to the
4292 specified value) or amplitude ratio. Default is -60dB, or 0.001.
4293
4294 @item duration, d
4295 Set silence duration until notification (default is 2 seconds).
4296
4297 @item mono, m
4298 Process each channel separately, instead of combined. By default is disabled.
4299 @end table
4300
4301 @subsection Examples
4302
4303 @itemize
4304 @item
4305 Detect 5 seconds of silence with -50dB noise tolerance:
4306 @example
4307 silencedetect=n=-50dB:d=5
4308 @end example
4309
4310 @item
4311 Complete example with @command{ffmpeg} to detect silence with 0.0001 noise
4312 tolerance in @file{silence.mp3}:
4313 @example
4314 ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null -
4315 @end example
4316 @end itemize
4317
4318 @section silenceremove
4319
4320 Remove silence from the beginning, middle or end of the audio.
4321
4322 The filter accepts the following options:
4323
4324 @table @option
4325 @item start_periods
4326 This value is used to indicate if audio should be trimmed at beginning of
4327 the audio. A value of zero indicates no silence should be trimmed from the
4328 beginning. When specifying a non-zero value, it trims audio up until it
4329 finds non-silence. Normally, when trimming silence from beginning of audio
4330 the @var{start_periods} will be @code{1} but it can be increased to higher
4331 values to trim all audio up to specific count of non-silence periods.
4332 Default value is @code{0}.
4333
4334 @item start_duration
4335 Specify the amount of time that non-silence must be detected before it stops
4336 trimming audio. By increasing the duration, bursts of noises can be treated
4337 as silence and trimmed off. Default value is @code{0}.
4338
4339 @item start_threshold
4340 This indicates what sample value should be treated as silence. For digital
4341 audio, a value of @code{0} may be fine but for audio recorded from analog,
4342 you may wish to increase the value to account for background noise.
4343 Can be specified in dB (in case "dB" is appended to the specified value)
4344 or amplitude ratio. Default value is @code{0}.
4345
4346 @item start_silence
4347 Specify max duration of silence at beginning that will be kept after
4348 trimming. Default is 0, which is equal to trimming all samples detected
4349 as silence.
4350
4351 @item start_mode
4352 Specify mode of detection of silence end in start of multi-channel audio.
4353 Can be @var{any} or @var{all}. Default is @var{any}.
4354 With @var{any}, any sample that is detected as non-silence will cause
4355 stopped trimming of silence.
4356 With @var{all}, only if all channels are detected as non-silence will cause
4357 stopped trimming of silence.
4358
4359 @item stop_periods
4360 Set the count for trimming silence from the end of audio.
4361 To remove silence from the middle of a file, specify a @var{stop_periods}
4362 that is negative. This value is then treated as a positive value and is
4363 used to indicate the effect should restart processing as specified by
4364 @var{start_periods}, making it suitable for removing periods of silence
4365 in the middle of the audio.
4366 Default value is @code{0}.
4367
4368 @item stop_duration
4369 Specify a duration of silence that must exist before audio is not copied any
4370 more. By specifying a higher duration, silence that is wanted can be left in
4371 the audio.
4372 Default value is @code{0}.
4373
4374 @item stop_threshold
4375 This is the same as @option{start_threshold} but for trimming silence from
4376 the end of audio.
4377 Can be specified in dB (in case "dB" is appended to the specified value)
4378 or amplitude ratio. Default value is @code{0}.
4379
4380 @item stop_silence
4381 Specify max duration of silence at end that will be kept after
4382 trimming. Default is 0, which is equal to trimming all samples detected
4383 as silence.
4384
4385 @item stop_mode
4386 Specify mode of detection of silence start in end of multi-channel audio.
4387 Can be @var{any} or @var{all}. Default is @var{any}.
4388 With @var{any}, any sample that is detected as non-silence will cause
4389 stopped trimming of silence.
4390 With @var{all}, only if all channels are detected as non-silence will cause
4391 stopped trimming of silence.
4392
4393 @item detection
4394 Set how is silence detected. Can be @code{rms} or @code{peak}. Second is faster
4395 and works better with digital silence which is exactly 0.
4396 Default value is @code{rms}.
4397
4398 @item window
4399 Set duration in number of seconds used to calculate size of window in number
4400 of samples for detecting silence.
4401 Default value is @code{0.02}. Allowed range is from @code{0} to @code{10}.
4402 @end table
4403
4404 @subsection Examples
4405
4406 @itemize
4407 @item
4408 The following example shows how this filter can be used to start a recording
4409 that does not contain the delay at the start which usually occurs between
4410 pressing the record button and the start of the performance:
4411 @example
4412 silenceremove=start_periods=1:start_duration=5:start_threshold=0.02
4413 @end example
4414
4415 @item
4416 Trim all silence encountered from beginning to end where there is more than 1
4417 second of silence in audio:
4418 @example
4419 silenceremove=stop_periods=-1:stop_duration=1:stop_threshold=-90dB
4420 @end example
4421 @end itemize
4422
4423 @section sofalizer
4424
4425 SOFAlizer uses head-related transfer functions (HRTFs) to create virtual
4426 loudspeakers around the user for binaural listening via headphones (audio
4427 formats up to 9 channels supported).
4428 The HRTFs are stored in SOFA files (see @url{http://www.sofacoustics.org/} for a database).
4429 SOFAlizer is developed at the Acoustics Research Institute (ARI) of the
4430 Austrian Academy of Sciences.
4431
4432 To enable compilation of this filter you need to configure FFmpeg with
4433 @code{--enable-libmysofa}.
4434
4435 The filter accepts the following options:
4436
4437 @table @option
4438 @item sofa
4439 Set the SOFA file used for rendering.
4440
4441 @item gain
4442 Set gain applied to audio. Value is in dB. Default is 0.
4443
4444 @item rotation
4445 Set rotation of virtual loudspeakers in deg. Default is 0.
4446
4447 @item elevation
4448 Set elevation of virtual speakers in deg. Default is 0.
4449
4450 @item radius
4451 Set distance in meters between loudspeakers and the listener with near-field
4452 HRTFs. Default is 1.
4453
4454 @item type
4455 Set processing type. Can be @var{time} or @var{freq}. @var{time} is
4456 processing audio in time domain which is slow.
4457 @var{freq} is processing audio in frequency domain which is fast.
4458 Default is @var{freq}.
4459
4460 @item speakers
4461 Set custom positions of virtual loudspeakers. Syntax for this option is:
4462 <CH> <AZIM> <ELEV>[|<CH> <AZIM> <ELEV>|...].
4463 Each virtual loudspeaker is described with short channel name following with
4464 azimuth and elevation in degrees.
4465 Each virtual loudspeaker description is separated by '|'.
4466 For example to override front left and front right channel positions use:
4467 'speakers=FL 45 15|FR 345 15'.
4468 Descriptions with unrecognised channel names are ignored.
4469
4470 @item lfegain
4471 Set custom gain for LFE channels. Value is in dB. Default is 0.
4472 @end table
4473
4474 @subsection Examples
4475
4476 @itemize
4477 @item
4478 Using ClubFritz6 sofa file:
4479 @example
4480 sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=1
4481 @end example
4482
4483 @item
4484 Using ClubFritz12 sofa file and bigger radius with small rotation:
4485 @example
4486 sofalizer=sofa=/path/to/ClubFritz12.sofa:type=freq:radius=2:rotation=5
4487 @end example
4488
4489 @item
4490 Similar as above but with custom speaker positions for front left, front right, back left and back right
4491 and also with custom gain:
4492 @example
4493 "sofalizer=sofa=/path/to/ClubFritz6.sofa:type=freq:radius=2:speakers=FL 45|FR 315|BL 135|BR 225:gain=28"
4494 @end example
4495 @end itemize
4496
4497 @section stereotools
4498
4499 This filter has some handy utilities to manage stereo signals, for converting
4500 M/S stereo recordings to L/R signal while having control over the parameters
4501 or spreading the stereo image of master track.
4502
4503 The filter accepts the following options:
4504
4505 @table @option
4506 @item level_in
4507 Set input level before filtering for both channels. Defaults is 1.
4508 Allowed range is from 0.015625 to 64.
4509
4510 @item level_out
4511 Set output level after filtering for both channels. Defaults is 1.
4512 Allowed range is from 0.015625 to 64.
4513
4514 @item balance_in
4515 Set input balance between both channels. Default is 0.
4516 Allowed range is from -1 to 1.
4517
4518 @item balance_out
4519 Set output balance between both channels. Default is 0.
4520 Allowed range is from -1 to 1.
4521
4522 @item softclip
4523 Enable softclipping. Results in analog distortion instead of harsh digital 0dB
4524 clipping. Disabled by default.
4525
4526 @item mutel
4527 Mute the left channel. Disabled by default.
4528
4529 @item muter
4530 Mute the right channel. Disabled by default.
4531
4532 @item phasel
4533 Change the phase of the left channel. Disabled by default.
4534
4535 @item phaser
4536 Change the phase of the right channel. Disabled by default.
4537
4538 @item mode
4539 Set stereo mode. Available values are:
4540
4541 @table @samp
4542 @item lr>lr
4543 Left/Right to Left/Right, this is default.
4544
4545 @item lr>ms
4546 Left/Right to Mid/Side.
4547
4548 @item ms>lr
4549 Mid/Side to Left/Right.
4550
4551 @item lr>ll
4552 Left/Right to Left/Left.
4553
4554 @item lr>rr
4555 Left/Right to Right/Right.
4556
4557 @item lr>l+r
4558 Left/Right to Left + Right.
4559
4560 @item lr>rl
4561 Left/Right to Right/Left.
4562
4563 @item ms>ll
4564 Mid/Side to Left/Left.
4565
4566 @item ms>rr
4567 Mid/Side to Right/Right.
4568 @end table
4569
4570 @item slev
4571 Set level of side signal. Default is 1.
4572 Allowed range is from 0.015625 to 64.
4573
4574 @item sbal
4575 Set balance of side signal. Default is 0.
4576 Allowed range is from -1 to 1.
4577
4578 @item mlev
4579 Set level of the middle signal. Default is 1.
4580 Allowed range is from 0.015625 to 64.
4581
4582 @item mpan
4583 Set middle signal pan. Default is 0. Allowed range is from -1 to 1.
4584
4585 @item base
4586 Set stereo base between mono and inversed channels. Default is 0.
4587 Allowed range is from -1 to 1.
4588
4589 @item delay
4590 Set delay in milliseconds how much to delay left from right channel and
4591 vice versa. Default is 0. Allowed range is from -20 to 20.
4592
4593 @item sclevel
4594 Set S/C level. Default is 1. Allowed range is from 1 to 100.
4595
4596 @item phase
4597 Set the stereo phase in degrees. Default is 0. Allowed range is from 0 to 360.
4598
4599 @item bmode_in, bmode_out
4600 Set balance mode for balance_in/balance_out option.
4601
4602 Can be one of the following:
4603
4604 @table @samp
4605 @item balance
4606 Classic balance mode. Attenuate one channel at time.
4607 Gain is raised up to 1.
4608
4609 @item amplitude
4610 Similar as classic mode above but gain is raised up to 2.
4611
4612 @item power
4613 Equal power distribution, from -6dB to +6dB range.
4614 @end table
4615 @end table
4616
4617 @subsection Examples
4618
4619 @itemize
4620 @item
4621 Apply karaoke like effect:
4622 @example
4623 stereotools=mlev=0.015625
4624 @end example
4625
4626 @item
4627 Convert M/S signal to L/R:
4628 @example
4629 "stereotools=mode=ms>lr"
4630 @end example
4631 @end itemize
4632
4633 @section stereowiden
4634
4635 This filter enhance the stereo effect by suppressing signal common to both
4636 channels and by delaying the signal of left into right and vice versa,
4637 thereby widening the stereo effect.
4638
4639 The filter accepts the following options:
4640
4641 @table @option
4642 @item delay
4643 Time in milliseconds of the delay of left signal into right and vice versa.
4644 Default is 20 milliseconds.
4645
4646 @item feedback
4647 Amount of gain in delayed signal into right and vice versa. Gives a delay
4648 effect of left signal in right output and vice versa which gives widening
4649 effect. Default is 0.3.
4650
4651 @item crossfeed
4652 Cross feed of left into right with inverted phase. This helps in suppressing
4653 the mono. If the value is 1 it will cancel all the signal common to both
4654 channels. Default is 0.3.
4655
4656 @item drymix
4657 Set level of input signal of original channel. Default is 0.8.
4658 @end table
4659
4660 @section superequalizer
4661 Apply 18 band equalizer.
4662
4663 The filter accepts the following options:
4664 @table @option
4665 @item 1b
4666 Set 65Hz band gain.
4667 @item 2b
4668 Set 92Hz band gain.
4669 @item 3b
4670 Set 131Hz band gain.
4671 @item 4b
4672 Set 185Hz band gain.
4673 @item 5b
4674 Set 262Hz band gain.
4675 @item 6b
4676 Set 370Hz band gain.
4677 @item 7b
4678 Set 523Hz band gain.
4679 @item 8b
4680 Set 740Hz band gain.
4681 @item 9b
4682 Set 1047Hz band gain.
4683 @item 10b
4684 Set 1480Hz band gain.
4685 @item 11b
4686 Set 2093Hz band gain.
4687 @item 12b
4688 Set 2960Hz band gain.
4689 @item 13b
4690 Set 4186Hz band gain.
4691 @item 14b
4692 Set 5920Hz band gain.
4693 @item 15b
4694 Set 8372Hz band gain.
4695 @item 16b
4696 Set 11840Hz band gain.
4697 @item 17b
4698 Set 16744Hz band gain.
4699 @item 18b
4700 Set 20000Hz band gain.
4701 @end table
4702
4703 @section surround
4704 Apply audio surround upmix filter.
4705
4706 This filter allows to produce multichannel output from audio stream.
4707
4708 The filter accepts the following options:
4709
4710 @table @option
4711 @item chl_out
4712 Set output channel layout. By default, this is @var{5.1}.
4713
4714 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
4715 for the required syntax.
4716
4717 @item chl_in
4718 Set input channel layout. By default, this is @var{stereo}.
4719
4720 See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
4721 for the required syntax.
4722
4723 @item level_in
4724 Set input volume level. By default, this is @var{1}.
4725
4726 @item level_out
4727 Set output volume level. By default, this is @var{1}.
4728
4729 @item lfe
4730 Enable LFE channel output if output channel layout has it. By default, this is enabled.
4731
4732 @item lfe_low
4733 Set LFE low cut off frequency. By default, this is @var{128} Hz.
4734
4735 @item lfe_high
4736 Set LFE high cut off frequency. By default, this is @var{256} Hz.
4737
4738 @item fc_in
4739 Set front center input volume. By default, this is @var{1}.
4740
4741 @item fc_out
4742 Set front center output volume. By default, this is @var{1}.
4743
4744 @item lfe_in
4745 Set LFE input volume. By default, this is @var{1}.
4746
4747 @item lfe_out
4748 Set LFE output volume. By default, this is @var{1}.
4749 @end table
4750
4751 @section treble, highshelf
4752
4753 Boost or cut treble (upper) frequencies of the audio using a two-pole
4754 shelving filter with a response similar to that of a standard
4755 hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
4756
4757 The filter accepts the following options:
4758
4759 @table @option
4760 @item gain, g
4761 Give the gain at whichever is the lower of ~22 kHz and the
4762 Nyquist frequency. Its useful range is about -20 (for a large cut)
4763 to +20 (for a large boost). Beware of clipping when using a positive gain.
4764
4765 @item frequency, f
4766 Set the filter's central frequency and so can be used
4767 to extend or reduce the frequency range to be boosted or cut.
4768 The default value is @code{3000} Hz.
4769
4770 @item width_type, t
4771 Set method to specify band-width of filter.
4772 @table @option
4773 @item h
4774 Hz
4775 @item q
4776 Q-Factor
4777 @item o
4778 octave
4779 @item s
4780 slope
4781 @item k
4782 kHz
4783 @end table
4784
4785 @item width, w
4786 Determine how steep is the filter's shelf transition.
4787
4788 @item channels, c
4789 Specify which channels to filter, by default all available are filtered.
4790 @end table
4791
4792 @subsection Commands
4793
4794 This filter supports the following commands:
4795 @table @option
4796 @item frequency, f
4797 Change treble frequency.
4798 Syntax for the command is : "@var{frequency}"
4799
4800 @item width_type, t
4801 Change treble width_type.
4802 Syntax for the command is : "@var{width_type}"
4803
4804 @item width, w
4805 Change treble width.
4806 Syntax for the command is : "@var{width}"
4807
4808 @item gain, g
4809 Change treble gain.
4810 Syntax for the command is : "@var{gain}"
4811 @end table
4812
4813 @section tremolo
4814
4815 Sinusoidal amplitude modulation.
4816
4817 The filter accepts the following options:
4818
4819 @table @option
4820 @item f
4821 Modulation frequency in Hertz. Modulation frequencies in the subharmonic range
4822 (20 Hz or lower) will result in a tremolo effect.
4823 This filter may also be used as a ring modulator by specifying
4824 a modulation frequency higher than 20 Hz.
4825 Range is 0.1 - 20000.0. Default value is 5.0 Hz.
4826
4827 @item d
4828 Depth of modulation as a percentage. Range is 0.0 - 1.0.
4829 Default value is 0.5.
4830 @end table
4831
4832 @section vibrato
4833
4834 Sinusoidal phase modulation.
4835
4836 The filter accepts the following options:
4837
4838 @table @option
4839 @item f
4840 Modulation frequency in Hertz.
4841 Range is 0.1 - 20000.0. Default value is 5.0 Hz.
4842
4843 @item d
4844 Depth of modulation as a percentage. Range is 0.0 - 1.0.
4845 Default value is 0.5.
4846 @end table
4847
4848 @section volume
4849
4850 Adjust the input audio volume.
4851
4852 It accepts the following parameters:
4853 @table @option
4854
4855 @item volume
4856 Set audio volume expression.
4857
4858 Output values are clipped to the maximum value.
4859
4860 The output audio volume is given by the relation:
4861 @example
4862 @var{output_volume} = @var{volume} * @var{input_volume}
4863 @end example
4864
4865 The default value for @var{volume} is "1.0".
4866
4867 @item precision
4868 This parameter represents the mathematical precision.
4869
4870 It determines which input sample formats will be allowed, which affects the
4871 precision of the volume scaling.
4872
4873 @table @option
4874 @item fixed
4875 8-bit fixed-point; this limits input sample format to U8, S16, and S32.
4876 @item float
4877 32-bit floating-point; this limits input sample format to FLT. (default)
4878 @item double
4879 64-bit floating-point; this limits input sample format to DBL.
4880 @end table
4881
4882 @item replaygain
4883 Choose the behaviour on encountering ReplayGain side data in input frames.
4884
4885 @table @option
4886 @item drop
4887 Remove ReplayGain side data, ignoring its contents (the default).
4888
4889 @item ignore
4890 Ignore ReplayGain side data, but leave it in the frame.
4891
4892 @item track
4893 Prefer the track gain, if present.
4894
4895 @item album
4896 Prefer the album gain, if present.
4897 @end table
4898
4899 @item replaygain_preamp
4900 Pre-amplification gain in dB to apply to the selected replaygain gain.
4901
4902 Default value for @var{replaygain_preamp} is 0.0.
4903
4904 @item eval
4905 Set when the volume expression is evaluated.
4906
4907 It accepts the following values:
4908 @table @samp
4909 @item once
4910 only evaluate expression once during the filter initialization, or
4911 when the @samp{volume} command is sent
4912
4913 @item frame
4914 evaluate expression for each incoming frame
4915 @end table
4916
4917 Default value is @samp{once}.
4918 @end table
4919
4920 The volume expression can contain the following parameters.
4921
4922 @table @option
4923 @item n
4924 frame number (starting at zero)
4925 @item nb_channels
4926 number of channels
4927 @item nb_consumed_samples
4928 number of samples consumed by the filter
4929 @item nb_samples
4930 number of samples in the current frame
4931 @item pos
4932 original frame position in the file
4933 @item pts
4934 frame PTS
4935 @item sample_rate
4936 sample rate
4937 @item startpts
4938 PTS at start of stream
4939 @item startt
4940 time at start of stream
4941 @item t
4942 frame time
4943 @item tb
4944 timestamp timebase
4945 @item volume
4946 last set volume value
4947 @end table
4948
4949 Note that when @option{eval} is set to @samp{once} only the
4950 @var{sample_rate} and @var{tb} variables are available, all other
4951 variables will evaluate to NAN.
4952
4953 @subsection Commands
4954
4955 This filter supports the following commands:
4956 @table @option
4957 @item volume
4958 Modify the volume expression.
4959 The command accepts the same syntax of the corresponding option.
4960
4961 If the specified expression is not valid, it is kept at its current
4962 value.
4963 @item replaygain_noclip
4964 Prevent clipping by limiting the gain applied.
4965
4966 Default value for @var{replaygain_noclip} is 1.
4967
4968 @end table
4969
4970 @subsection Examples
4971
4972 @itemize
4973 @item
4974 Halve the input audio volume:
4975 @example
4976 volume=volume=0.5
4977 volume=volume=1/2
4978 volume=volume=-6.0206dB
4979 @end example
4980
4981 In all the above example the named key for @option{volume} can be
4982 omitted, for example like in:
4983 @example
4984 volume=0.5
4985 @end example
4986
4987 @item
4988 Increase input audio power by 6 decibels using fixed-point precision:
4989 @example
4990 volume=volume=6dB:precision=fixed
4991 @end example
4992
4993 @item
4994 Fade volume after time 10 with an annihilation period of 5 seconds:
4995 @example
4996 volume='if(lt(t,10),1,max(1-(t-10)/5,0))':eval=frame
4997 @end example
4998 @end itemize
4999
5000 @section volumedetect
5001
5002 Detect the volume of the input video.
5003
5004 The filter has no parameters. The input is not modified. Statistics about
5005 the volume will be printed in the log when the input stream end is reached.
5006
5007 In particular it will show the mean volume (root mean square), maximum
5008 volume (on a per-sample basis), and the beginning of a histogram of the
5009 registered volume values (from the maximum value to a cumulated 1/1000 of
5010 the samples).
5011
5012 All volumes are in decibels relative to the maximum PCM value.
5013
5014 @subsection Examples
5015
5016 Here is an excerpt of the output:
5017 @example
5018 [Parsed_volumedetect_0 @ 0xa23120] mean_volume: -27 dB
5019 [Parsed_volumedetect_0 @ 0xa23120] max_volume: -4 dB
5020 [Parsed_volumedetect_0 @ 0xa23120] histogram_4db: 6
5021 [Parsed_volumedetect_0 @ 0xa23120] histogram_5db: 62
5022 [Parsed_volumedetect_0 @ 0xa23120] histogram_6db: 286
5023 [Parsed_volumedetect_0 @ 0xa23120] histogram_7db: 1042
5024 [Parsed_volumedetect_0 @ 0xa23120] histogram_8db: 2551
5025 [Parsed_volumedetect_0 @ 0xa23120] histogram_9db: 4609
5026 [Parsed_volumedetect_0 @ 0xa23120] histogram_10db: 8409
5027 @end example
5028
5029 It means that:
5030 @itemize
5031 @item
5032 The mean square energy is approximately -27 dB, or 10^-2.7.
5033 @item
5034 The largest sample is at -4 dB, or more precisely between -4 dB and -5 dB.
5035 @item
5036 There are 6 samples at -4 dB, 62 at -5 dB, 286 at -6 dB, etc.
5037 @end itemize
5038
5039 In other words, raising the volume by +4 dB does not cause any clipping,
5040 raising it by +5 dB causes clipping for 6 samples, etc.
5041
5042 @c man end AUDIO FILTERS
5043
5044 @chapter Audio Sources
5045 @c man begin AUDIO SOURCES
5046
5047 Below is a description of the currently available audio sources.
5048
5049 @section abuffer
5050
5051 Buffer audio frames, and make them available to the filter chain.
5052
5053 This source is mainly intended for a programmatic use, in particular
5054 through the interface defined in @file{libavfilter/asrc_abuffer.h}.
5055
5056 It accepts the following parameters:
5057 @table @option
5058
5059 @item time_base
5060 The timebase which will be used for timestamps of submitted frames. It must be
5061 either a floating-point number or in @var{numerator}/@var{denominator} form.
5062
5063 @item sample_rate
5064 The sample rate of the incoming audio buffers.
5065
5066 @item sample_fmt
5067 The sample format of the incoming audio buffers.
5068 Either a sample format name or its corresponding integer representation from
5069 the enum AVSampleFormat in @file{libavutil/samplefmt.h}
5070
5071 @item channel_layout
5072 The channel layout of the incoming audio buffers.
5073 Either a channel layout name from channel_layout_map in
5074 @file{libavutil/channel_layout.c} or its corresponding integer representation
5075 from the AV_CH_LAYOUT_* macros in @file{libavutil/channel_layout.h}
5076
5077 @item channels
5078 The number of channels of the incoming audio buffers.
5079 If both @var{channels} and @var{channel_layout} are specified, then they
5080 must be consistent.
5081
5082 @end table
5083
5084 @subsection Examples
5085
5086 @example
5087 abuffer=sample_rate=44100:sample_fmt=s16p:channel_layout=stereo
5088 @end example
5089
5090 will instruct the source to accept planar 16bit signed stereo at 44100Hz.
5091 Since the sample format with name "s16p" corresponds to the number
5092 6 and the "stereo" channel layout corresponds to the value 0x3, this is
5093 equivalent to:
5094 @example
5095 abuffer=sample_rate=44100:sample_fmt=6:channel_layout=0x3
5096 @end example
5097
5098 @section aevalsrc
5099
5100 Generate an audio signal specified by an expression.
5101
5102 This source accepts in input one or more expressions (one for each
5103 channel), which are evaluated and used to generate a corresponding
5104 audio signal.
5105