Move audio filter descriptions to the man page.

git-svn-id: svn://svn.mplayerhq.hu/mplayer/trunk@14788 b3059339-0415-0410-9bf9-f77b7e298cf2

2 files changed, 299 insertions, 735 deletions

diff --git a/DOCS/man/en/mplayer.1 b/DOCS/man/en/mplayer.1
index 778332bedf..de422906b7 100644
--- a/DOCS/man/en/mplayer.1
+++ b/DOCS/man/en/mplayer.1
@@ -3507,15 +3507,57 @@ To get a full list of available audio filters, see \-af help.
 Available filters are:
 .
 .TP
-.B resample[=srate[:sloppy][:type]]
-Changes the sample rate of the audio stream to an integer srate in Hz.
+.B resample[=srate[:sloppy[:type]]]
+Changes the sample rate of the audio stream.
+Can be used if you have a fixed frequency sound card or if you are
+stuck with an old sound card that is only capable of max 44.1kHz.
+This filter is automatically enabled if necessary.
 It only supports the 16-bit little-endian format.
+.br
+.I NOTE:
 With MEncoder, you need to also use \-srate <srate>.
+.PD 0
+.RSs
+.IPs <srate>
+output sample frequency in Hz.
+The valid range for this parameter is 8000 to 192000.
+If the input and output sample frequency are the same or if this
+parameter is omitted the filter is automatically unloaded.
+A high sample frequency normally improves the audio quality,
+especially when used in combination with other filters.
+.IPs <sloppy>
+Allow (1) or disallow (0) the output frequency to differ slightly
+from the frequency given by <srate> (default: 1).
+Can be used if the startup of the playback is extremely slow.
+.IPs <type>
+Selects which resampling method to use.
+.RSss
+0: linear interpolation (fast, poor quality especially when upsampling)
+.br
+1: polyphase filterbank and integer processing
+.br
+2: polyphase filterbank and floating point processing (slow, best quality)
+.REss
+.PD 1
+.RE
+.sp 1
+.RS
+.I EXAMPLE:
+.RE
+.PD 0
+.RSs
+.IPs "mplayer -af resample=44100:0:0"
+would set the output frequency of the resample filter to 44100Hz using
+exact output frequency scaling and linear interpolation.
+.RE
+.PD 1
 .
 .TP
 .B lavcresample[=srate[:length[:linear[:count[:cutoff]]]]]
-Changes the sample rate of the audio stream to an integer srate in Hz.
+Changes the sample rate of the audio stream to an integer <srate> in Hz.
 It only supports the 16-bit little-endian format.
+.br
+.I NOTE:
 With MEncoder, you need to also use \-srate <srate>.
 .PD 0
 .RSs
@@ -3544,17 +3586,93 @@ Head-related transfer function: Converts multichannel audio to
 2 channel output for headphones, preserving the spatiality of the sound.
 .
 .TP
