DOCS/man/en/af.rst

   1 Audio Filters
   2 =============
   3
   4 Audio filters allow you to modify the audio stream and its properties. The
   5 syntax is:
   6
   7 --af=<filter1[=parameter1:parameter2:...],filter2,...>
   8     Setup a chain of audio filters.
   9
  10 *NOTE*: To get a full list of available audio filters, see ``--af=help``.
  11
  12 Audio filters are managed in lists. There are a few commands to manage the
  13 filter list.
  14
  15 --af-add=<filter1[,filter2,...]>
  16     Appends the filters given as arguments to the filter list.
  17
  18 --af-pre=<filter1[,filter2,...]>
  19     Prepends the filters given as arguments to the filter list.
  20
  21 --af-del=<index1[,index2,...]>
  22     Deletes the filters at the given indexes. Index numbers start at 0,
  23     negative numbers address the end of the list (-1 is the last).
  24
  25 --af-clr
  26     Completely empties the filter list.
  27
  28 Available filters are:
  29
  30 lavrresample[=option1:option2:...]
  31     Changes the sample rate of the audio stream to an integer <srate> in Hz.
  32
  33     This filter is automatically inserted if the audio output device does not
  34     support the sample rate of the file played. It only supports the
  35     16-bit integer native-endian format.
  36
  37     srate=<srate>
  38         the output sample rate (defaut: 44100)
  39     length=<length>
  40         length of the filter with respect to the lower sampling rate (default:
  41         16)
  42     phase_shift=<count>
  43         log2 of the number of polyphase entries (..., 10->1024, 11->2048,
  44         12->4096, ...) (default: 10->1024)
  45     cutoff=<cutoff>
  46         cutoff frequency (0.0-1.0), default set depending upon filter length
  47     linear
  48         if set then filters will be linearly interpolated between polyphase
  49         entries (default: no)
  50
  51 lavcac3enc[=tospdif[:bitrate[:minchn]]]
  52     Encode multi-channel audio to AC-3 at runtime using libavcodec. Supports
  53     16-bit native-endian input format, maximum 6 channels. The output is
  54     big-endian when outputting a raw AC-3 stream, native-endian when
  55     outputting to S/PDIF. The output sample rate of this filter is same with
  56     the input sample rate. When input sample rate is 48kHz, 44.1kHz, or 32kHz,
  57     this filter directly use it. Otherwise a resampling filter is
  58     auto-inserted before this filter to make the input and output sample rate
  59     be 48kHz. You need to specify ``--channels=N`` to make the decoder decode
  60     audio into N-channel, then the filter can encode the N-channel input to
  61     AC-3.
  62
  63     <tospdif>
  64         Output raw AC-3 stream if zero or not set, output to S/PDIF for
  65         passthrough when <tospdif> is set non-zero.
  66     <bitrate>
  67         The bitrate to encode the AC-3 stream. Set it to either 384 or 384000
  68         to get 384kbits.
  69
  70         Valid values: 32, 40, 48, 56, 64, 80, 96, 112, 128,
  71         160, 192, 224, 256, 320, 384, 448, 512, 576, 640.
  72
  73         Default bitrate is based on the input channel number:
  74
  75         :1ch: 96
  76         :2ch: 192
  77         :3ch: 224
  78         :4ch: 384
  79         :5ch: 448
  80         :6ch: 448
  81
  82     <minchn>
  83         If the input channel number is less than <minchn>, the filter will
  84         detach itself (default: 5).
  85
  86 sweep[=speed]
  87     Produces a sine sweep.
  88
  89     <0.0-1.0>
  90         Sine function delta, use very low values to hear the sweep.
  91
  92 sinesuppress[=freq:decay]
  93     Remove a sine at the specified frequency. Useful to get rid of the 50/60Hz
  94     noise on low quality audio equipment. It probably only works on mono input.
  95
  96     <freq>
  97         The frequency of the sine which should be removed (in Hz) (default:
  98         50)
  99     <decay>
 100         Controls the adaptivity (a larger value will make the filter adapt to
 101         amplitude and phase changes quicker, a smaller value will make the
 102         adaptation slower) (default: 0.0001). Reasonable values are around
 103         0.001.
 104
 105 bs2b[=option1:option2:...]
 106     Bauer stereophonic to binaural transformation using ``libbs2b``. Improves
 107     the headphone listening experience by making the sound similar to that
 108     from loudspeakers, allowing each ear to hear both channels and taking into
 109     account the distance difference and the head shadowing effect. It is
 110     applicable only to 2 channel audio.
 111
 112     fcut=<300-1000>
 113         Set cut frequency in Hz.
 114     feed=<10-150>
 115         Set feed level for low frequencies in 0.1*dB.
 116     profile=<value>
 117         Several profiles are available for convenience:
 118
 119         :default: will be used if nothing else was specified (fcut=700,
 120                   feed=45)
 121         :cmoy:    Chu Moy circuit implementation (fcut=700, feed=60)
 122         :jmeier:  Jan Meier circuit implementation (fcut=650, feed=95)
 123
 124     If fcut or feed options are specified together with a profile, they will
 125     be applied on top of the selected profile.
 126
 127 hrtf[=flag]
 128     Head-related transfer function: Converts multichannel audio to 2 channel
 129     output for headphones, preserving the spatiality of the sound.
 130
 131     ==== ===================================
 132     Flag Meaning
 133     ==== ===================================
 134     m    matrix decoding of the rear channel
 135     s    2-channel matrix decoding
 136     0    no matrix decoding (default)
 137     ==== ===================================
 138
 139 equalizer=[g1:g2:g3:...:g10]
 140     10 octave band graphic equalizer, implemented using 10 IIR band pass
 141     filters. This means that it works regardless of what type of audio is
 142     being played back. The center frequencies for the 10 bands are:
 143
 144     === ==========
 145     No. frequency
 146     === ==========
 147     0    31.25  Hz
 148     1    62.50  Hz
 149     2   125.00  Hz
 150     3   250.00  Hz
 151     4   500.00  Hz
 152     5     1.00 kHz
 153     6     2.00 kHz
 154     7     4.00 kHz
 155     8     8.00 kHz
 156     9    16.00 kHz
 157     === ==========
 158
 159     If the sample rate of the sound being played is lower than the center
 160     frequency for a frequency band, then that band will be disabled. A known
 161     bug with this filter is that the characteristics for the uppermost band
 162     are not completely symmetric if the sample rate is close to the center
 163     frequency of that band. This problem can be worked around by upsampling
 164     the sound using the resample filter before it reaches this filter.
 165
 166     <g1>:<g2>:<g3>:...:<g10>
 167         floating point numbers representing the gain in dB for each frequency
 168         band (-12-12)
 169
 170     *EXAMPLE*:
 171
 172     ``mplayer --af=equalizer=11:11:10:5:0:-12:0:5:12:12 media.avi``
 173         Would amplify the sound in the upper and lower frequency region while
 174         canceling it almost completely around 1kHz.
 175
 176 channels=nch[:nr:from1:to1:from2:to2:from3:to3:...]
 177     Can be used for adding, removing, routing and copying audio channels. If
 178     only <nch> is given the default routing is used, it works as follows: If
 179     the number of output channels is bigger than the number of input channels
 180     empty channels are inserted (except mixing from mono to stereo, then the
 181     mono channel is repeated in both of the output channels). If the number of
 182     output channels is smaller than the number of input channels the exceeding
 183     channels are truncated.
 184
 185     <nch>
 186         number of output channels (1-8)
 187     <nr>
 188         number of routes (1-8)
 189     <from1:to1:from2:to2:from3:to3:...>
 190         Pairs of numbers between 0 and 7 that define where to route each
 191         channel.
 192
 193     *EXAMPLE*:
 194
 195     ``mplayer --af=channels=4:4:0:1:1:0:2:2:3:3 media.avi``
 196         Would change the number of channels to 4 and set up 4 routes that swap
 197         channel 0 and channel 1 and leave channel 2 and 3 intact. Observe that
 198         if media containing two channels was played back, channels 2 and 3
 199         would contain silence but 0 and 1 would still be swapped.
 200
 201     ``mplayer --af=channels=6:4:0:0:0:1:0:2:0:3 media.avi``
 202         Would change the number of channels to 6 and set up 4 routes that copy
 203         channel 0 to channels 0 to 3. Channel 4 and 5 will contain silence.
 204
 205 format[=format]
 206     Convert between different sample formats. Automatically enabled when
 207     needed by the sound card or another filter. See also ``--format``.
 208
 209     <format>
 210         Sets the desired format. The general form is 'sbe', where 's' denotes
 211         the sign (either 's' for signed or 'u' for unsigned), 'b' denotes the
 212         number of bits per sample (16, 24 or 32) and 'e' denotes the
 213         endianness ('le' means little-endian, 'be' big-endian and 'ne' the
 214         endianness of the computer MPlayer is running on). Valid values
 215         (amongst others) are: 's16le', 'u32be' and 'u24ne'. Exceptions to this
 216         rule that are also valid format specifiers: u8, s8, floatle, floatbe,
 217         floatne, mulaw, alaw, mpeg2, ac3 and imaadpcm.
 218
 219 volume[=v[:sc]]
 220     Implements software volume control. Use this filter with caution since it
 221     can reduce the signal to noise ratio of the sound. In most cases it is
 222     best to set the level for the PCM sound to max, leave this filter out and
 223     control the output level to your speakers with the master volume control
 224     of the mixer. In case your sound card has a digital PCM mixer instead of
 225     an analog one, and you hear distortion, use the MASTER mixer instead. If
 226     there is an external amplifier connected to the computer (this is almost
 227     always the case), the noise level can be minimized by adjusting the master
 228     level and the volume knob on the amplifier until the hissing noise in the
 229     background is gone.
 230
 231     This filter has a second feature: It measures the overall maximum sound
 232     level and prints out that level when MPlayer exits. This feature currently
 233     only works with floating-point data, use e.g. ``--af-adv=force=5``, or use
 234     ``--af=stats``.
 235
 236     *NOTE*: This filter is not reentrant and can therefore only be enabled
 237     once for every audio stream.
 238
 239     <v>
 240         Sets the desired gain in dB for all channels in the stream from -200dB
 241         to +60dB, where -200dB mutes the sound completely and +60dB equals a
 242         gain of 1000 (default: 0).
 243     <sc>
 244         Turns soft clipping on (1) or off (0). Soft-clipping can make the
 245         sound more smooth if very high volume levels are used. Enable this
 246         option if the dynamic range of the loudspeakers is very low.
 247
 248         *WARNING*: This feature creates distortion and should be considered a
 249         last resort.
 250
 251     *EXAMPLE*:
 252
 253     ``mplayer --af=volume=10.1:0 media.avi``
 254         Would amplify the sound by 10.1dB and hard-clip if the sound level is
 255         too high.
 256
 257 pan=n[:L00:L01:L02:...L10:L11:L12:...Ln0:Ln1:Ln2:...]
 258     Mixes channels arbitrarily. Basically a combination of the volume and the
 259     channels filter that can be used to down-mix many channels to only a few,
 260     e.g. stereo to mono or vary the "width" of the center speaker in a
 261     surround sound system. This filter is hard to use, and will require some
 262     tinkering before the desired result is obtained. The number of options for
 263     this filter depends on the number of output channels. An example how to
 264     downmix a six-channel file to two channels with this filter can be found
 265     in the examples section near the end.
 266
 267     <n>
 268         number of output channels (1-8)
 269     <Lij>
 270         How much of input channel i is mixed into output channel j (0-1). So
 271         in principle you first have n numbers saying what to do with the first
 272         input channel, then n numbers that act on the second input channel
 273         etc. If you do not specify any numbers for some input channels, 0 is
 274         assumed.
 275
 276     *EXAMPLE*:
 277
 278     ``mplayer --af=pan=1:0.5:0.5 media.avi``
 279         Would down-mix from stereo to mono.
 280
 281     ``mplayer --af=pan=3:1:0:0.5:0:1:0.5 media.avi``
 282         Would give 3 channel output leaving channels 0 and 1 intact, and mix
 283         channels 0 and 1 into output channel 2 (which could be sent to a
 284         subwoofer for example).
 285
 286 sub[=fc:ch]
 287     Adds a subwoofer channel to the audio stream. The audio data used for
 288     creating the subwoofer channel is an average of the sound in channel 0 and
 289     channel 1. The resulting sound is then low-pass filtered by a 4th order
 290     Butterworth filter with a default cutoff frequency of 60Hz and added to a
 291     separate channel in the audio stream.
 292
 293     *Warning*: Disable this filter when you are playing DVDs with Dolby
 294     Digital 5.1 sound, otherwise this filter will disrupt the sound to the
 295     subwoofer.
 296
 297     <fc>
 298         cutoff frequency in Hz for the low-pass filter (20Hz to 300Hz)
 299         (default: 60Hz) For the best result try setting the cutoff frequency
 300         as low as possible. This will improve the stereo or surround sound
 301         experience.
 302     <ch>
 303         Determines the channel number in which to insert the sub-channel
 304         audio. Channel number can be between 0 and 7 (default: 5). Observe
 305         that the number of channels will automatically be increased to <ch> if
 306         necessary.
 307
 308     *EXAMPLE*:
 309
 310     ``mplayer --af=sub=100:4 --channels=5 media.avi``
 311         Would add a sub-woofer channel with a cutoff frequency of 100Hz to
 312         output channel 4.
 313
 314 center
 315     Creates a center channel from the front channels. May currently be low
 316     quality as it does not implement a high-pass filter for proper extraction
 317     yet, but averages and halves the channels instead.
 318
 319     <ch>
 320         Determines the channel number in which to insert the center channel.
 321         Channel number can be between 0 and 7 (default: 5). Observe that the
 322         number of channels will automatically be increased to <ch> if
 323         necessary.
 324
 325 surround[=delay]
 326     Decoder for matrix encoded surround sound like Dolby Surround. Many files
 327     with 2 channel audio actually contain matrixed surround sound. Requires a
 328     sound card supporting at least 4 channels.
 329
 330     <delay>
 331         delay time in ms for the rear speakers (0 to 1000) (default: 20) This
 332         delay should be set as follows: If d1 is the distance from the
 333         listening position to the front speakers and d2 is the distance from
 334         the listening position to the rear speakers, then the delay should be
 335         set to 15ms if d1 <= d2 and to 15 + 5*(d1-d2) if d1 > d2.
 336
 337     *EXAMPLE*:
 338
 339     ``mplayer --af=surround=15 --channels=4 media.avi``
 340         Would add surround sound decoding with 15ms delay for the sound to the
 341         rear speakers.
 342
 343 delay[=ch1:ch2:...]
 344     Delays the sound to the loudspeakers such that the sound from the
 345     different channels arrives at the listening position simultaneously. It is
 346     only useful if you have more than 2 loudspeakers.
 347
 348     ch1,ch2,...
 349         The delay in ms that should be imposed on each channel (floating point
 350         number between 0 and 1000).
 351
 352     To calculate the required delay for the different channels do as follows:
 353
 354     1. Measure the distance to the loudspeakers in meters in relation to your
 355        listening position, giving you the distances s1 to s5 (for a 5.1
 356        system). There is no point in compensating for the subwoofer (you will
 357        not hear the difference anyway).
 358
 359     2. Subtract the distances s1 to s5 from the maximum distance, i.e.
 360        ``s[i] = max(s) - s[i]; i = 1...5``.
 361
 362     3. Calculate the required delays in ms as ``d[i] = 1000*s[i]/342; i =
 363        1...5``.
 364
 365     *EXAMPLE*:
 366
 367     ``mplayer --af=delay=10.5:10.5:0:0:7:0 media.avi``
 368         Would delay front left and right by 10.5ms, the two rear channels and
 369         the sub by 0ms and the center channel by 7ms.
 370
 371 export[=mmapped_file[:nsamples]]
 372     Exports the incoming signal to other processes using memory mapping
 373     (``mmap()``). Memory mapped areas contain a header:
 374
 375     | int nch                      /\* number of channels \*/
 376     | int size                     /\* buffer size \*/
 377     | unsigned long long counter   /\* Used to keep sync, updated every time new data is exported. \*/
 378
 379     The rest is payload (non-interleaved) 16 bit data.
 380
 381     <mmapped_file>
 382         file to map data to (default: ``~/.mplayer/mplayer-af_export``)
 383     <nsamples>
 384         number of samples per channel (default: 512)
 385
 386     *EXAMPLE*:
 387
 388     ``mplayer --af=export=/tmp/mplayer-af_export:1024 media.avi``
 389         Would export 1024 samples per channel to ``/tmp/mplayer-af_export``.
 390
 391 extrastereo[=mul]
 392     (Linearly) increases the difference between left and right channels which
 393     adds some sort of "live" effect to playback.
 394
 395     <mul>
 396         Sets the difference coefficient (default: 2.5). 0.0 means mono sound
 397         (average of both channels), with 1.0 sound will be unchanged, with
 398         -1.0 left and right channels will be swapped.
 399
 400 volnorm[=method:target]
 401     Maximizes the volume without distorting the sound.
 402
 403     <method>
 404         Sets the used method.
 405
 406         1
 407             Use a single sample to smooth the variations via the standard
 408             weighted mean over past samples (default).
 409         2
 410             Use several samples to smooth the variations via the standard
 411             weighted mean over past samples.
 412
 413     <target>
 414         Sets the target amplitude as a fraction of the maximum for the sample
 415         type (default: 0.25).
 416
 417 ladspa=file:label[:controls...]
 418     Load a LADSPA (Linux Audio Developer's Simple Plugin API) plugin. This
 419     filter is reentrant, so multiple LADSPA plugins can be used at once.
 420
 421     <file>
 422         Specifies the LADSPA plugin library file. If ``LADSPA_PATH`` is set,
 423         it searches for the specified file. If it is not set, you must supply
 424         a fully specified pathname.
 425     <label>
 426         Specifies the filter within the library. Some libraries contain only
 427         one filter, but others contain many of them. Entering 'help' here,
 428         will list all available filters within the specified library, which
 429         eliminates the use of 'listplugins' from the LADSPA SDK.
 430     <controls>
 431         Controls are zero or more floating point values that determine the
 432         behavior of the loaded plugin (for example delay, threshold or gain).
 433         In verbose mode (add ``-v`` to the MPlayer command line), all
 434         available controls and their valid ranges are printed. This eliminates
 435         the use of 'analyseplugin' from the LADSPA SDK.
 436
 437 comp
 438     Compressor/expander filter usable for microphone input. Prevents artifacts
 439     on very loud sound and raises the volume on very low sound. This filter is
 440     untested, maybe even unusable.
 441
 442 gate
 443     Noise gate filter similar to the comp audio filter. This filter is
 444     untested, maybe even unusable.
 445
 446 karaoke
 447     Simple voice removal filter exploiting the fact that voice is usually
 448     recorded with mono gear and later 'center' mixed onto the final audio
 449     stream. Beware that this filter will turn your signal into mono. Works
 450     well for 2 channel tracks; do not bother trying it on anything but 2
 451     channel stereo.
 452
 453 scaletempo[=option1:option2:...]
 454     Scales audio tempo without altering pitch, optionally synced to playback
 455     speed (default).
 456
 457     This works by playing 'stride' ms of audio at normal speed then consuming
 458     'stride*scale' ms of input audio. It pieces the strides together by
 459     blending 'overlap'% of stride with audio following the previous stride. It
 460     optionally performs a short statistical analysis on the next 'search' ms
 461     of audio to determine the best overlap position.
 462
 463     scale=<amount>
 464         Nominal amount to scale tempo. Scales this amount in addition to
 465         speed. (default: 1.0)
 466     stride=<amount>
 467         Length in milliseconds to output each stride. Too high of value will
 468         cause noticable skips at high scale amounts and an echo at low scale
 469         amounts. Very low values will alter pitch. Increasing improves
 470         performance. (default: 60)
 471     overlap=<percent>
 472         Percentage of stride to overlap. Decreasing improves performance.
 473         (default: .20)
 474     search=<amount>
 475         Length in milliseconds to search for best overlap position. Decreasing
 476         improves performance greatly. On slow systems, you will probably want
 477         to set this very low. (default: 14)
 478     speed=<tempo|pitch|both|none>
 479         Set response to speed change.
 480
 481         tempo
 482              Scale tempo in sync with speed (default).
 483         pitch
 484              Reverses effect of filter. Scales pitch without altering tempo.
 485              Add ``[ speed_mult 0.9438743126816935`` and ``] speed_mult
 486              1.059463094352953`` to your ``input.conf`` to step by musical
 487              semi-tones.
 488
 489              *WARNING*: Loses sync with video.
 490         both
 491             Scale both tempo and pitch.
 492         none
 493             Ignore speed changes.
 494
 495     *EXAMPLE*:
 496
 497     ``mplayer --af=scaletempo --speed=1.2 media.ogg``
 498         Would playback media at 1.2x normal speed, with audio at normal pitch.
 499         Changing playback speed, would change audio tempo to match.
 500
 501     ``mplayer --af=scaletempo=scale=1.2:speed=none --speed=1.2 media.ogg``
 502         Would playback media at 1.2x normal speed, with audio at normal pitch,
 503         but changing playback speed has no effect on audio tempo.
 504
 505     ``mplayer --af=scaletempo=stride=30:overlap=.50:search=10 media.ogg``
 506         Would tweak the quality and performace parameters.
 507
 508     ``mplayer --af=format=floatne,scaletempo media.ogg``
 509         Would make scaletempo use float code. Maybe faster on some platforms.
 510
 511     ``mplayer --af=scaletempo=scale=1.2:speed=pitch audio.ogg``
 512         Would playback audio file at 1.2x normal speed, with audio at normal
 513         pitch. Changing playback speed, would change pitch, leaving audio
 514         tempo at 1.2x.
 515
 516 stats
 517     Collects and prints statistics about the audio stream, especially the
 518     volume. These statistics are especially intended to help adjusting the
 519     volume while avoiding clipping. The volumes are printed in dB and
 520     compatible with the volume audio filter.