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