-.B channels[=nch]
-Change the number of channels to <nch> output channels.
-If the number of output channels is bigger than the number of input channels
-empty channels are inserted (except when mixing from mono to stereo, then
-the mono channel is repeated in both of the output channels).
-If the number of output channels is smaller than the number of input channels
-the exceeding channels are truncated.
+.B equalizer=[g1:g2:g3:...:g10]
+10 octave band graphic equalizer, implemented using 10 IIR band pass filters.
+This means that it works regardless of what type of audio is being played back.
+The center frequencies for the 10 bands are:
+.sp 1
+.PD 0
+.RS
+.IPs "No. frequency"
+.IPs "0    31.25 Hz"
+.IPs "1    62.50 Hz"
+.IPs "2   125.00 Hz"
+.IPs "3   250.00 Hz"
+.IPs "4   500.00 Hz"
+.IPs "5    1.00 kHz"
+.IPs "6    2.00 kHz"
+.IPs "7    4.00 kHz"
+.IPs "8    8.00 kHz"
+.IPs "9   16.00 kHz"
+.RE
+.PD 1
+.sp 1
+.RS
+If the sample rate of the sound being played is lower than the center
+frequency for a frequency band, then that band will be disabled.
+A known bug with this filter is that the characteristics for the
+uppermost band are not completely symmetric if the sample
+rate is close to the center frequency of that band.
+This problem can be worked around by upsampling the sound
+using the resample filter before it reaches this filter.
+.RE
+.PD 0
+.RSs
+.IPs <g1>:<g2>:<g3>:...:<g10>
+floating point numbers representing the gain in dB
+for each frequency band (-12\-12)
+.RE
+.sp 1
+.RS
+.I EXAMPLE:
+.RE
+.RSs
+.IPs "mplayer \-af equalizer=11:11:10:5:0:-12:0:5:12:12 media.avi"
+Would amplify the sound in the upper and lower frequency region
+while canceling it almost completely around 1kHz.
+.RE
+.PD 1
+.
+.TP
+.B channels=nch[:nr:from1:to1:from2:to2:from3:to3:...]
+Can be used for adding, removing, routing and copying audio channels.
+If only <nch> is given the default routing is used, it works as
+follows: If the number of output channels is bigger than the number of
+input channels empty channels are inserted (except mixing from mono to
+stereo, then the mono channel is repeated in both of the output
+channels).
+If the number of output channels is smaller than the number
+of input channels the exceeding channels are truncated.
+.PD 0
+.RSs
+.IPs <nch>
+number of output channels (1\-6)
+.IPs <nr>\ 
+number of routes (1\-6)
+.IPs <from1:to1:from2:to2:from3:to3:...>
+Pairs of numbers between 0 and 5 that define where to route each channel.
+.RE
+.sp 1
+.RS
+.I EXAMPLE:
+.RE
+.RSs
+.IPs "mplayer -af channels=4:4:0:1:1:0:2:2:3:3 media.avi"
+Would change the number of channels to 4 and set up 4 routes that
+swap channel 0 and channel 1 and leave channel 2 and 3 intact.
+Observe that if media containing two channels was played back, channels
+2 and 3 would contain silence but 0 and 1 would still be swapped.
+.IPs "mplayer -af channels=6:4:0:0:0:1:0:2:0:3 media.avi"
+Would change the number of channels to 6 and set up 4 routes
+that copy channel 0 to channels 0 to 3.
+Channel 4 and 5 will contain silence.
+.RE
+.PD 1
 .
 .TP
 .B format[=format]
-Change the current sample format.
+Convert between different sample formats.
+Automatically enabled when needed by the sound card or another filter.
 .PD 0
 .RSs
 .IPs <format>
@@ -3564,72 +3682,207 @@ or 'u' for unsigned), 'b' denotes the number of bits per sample (16, 24 or 32)
 and 'e' denotes the endianness ('le' means little-endian, 'be' big-endian
 and 'ne' the endianness of the computer MPlayer is running on).
 Valid values (amongst others) are: 's16le', 'u32be' and 'u24ne'.
-Exceptions to this rule are: u8, s8, floatle, floatbe, floatne, mulaw, alaw,
-mpeg2, ac3 and imaadpcm.
+Exceptions to this rule that are also valid format specifiers: u8, s8,
+floatle, floatbe, floatne, mulaw, alaw, mpeg2, ac3 and imaadpcm.
 .RE
 .PD 1
 .
 .TP
-.B volume[=v:sc]
-Select the output volume level.
-This filter is not reentrant and can therefore only be enabled once for every
-audio stream.
+.B volume[=v[:sc]]
+Implements software volume control.
+Use this filter with caution since it can reduce the signal
+to noise ratio of the sound.
+In most cases it is best to set the level for the PCM sound to max,
+leave this filter out and control the output level to your
+speakers with the master volume control of the mixer.
+In case your sound card has a digital PCM mixer instead of an analog
+one, and you hear distortion, use the MASTER mixer instead.
+If there is an external amplifier connected to the computer (this
+is almost always the case), the noise level can be minimized by
+adjusting the master level and the volume knob on the amplifier
+until the hissing noise in the background is gone.
+.br
+This filter has a second feature: It measures the overall maximum
+sound level and prints out that level when MPlayer exits.
+This volume estimate can be used for setting the sound level in
+MEncoder such that the maximum dynamic range is utilized.
+.br
+.I NOTE:
+This filter is not reentrant and can therefore only be enabled
+once for every audio stream.
 .PD 0
 .RSs
 .IPs <v>\ \ 
 Sets the desired gain in dB for all channels in the stream
