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