[MPlayer-DOCS] CVS: main/DOCS/xml/en audio.xml,1.30,1.31
Diego Biurrun CVS
syncmail at mplayerhq.hu
Thu Feb 24 12:00:48 CET 2005
CVS change done by Diego Biurrun CVS
Update of /cvsroot/mplayer/main/DOCS/xml/en
In directory mail:/var2/tmp/cvs-serv15177/DOCS/xml/en
Modified Files:
audio.xml
Log Message:
Move audio filter descriptions to the man page.
Index: audio.xml
===================================================================
RCS file: /cvsroot/mplayer/main/DOCS/xml/en/audio.xml,v
retrieving revision 1.30
retrieving revision 1.31
diff -u -r1.30 -r1.31
--- audio.xml 4 Feb 2005 23:39:31 -0000 1.30
+++ audio.xml 24 Feb 2005 11:00:45 -0000 1.31
@@ -55,703 +55,4 @@
</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 <8000-192000></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 <0-2></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 <1-6></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 <1-6></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 <number></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 <format></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 <-200 - +60></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.
-There are two major uses for this filter:
-</para>
-
-<orderedlist>
-<listitem><para>
-Down-mixing many channels to only a few, stereo to mono for example.
-</para></listitem>
-<listitem><para>
-Varying the "width" of the center speaker in a surround sound system.
-</para></listitem>
-</orderedlist>
-
-<para>
-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:
-</para>
-
-<variablelist>
-<varlistentry>
-<term><option>nch <1-6></option></term>
-<listitem><para>
-is an integer between <literal>1</literal> and <literal>6</literal> and is used
-for setting the number of input channels. This option is required, leaving it
-empty results in a runtime error.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>l00:l01:l02:..l10:l11:l12:...ln0:ln1:ln2:...</option></term>
-<listitem><para>
-are floating point values between <literal>0</literal> and <literal>1</literal>.
-<option>l[i][j]</option> determines how much of input channel j is mixed into
-output channel i.
-</para></listitem>
-</varlistentry>
-</variablelist>
-
-<para>
-Example 1:
-<screen>mplayer -af pan=1:0.5:0.5 -channels 1 <replaceable>media.avi</replaceable></screen>
-would down-mix from stereo to mono.
-</para>
-
-<para>
-Example 2:
-<screen>mplayer -af pan=3:1:0:1:0.5:0.5 -channels 3 <replaceable>media.avi</replaceable></screen>
-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
-sub-woofer for example).
-</para>
-</sect2>
-
-<sect2 id="af_sub">
-<title>Sub-woofer</title>
-<para>
-The <option>sub</option> filter adds a sub woofer channel to the audio
-stream. The audio data used for creating the sub-woofer 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. Warning: Disable this filter when you are playing DVDs with Dolby
-Digital 5.1 sound, otherwise this filter will disrupt the sound to the
-sub-woofer. This filter has two parameters:
-</para>
-
-<variablelist>
-<varlistentry>
-<term><option>fc <20-300></option></term>
-<listitem><para>
- is an optional floating point number used for setting the cutoff frequency
- for the filter in Hz. The valid range is 20Hz to 300Hz. For the best result
- try setting the cutoff frequency as low as possible. This will improve the
- stereo or surround sound experience. The default cutoff frequency is 60Hz.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>ch <0-5></option></term>
-<listitem><para>
- is an optional integer between <literal>0</literal> and <literal>5</literal>
- which determines the channel number in which to insert the sub-channel audio.
- The default is channel number <literal>5</literal>. Observe that the number of
- channels will automatically be increased to <replaceable>ch</replaceable> if
- necessary.
-</para></listitem>
-</varlistentry>
-</variablelist>
-
-<para>
-Example:
-<screen>mplayer -af sub=100:4 -channels 5 <replaceable>media.avi</replaceable></screen>
-would add a sub-woofer channel with a cutoff frequency of
-100Hz to output channel 4.
-</para>
-</sect2>
-
-<sect2 id="af_surround">
-<title>Surround-sound decoder</title>
-<para>
-Matrix encoded surround sound can be decoded by the <option>surround</option>
-filter. Dolby Surround is an example of a matrix encoded format. Many files
-with 2 channel audio actually contain matrixed surround sound. To use this
-feature you need a sound card supporting at least 4 channels. This filter has
-one parameter:
-</para>
-
-<variablelist>
-<varlistentry>
-<term><option>d <0-1000></option></term>
-<listitem><para>
-is an optional floating point number between <literal>0</literal> and
-<literal>1000</literal> used for setting the delay time in ms for the
-rear speakers. 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. The default
-value for d is 20ms.
-</para></listitem>
-</varlistentry>
-</variablelist>
-
-<para>
-Example:
-<screen>mplayer -af surround=15 -channels 4 <replaceable>media.avi</replaceable></screen>
-would add surround sound decoding with 15ms delay for the sound to the
-rear speakers.
-</para>
-</sect2>
-
-<sect2 id="af_export">
-<title>Audio Exporter</title>
-<para>
-This audio filter exports the incoming signal to other processes using memory
-mapping (<literal>mmap()</literal>). Memory mapped areas contain a header:
-
-<programlisting>
-int nch /*number of channels*/
-int size /*buffer size*/
-unsigned long long counter /*Used to keep sync, it's updated
- every time new data is exported.*/
-</programlisting>
-
-The rest is payload (non-interleaved) 16bit data.
-</para>
-
-<variablelist>
-<varlistentry>
-<term><option>mmapped_file</option></term>
-<listitem><para>
-The file you want this filter to export to. The default is to map to
-<filename>~/.mplayer/mplayer-af_export</filename>.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>nsamples</option></term>
-<listitem><para>
-Number of samples per channel. The default is <literal>512</literal> samples.
-</para></listitem>
-</varlistentry>
-</variablelist>
-
-<para>
-Example:
-<screen>mplayer -af export=/tmp/mplayer-af_export:1024 <replaceable>media.avi</replaceable></screen>
-would export 1024 samples per channel to <filename>/tmp/mplayer-af_export</filename>.
-</para>
-</sect2>
-
-<sect2 id="af_extrastereo">
-<title>Extrastereo</title>
-
-<para>
-This audio filter (linearly) increases the difference between left and
-right channels (like the <application>XMMS</application> extrastereo
-plugin) which adds some sort of "live" effect to playback.
-This filter has one parameter:</para>
-
-<variablelist>
-<varlistentry>
-<term><option>mul</option></term>
-<listitem><para>
-is the difference coefficient, an optional floating point number that defaults
-to <literal>2.5</literal>. If you set it to <literal>0.0</literal>, you will
-have mono sound (average of both channels). If you set it to
-<literal>1.0</literal>, sound will be unchanged, if you set it to
-<literal>-1.0</literal>, left and right channels will be swapped.
-</para></listitem>
-</varlistentry>
-</variablelist>
-
-<para>
-Usage:
-<screen>
-mplayer -af extrastereo <replaceable>media.avi</replaceable>
-mplayer -af extrastereo=3.45 <replaceable>media.avi</replaceable><!--
---></screen>
-</para>
-</sect2>
-
-<sect2 id="af_volnorm">
-<title>Volume normalizer</title>
-
-<para>
-This audio filter maximizes the volume without distorting the sound.
-</para>
-
-<para>
-Usage:
-<screen>mplayer -af volnorm <replaceable>media.avi</replaceable></screen>
-</para>
-</sect2>
-
</sect1>
More information about the MPlayer-DOCS
mailing list