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