-from -200dB to +60dB (where -200dB mutes the sound
-completely and +60dB equals a gain of 1000).
+from -200dB to +60dB, where -200dB mutes the sound
+completely and +60dB equals a gain of 1000 (default: 0).
 .IPs <sc>\ 
-Enable soft clipping.
+Turns soft clipping on (1) or off (0).
+Soft-clipping can make the sound more smooth if very
+high volume levels are used.
+Enable this option if the dynamic range of the
+loudspeakers is very low.
+.br
+.I WARNING:
+This feature creates distortion and should be considered a last resort.
+.RE
+.sp 1
+.RS
+.I EXAMPLE:
+.RE
+.RSs
+.IPs "mplayer -af volume=10.1:0 media.avi"
+would amplify the sound by 10.1dB and hard-clip if the
+sound level is too high.
 .RE
 .PD 1
 .
 .TP
-.B pan[=n:l01:l02:...l10:l11:l12:...ln0:ln1:ln2:...]
-Mixes channels arbitrarily, see DOCS/\:HTML/\:en/\:audio.html for details.
-An example how to downmix a six-channel file to two channels with this
-filter can be found in the examples section near the end of the man page.
+.B pan=n[:l01:l02:...l10:l11:l12:...ln0:ln1:ln2:...]
+Mixes channels arbitrarily.
+Basically a combination of the volume and the channels filter
+that can be used to down-mix many channels to only a few,
+e.g.\& stereo to mono or vary the "width" of the center
+speaker in a surround sound system.
+This filter is hard to use, and will require some tinkering
+before the desired result is obtained.
+The number of options for this filter depends on
+the number of output channels.
+An example how to downmix a six-channel file to two channels with
+this filter can be found in the examples section near the end.
 .PD 0
 .RSs
 .IPs <n>\ \ 
 number of input channels (1\-6)
 .IPs <lij>
-How much of input channel j is mixed into output channel i.
+How much of input channel j is mixed into output channel i (0\-1).
+.RE
+.sp 1
+.RS
+.I EXAMPLE:
+.RE
+.RSs
+.IPs "mplayer -af pan=1:0.5:0.5 -channels 1 media.avi"
+Would down-mix from stereo to mono.
+.IPs "mplayer -af pan=3:1:0:1:0.5:0.5 -channels 3 media.avi"
+Would give 3 channel output leaving channels 0 and 1 intact,
+and mix channels 0 and 1 into output channel 2 (which could
+be sent to a subwoofer for example).
 .RE
 .PD 1
 .
 .TP
 .B sub[=fc:ch]
-Add subwoofer channel.
+Adds a subwoofer channel to the audio stream.
+The audio data used for creating the subwoofer channel is
+an average of the sound in channel 0 and channel 1.
+The resulting sound is then low-pass filtered by a 4th order
+Butterworth filter with a default cutoff frequency of 60Hz
+and added to a separate channel in the audio stream.
+.br
+.I Warning:
+Disable this filter when you are playing DVDs with Dolby
+Digital 5.1 sound, otherwise this filter will disrupt
+the sound to the subwoofer.
 .PD 0
 .RSs
 .IPs <fc>\ 
-cutoff frequency for low-pass filter (20Hz to 300Hz) (default: 60Hz)
+cutoff frequency in Hz for the low-pass filter (20Hz to 300Hz) (default: 60Hz)
+For the best result try setting the cutoff frequency as low as possible.
+This will improve the stereo or surround sound experience.
 .IPs <ch>\ 
-channel number for the sub-channel
+Determines the channel number in which to insert the sub-channel audio.
+Channel number can be between 0 and 5 (default: 5).
+Observe that the number of channels will automatically
+be increased to <ch> if necessary.
+.RE
+.sp 1
+.RS
+.I EXAMPLE:
+.RE
+.RSs
+.IPs "mplayer -af sub=100:4 -channels 5 media.avi"
+would add a sub-woofer channel with a cutoff frequency of
+100Hz to output channel 4.
 .RE
 .PD 1
 .
 .TP
 .B surround[=delay]
