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