-Decoder for matrix encoded surround sound, works on many 2 channel files.
+Decoder for matrix encoded surround sound like Dolby Surround.
+Many files with 2 channel audio actually contain matrixed surround sound.
+Requires a sound card supporting at least 4 channels.
 .PD 0
 .RSs
 .IPs <delay>
 delay time in ms for the rear speakers (0 to 1000) (default: 20)
+This delay should be set as follows: If d1 is the distance
+from the listening position to the front speakers and d2 is the distance
+from the listening position to the rear speakers, then the delay d should
+be set to 15ms if d1 <= d2 and to 15 + 5*(d1-d2) if d1 > d2.
+.RE
+.sp 1
+.RS
+.I EXAMPLE:
+.RE
+.RSs
+.IPs "mplayer \-af surround=15 \-channels 4 media.avi"
+Would add surround sound decoding with 15ms delay for the sound to the
+rear speakers.
 .RE
 .PD 1
 .
 .TP
 .B delay[=ch1:ch2:...]
-Delays the sound output.
-Specify the delay separately for each channel in milliseconds (floating point
-number between 0 and 1000).
+Delays the sound to the loudspeakers such that the sound from the
+different channels arrives at the listening position simultaneously.
+It is only useful if you have more than 2 loudspeakers.
+.PD 0
+.RSs
+.IPs ch1,ch2,...
+The delay in ms that should be imposed on each channel
+(floating point number between 0 and 1000).
+.RE
+.PD 1
+.sp 1
+.RS
+To calculate the required delay for the different channels do as follows:
+.IP 1. 3
+Measure the distance to the loudspeakers in meters in relation
+to your listening position, giving you the distances s1 to s5
+(for a 5.1 system). There is no point in compensating for the
+subwoofer (you will not hear the difference anyway).
+.IP 2. 3
+Subtract the distances s1 to s5 from the maximum distance,
+i.e.\& s[i] = max(s) - s[i]; i = 1...5.
+.IP 3.
+Calculate the required delays in ms as d[i] = 1000*s[i]/342; i = 1...5.
+.RE
+.PD 0
+.sp 1
+.RS
+.I EXAMPLE:
+.RE
+.RSs
+.IPs "mplayer \-af delay=10.5:10.5:0:0:7:0 media.avi"
+Would delay front left and right by 10.5ms, the two rear channels
+and the sub by 0ms and the center channel by 7ms.
+.RE
+.PD 1
 .
 .TP
 .B export[=mmapped_file[:nsamples]]
 Exports the incoming signal to other processes using memory mapping (mmap()).
+Memory mapped areas contain a header:
+.sp 1
+.nf
+int nch                      /*number of channels*/
+int size                     /*buffer size*/
+unsigned long long counter   /*Used to keep sync, updated every
+                               time new data is exported.*/
+.fi
+.sp 1
+The rest is payload (non-interleaved) 16 bit data.
 .PD 0
 .RSs
 .IPs <mmapped_file>
@@ -3637,16 +3890,26 @@ file to map data to (default: ~/.mplayer/\:mplayer-af_export)
 .IPs <nsamples>
 number of samples per channel (default: 512)
 .RE
+.sp 1
+.RS
+.I EXAMPLE:
+.RE
+.RSs
+.IPs "mplayer \-af export=/tmp/mplayer-af_export:1024 media.avi"
+Would export 1024 samples per channel to '/tmp/mplayer-af_export'.
+.RE
 .PD 1
 .
 .TP
 .B extrastereo[=mul]
-Increases the difference between left and right channels to add some
-sort of "live" effect to playback.
+(Linearly) increases the difference between left and right channels
+which adds some sort of "live" effect to playback.
 .PD 0
 .RSs
 .IPs <mul>
-difference coefficient (default: 2.5)
+Sets the difference coefficient (default: 2.5).
+0.0 means mono sound (average of both channels), with 1.0 sound will be
+unchanged, with -1.0 left and right channels will be swapped.
 .RE
 .PD 1
 .
@@ -3703,7 +3966,7 @@ from the upper left corner of the bigger image.
 .I NOTE:
 To get a full list of available video filters, see \-vf help.
 .sp 1
-Filters are managed in lists.
+Video filters are managed in lists.
 There are a few commands to manage the filter list.
 .
 .TP
diff --git a/DOCS/xml/en/audio.xml b/DOCS/xml/en/audio.xml
index 2dab6d4bb8..2edc83cff0 100644
--- a/DOCS/xml/en/audio.xml
+++ b/DOCS/xml/en/audio.xml
@@ -55,703 +55,4 @@ DEMUXER: Too many (945 in 8390980 bytes) video packets in the buffer!<!--
 </para>
 </sect2>
 
-
-</sect1>
-
-<sect1 id="af">
-<title>Audio filters</title>
-<para>
-  Audio filters allow changing the properties of the audio data before the
-  sound reaches the sound card. The activation and deactivation of the filters
-  is normally automated but can be overridden. The filters are activated when
-  the properties of the audio data differ from those required by the sound card
-  and deactivated if unnecessary. The <option>-af filter1,filter2,...</option>
-  option is used to override the automatic activation of filters or to insert
-  filters that are not automatically inserted. The filters will be executed as
-  they appear in the comma separated list.
-</para>
-
-<para>
-Example:
-<screen>mplayer -af resample,pan <replaceable>movie.avi</replaceable></screen>
-would run the sound through the resampling filter followed by the pan filter.
-Observe that the list must not contain any spaces, else it will fail.
-</para>
-
-<para>
-The filters often have options that change their behavior. These options
-are explained in detail in the sections below. A filter will execute using
-default settings if its options are omitted. Here is an example of how to use
-filters in combination with filter specific options:
-<screen>mplayer -af resample=11025,pan=1:0.5:0.5 -channels 1 -srate 11025 <replaceable>media.avi</replaceable></screen>
-would set the output frequency of the resample filter to 11025Hz and downmix
-the audio to 1 channel using the pan filter.
-</para>
-
-
-<para>
-The overall execution of the filter layer is controlled using the
-<option>-af-adv</option> option. This option has two suboptions:
-</para>
-
-<para>
-<option>force</option> is a bit field that controls how the filters
-are inserted and what speed/accuracy optimizations they use:
-</para>
-
-<variablelist>
-<varlistentry>
-<term><option>0</option></term>
-<listitem><para>
-Use automatic insertion of filters and optimize according to CPU speed.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>1</option></term>
-<listitem><para>
-Use automatic insertion of filters and optimize for the highest speed.
-<emphasis>Warning:</emphasis> Some features in the audio filters may
-silently fail, and the sound quality may drop.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>2</option></term>
-<listitem><para>
-Use automatic insertion of filters and optimize for quality.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>3</option></term>
-<listitem><para>
-Use no automatic insertion of filters and no optimization.
-<emphasis>Warning:</emphasis> It may be possible to crash <application>MPlayer</application>
-using this setting.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>4</option></term>
-<listitem><para>
-Use automatic insertion of filters according to 0 above,
-but use floating point processing when possible.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>5</option></term>
-<listitem><para>
-Use automatic insertion of filters according to 1 above,
-but use floating point processing when possible.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>6</option></term>
-<listitem><para>
-Use automatic insertion of filters according to 2 above,
-but use floating point processing when possible.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>7</option></term>
-<listitem><para>
-Use no automatic insertion of filters according to 3 above,
-and use floating point processing when possible.
-</para></listitem>
-</varlistentry>
-</variablelist>
-
-<para>
-<option>list</option> is an alias for the -af option.
-</para>
-
-<para>
-The filter layer is also affected by the following generic options:
-</para>
-
-<variablelist>
-<varlistentry>
-<term><option>-v</option></term>
-<listitem><para>
-Increases the verbosity level and makes most filters print out extra
-status messages.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>-channels</option></term>
-<listitem><para>
-This option sets the number of output channels you would like your
-sound card to use. It also affects the number of channels that are
-being decoded from the media. If the media contains less channels
-than requested the channels filter (see below) will automatically
-be inserted. The routing will be the default routing for the channels
-filter.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>-srate</option></term>
-<listitem><para>
-This option selects the sample rate you would like your sound card
-to use (of course the cards have limits on this). If the sample frequency
-of your sound card is different from that of the current media, the resample
-filter (see below) will be inserted into the audio filter layer to compensate
-for the difference.
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term><option>-format</option></term>
-<listitem><para>
-This option sets the sample format between the audio filter layer and the
-sound card. If the requested sample format of your sound card is different
-from that of the current media, a format filter (see below) will be inserted
-to rectify the difference.
-</para></listitem>
-</varlistentry>
-</variablelist>
-
-<sect2 id="af_resample">
-<title>Up/Downsampling</title>
-
-<para>
-<application>MPlayer</application> fully supports sound up/down-sampling through the
-<option>resample</option> filter. It can be used if you
-have a fixed frequency sound card or if you are stuck with an old sound card
-that is only capable of max 44.1kHz. This filter is automatically enabled if
-it is necessary, but it can also be explicitly enabled on the command line. It
-has three options:
-</para>
-
-<variablelist>
-<varlistentry>
-<term><option>srate &lt;8000-192000&gt;</option></term>
-<listitem><para>
-    is an integer used for setting the output sample
-    frequency in Hz. The valid range for this parameter is 8kHz to 192kHz. If
-    the input and output sample frequency are the same or if this parameter is
-    omitted the filter is automatically unloaded. A high sample frequency
-    normally improves the audio quality, especially when used in combination
-    with other filters.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>sloppy</option></term>
-<listitem><para>
-    is an optional binary parameter that allows the output frequency to differ
-    slightly from the frequency given by <option>srate</option>. This option
-    can be used if the startup of the playback is extremely slow. It is enabled
-    by default.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>type &lt;0-2&gt;</option></term>
-<listitem><para>
-    is an optional integer between <literal>0</literal> and <literal>2</literal> that
-    selects which resampling method to use. Here <literal>0</literal> represents
-    linear interpolation as resampling method, <literal>1</literal> represents
-    resampling using a poly-phase filter-bank and integer processing and
-    <literal>2</literal> represents resampling using a poly-phase filter-bank and
-    floating point processing. Linear interpolation is extremely fast, but
-    suffers from poor sound quality especially when used for up-sampling. The
-    best quality is given by <literal>2</literal> but this method also suffers from
-    the highest CPU load.
-</para></listitem>
-</varlistentry>
-</variablelist>
-
-<para>Example:
-<screen>mplayer -af resample=44100:0:0</screen>
-would set the output frequency of the resample filter to 44100Hz using exact output
-frequency scaling and linear interpolation.
-</para>
-</sect2>
-
-<sect2 id="af_channels">
-<title>Changing the number of channels</title>
-<para>
-The <option>channels</option> filter can be used for adding and removing
-channels, it can also be used for routing or copying channels. It is
-automatically enabled when the output from the audio filter layer differs from
-the input layer or when it is requested by another filter. This filter unloads
-itself if not needed. The number of options is dynamic:
-</para>
-
-<variablelist>
-<varlistentry>
-<term><option>nch &lt;1-6&gt;</option></term>
-<listitem><para>
-  is an integer between <literal>1</literal> and <literal>6</literal> that is used
-  for setting the number of output channels. This option is required, leaving it
-  empty results in a runtime error.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>nr &lt;1-6&gt;</option></term>
-<listitem><para>
-  is an integer between <literal>1</literal> and <literal>6</literal> that is used
-  for specifying the number of routes. This parameter is optional. If it is
-  omitted the default routing is used.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>from1:to1:from2:to2:from3:to3...</option></term>
-<listitem><para>
-  are pairs of numbers between <literal>0</literal> and <literal>5</literal>
-  that define where each channel should be routed.
-</para></listitem>
-</varlistentry>
-</variablelist>
-
-<para>
-  If only <option>nch</option> is given the default routing is used, it works
-  as follows: If the number of output channels is bigger than the number of input
-  channels empty channels are inserted (except mixing from mono to stereo, then
-  the mono channel is repeated in both of the output channels). If the number of
-  output channels is smaller than the number of input channels the exceeding
-  channels are truncated.
-</para>
-
-<para>
-Example 1:
-<screen>mplayer -af channels=4:4:0:1:1:0:2:2:3:3 <replaceable>media.avi</replaceable></screen>
-would change the number of channels to 4 and set up 4 routes that swap
-channel 0 and channel 1 and leave channel 2 and 3 intact. Observe that
-if media containing two channels was played back, channels 2 and 3 would
-contain silence but 0 and 1 would still be swapped.
-</para>
-
-<para>
-Example 2:
-<screen>mplayer -af channels=6:4:0:0:0:1:0:2:0:3 <replaceable>media.avi</replaceable></screen>
-would change the number of channels to 6 and set up 4 routes that copy
-channel 0 to channels 0 to 3. Channel 4 and 5 will contain silence.
-</para>
-</sect2>
-
-<sect2 id="af_format">
-<title>Sample format converter</title>
-<para>
-The <option>format</option> filter converts between different sample formats. It
-  is automatically enabled when needed by the sound card or another filter.
-</para>
-
-<variablelist>
-<varlistentry>
-<term><option>bps &lt;number&gt;</option></term>
-<listitem><para>
-    can be <literal>1</literal>, <literal>2</literal> or <literal>4</literal> and
-    denotes the number of bytes per sample. This option is required, leaving it empty
-    results in a runtime error.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>f &lt;format&gt;</option></term>
-<listitem><para>
-    is a text string describing the sample format. The string is a
-    concatenated mix of: <option>alaw</option>, <option>mulaw</option> or
-    <option>imaadpcm</option>, <option>float</option> or <option>int</option>,
-    <option>unsigned</option> or <option>signed</option>, <option>le</option> or
-    <option>be</option> (little- or big-endian). This option is required,
-    leaving it empty results in a runtime error.
-</para></listitem>
-</varlistentry>
-</variablelist>
-
-<para>
-Example:
-<screen>mplayer -af format=4:float <replaceable>media.avi</replaceable></screen>
-would set the output format to 4 bytes per sample floating point data.
-</para>
-</sect2>
-
-<sect2 id="af_delay">
-<title>Delay</title>
-<para>
-The <option>delay</option> filter delays the sound to the loudspeakers such that
-the sound from the different channels arrives at the listening position
-simultaneously.
-It is only useful if you have more than 2 loudspeakers. This filter has a
-variable number of parameters:
-</para>
-
-<variablelist>
-<varlistentry>
-<term><option>d1:d2:d3...</option></term>
-<listitem><para>
-    are floating point numbers representing the delays in ms that should be
-    imposed on the different channels. The minimum delay is 0ms and the maximum
-    is 1000ms.
-</para></listitem>
-</varlistentry>
-</variablelist>
-
-<para>
-To calculate the required delay for the different channels do as follows:
-</para>
-
-<orderedlist>
-<listitem><para>
-    Measure the distance to the loudspeakers in meters in relation to your
-    listening position, giving you the distances s1 to s5 (for a 5.1 system).
-    There is no point in compensating for the sub-woofer (you will not hear the
-    difference anyway).
-</para></listitem>
-<listitem><para>
-Subtract the distances s1 to s5 from the maximum distance i.e.
-    s[i] = max(s) - s[i]; i = 1...5
-</para></listitem>
-<listitem><para>
-Calculate the required delays in ms as
-    d[i] = 1000*s[i]/342; i = 1...5
-</para></listitem>
-</orderedlist>
-
-<para>
-Example:
-<screen>mplayer -af delay=10.5:10.5:0:0:7:0 <replaceable>media.avi</replaceable></screen>
-would delay front left and right by 10.5ms, the two rear channels and the sub
-by 0ms and the center channel by 7ms.
-</para>
-
-</sect2>
-
-<sect2 id="af_volume">
-<title>Software volume control</title>
-<para>Software volume control is implemented by the <option>volume</option>
-audio filter. Use this filter with caution since it can reduce the signal to
-noise ratio of the sound. In most cases it is best to set the level for the
-PCM sound to max, leave this filter out and control the output level to your
-speakers with the master volume control of the mixer. In case your sound card
-has a digital PCM mixer instead of an analog one, and you hear distortion,
-use the MASTER mixer instead. If there is an external amplifier connected to
-the computer (this is almost always the case), the noise level can be minimized
-by adjusting the master level and the volume knob on the amplifier until the
-hissing noise in the background is gone. This filter has two options:
-</para>
-
-<variablelist>
-<varlistentry>
-<term><option>v &lt;-200 - +60&gt;</option></term>
-<listitem><para>
-    is a floating point number between <literal>-200</literal> and <literal>+60</literal>
-    which represents the volume level in dB. The default level is 0dB.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>c</option></term>
-<listitem><para>
-    is a binary control that turns soft clipping on and off. Soft-clipping can
-    make the sound more smooth if very high volume levels are used. Enable this
-    option if the dynamic range of the loudspeakers is very low. Be aware that
-    this feature creates distortion and should be considered a last resort.
-</para></listitem>
-</varlistentry>
-</variablelist>
-
-<para>
-Example:
-<screen>mplayer -af volume=10.1:0 <replaceable>media.avi</replaceable></screen>
-would amplify the sound by 10.1dB and hard-clip if the sound level is too high.
-</para>
-
-<para>
-This filter has a second feature: It measures the overall maximum sound level
-and prints out that level when <application>MPlayer</application> exits.
-This volume estimate can be used for setting the sound level in
-<application>MEncoder</application> such that the maximum dynamic range is utilized.
-</para>
-</sect2>
-
-<sect2 id="af_equalizer">
-<title>Equalizer</title>
-<para>
-The <option>equalizer</option> filter represents a 10 octave band graphic
-equalizer, implemented using 10 IIR band pass filters. This means that
-it works regardless of what type of audio is being played back. The center
-frequencies for the 10 bands are:
-</para>
-
-<informaltable>
-<tgroup cols="2">
-<thead>
-  <row>
-    <entry>Band No.</entry><entry>Center frequency</entry>
-  </row>
-</thead>
-<tbody>
-  <row><entry>0</entry><entry>31.25 Hz</entry></row>
-  <row><entry>1</entry><entry>62.50 Hz</entry></row>
-  <row><entry>2</entry><entry>125.0 Hz</entry></row>
-  <row><entry>3</entry><entry>250.0 Hz</entry></row>
-  <row><entry>4</entry><entry>500.0 Hz</entry></row>
-  <row><entry>5</entry><entry>1.000 kHz</entry></row>
-  <row><entry>6</entry><entry>2.000 kHz</entry></row>
-  <row><entry>7</entry><entry>4.000 kHz</entry></row>
-  <row><entry>8</entry><entry>8.000 kHz</entry></row>
-  <row><entry>9</entry><entry>16.00 kHz</entry></row>
-</tbody>
-</tgroup>
-</informaltable>
-
-<para>
-If the sample rate of the sound being played back is lower than the center
-frequency for a frequency band, then that band will be disabled. A known
-bug with this filter is that the characteristics for the uppermost band
-are not completely symmetric if the sample rate is close to the center
-frequency of that band. This problem can be worked around by up-sampling
-the sound using the resample filter before it reaches this filter.
-</para>
-
-<para>
-This filter has 10 parameters:
-</para>
-
-<variablelist>
-<varlistentry>
-<term><option>g1:g2:g3...g10</option></term>
-<listitem><para>
-are floating point numbers between <literal>-12</literal> and <literal>+12</literal>
-representing the gain in dB for each frequency band.
-</para></listitem>
-</varlistentry>
-</variablelist>
-
-<para>
-Example:
-<screen>mplayer -af equalizer=11:11:10:5:0:-12:0:5:12:12 <replaceable>media.avi</replaceable></screen>
-would amplify the sound in the upper and lower frequency region while
-canceling it almost completely around 1kHz.
-</para>
-</sect2>
-
-<sect2 id="af_panning">
-<title>Panning filter</title>
-<para>
-Use the <option>pan</option> filter to mix channels arbitrarily. It is
-basically a combination of the volume control and the channels filter.