comparison DOCS/xml/en/audio.xml @ 13912:c66b1514ce5b

Remove pointless devices section, make video and audio top level sections.

13911:bb37fefc205b

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<sect2 id="audio-dev">
<title>Audio output devices</title>
<sect3 id="sync">
<title>Audio/Video synchronisation</title>

<para>
<application>MPlayer</application>'s audio interface is called
<emphasis>libao2</emphasis>. It currently contains these drivers:

  <command>hdparm -u1 /dev/cdrom</command> (<command>man hdparm</command>).
  This is generally beneficial and described in more detail in the
  <link linkend="drives">CD-ROM</link> section.
 </para></listitem>
</itemizedlist>
</sect3>

<sect3 id="experiences">
<title>Soundcard experiences, recommendations</title>
<para>
On Linux, a 2.4.x kernel is highly recommended. Kernel 2.2 is not tested.
</para>

<para>
Feedback to this document is welcome. Please tell us how
<application>MPlayer</application> and your sound card(s) worked together.
</para>
</sect3>

<sect3 id="af">
<title>Audio filters</title>
<para>
  The old audio plugins have been superseded by a new audio filter layer. Audio
  filters are used for changing the properties of the audio data before the
  sound reaches the sound card. The activation and deactivation of the filters

to rectify the difference.
</para></listitem>
</varlistentry>
</variablelist>

<sect4 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

<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>
</sect4>

<sect4 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

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>
</sect4>

<sect4 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>

<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>
</sect4>

<sect4 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.

<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>

</sect4>

<sect4 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

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>
</sect4>

<sect4 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

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>
</sect4>

<sect4 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:

<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>
</sect4>

<sect4 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

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>
</sect4>

<sect4 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

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>
</sect4>

<sect4 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:

<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>
</sect4>

<sect4 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

<screen>
mplayer -af extrastereo <replaceable>media.avi</replaceable>
mplayer -af extrastereo=3.45 <replaceable>media.avi</replaceable><!--
--></screen>
</para>
</sect4>

<sect4 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>
</sect4>

</sect3>

<sect3 id="audio-plugins">
<title>Audio plugins (deprecated)</title>
<note><para><emphasis role="bold">Audio plugins have been deprecated by audio filters and will
be removed soon.</emphasis></para></note>

<para>

Currently audio plugins can not be used in
<application>MEncoder</application>.
</para>


<sect4 id="updn-sampling">
<title>Up/Downsampling</title>

<para>
<application>MPlayer</application> fully supports up/downsampling of the sound. This plugin can be
used if you have a fixed frequency sound card or if you are stuck with an

The output frequency should not be scaled up from the default value.
Scaling up will cause the audio and video streams to be played in slow
motion in addition to audio distortion.
</para>
</note>
</sect4>


<sect4 id="surround-decode">
<title>Surround Sound decoding</title>

<para>
<application>MPlayer</application> has an audio plugin that can decode
matrix encoded surround sound. Dolby Surround is an example of a matrix

<para>
Usage:
<screen>mplayer <replaceable>media.avi</replaceable> -aop list=surround</screen>
</para>
</sect4>


<sect4 id="sample-format-conv">
<title>Sample format converter</title>

<para>
If your sound card driver does not support signed 16-bit int data type,
this plugin can be used to change the format to one which your sound card

mplayer <replaceable>media.avi</replaceable> -aop list=format:format=<replaceable>outfmt</replaceable></screen>

where <literal><replaceable>outfmt</replaceable></literal> is the
required output format.
</para>
</sect4>


<sect4 id="audio-delay">
<title>Delay</title>
<para>
This plugin delays the sound and is intended as an example of how to
develop new plugins. It can not be used for anything useful from a users
perspective and is mentioned here for the sake of completeness only. Do not
use this plugin unless you are a developer.
</para>
</sect4>


<sect4 id="sw-volume">
<title>Software volume control</title>

<para>
This plugin is a software replacement for the volume control, and can be
used on machines with a broken mixer device. It can also be used if one

<para>
Usage:
<screen>
mplayer <replaceable>media.avi</replaceable> -aop list=volume:softclip</screen>
</para>
</sect4>

<sect4 id="extrastereo">
<title>Extrastereo</title>

<para>
This plugin (linearly) increases the difference between left and right
channels (like the <application>XMMS</application> extrastereo plugin) which gives some

defaults to 2.5. 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>
</sect4>


<sect4 id="volnorm">
<title>Volume normalizer</title>

<para>
This plugin maximizes the volume without distorting the sound.
</para>

<para>
Usage:
<screen>mplayer <replaceable>media.avi</replaceable> -aop list=volnorm</screen>
</para>
</sect4>
</sect3>
</sect2>

13912:c66b1514ce5b

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<sect1 id="audio">
<title>Audio output devices</title>
<sect2 id="sync">
<title>Audio/Video synchronisation</title>

<para>
<application>MPlayer</application>'s audio interface is called
<emphasis>libao2</emphasis>. It currently contains these drivers:

  <command>hdparm -u1 /dev/cdrom</command> (<command>man hdparm</command>).
  This is generally beneficial and described in more detail in the
  <link linkend="drives">CD-ROM</link> section.
 </para></listitem>
</itemizedlist>
</sect2>

<sect2 id="experiences">
<title>Soundcard experiences, recommendations</title>
<para>
On Linux, a 2.4.x kernel is highly recommended. Kernel 2.2 is not tested.
</para>

<para>
Feedback to this document is welcome. Please tell us how
<application>MPlayer</application> and your sound card(s) worked together.
</para>
</sect2>

<sect2 id="af">
<title>Audio filters</title>
<para>
  The old audio plugins have been superseded by a new audio filter layer. Audio
  filters are used for changing the properties of the audio data before the
  sound reaches the sound card. The activation and deactivation of the filters

to rectify the difference.
</para></listitem>
</varlistentry>
</variablelist>

<sect3 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

<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>
</sect3>

<sect3 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

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>
</sect3>

<sect3 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>

<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>
</sect3>

<sect3 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.

<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>

</sect3>

<sect3 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

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>
</sect3>

<sect3 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

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>
</sect3>

<sect3 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:

<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>
</sect3>

<sect3 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

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>
</sect3>

<sect3 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

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>
</sect3>

<sect3 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:

<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>
</sect3>

<sect3 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

<screen>
mplayer -af extrastereo <replaceable>media.avi</replaceable>
mplayer -af extrastereo=3.45 <replaceable>media.avi</replaceable><!--
--></screen>
</para>
</sect3>

<sect3 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>
</sect3>

</sect2>

<sect2 id="audio-plugins">
<title>Audio plugins (deprecated)</title>
<note><para><emphasis role="bold">Audio plugins have been deprecated by audio filters and will
be removed soon.</emphasis></para></note>

<para>

Currently audio plugins can not be used in
<application>MEncoder</application>.
</para>


<sect3 id="updn-sampling">
<title>Up/Downsampling</title>

<para>
<application>MPlayer</application> fully supports up/downsampling of the sound. This plugin can be
used if you have a fixed frequency sound card or if you are stuck with an

The output frequency should not be scaled up from the default value.
Scaling up will cause the audio and video streams to be played in slow
motion in addition to audio distortion.
</para>
</note>
</sect3>


<sect3 id="surround-decode">
<title>Surround Sound decoding</title>

<para>
<application>MPlayer</application> has an audio plugin that can decode
matrix encoded surround sound. Dolby Surround is an example of a matrix

<para>
Usage:
<screen>mplayer <replaceable>media.avi</replaceable> -aop list=surround</screen>
</para>
</sect3>


<sect3 id="sample-format-conv">
<title>Sample format converter</title>

<para>
If your sound card driver does not support signed 16-bit int data type,
this plugin can be used to change the format to one which your sound card

mplayer <replaceable>media.avi</replaceable> -aop list=format:format=<replaceable>outfmt</replaceable></screen>

where <literal><replaceable>outfmt</replaceable></literal> is the
required output format.
</para>
</sect3>


<sect3 id="audio-delay">
<title>Delay</title>
<para>
This plugin delays the sound and is intended as an example of how to
develop new plugins. It can not be used for anything useful from a users
perspective and is mentioned here for the sake of completeness only. Do not
use this plugin unless you are a developer.
</para>
</sect3>


<sect3 id="sw-volume">
<title>Software volume control</title>

<para>
This plugin is a software replacement for the volume control, and can be
used on machines with a broken mixer device. It can also be used if one

<para>
Usage:
<screen>
mplayer <replaceable>media.avi</replaceable> -aop list=volume:softclip</screen>
</para>
</sect3>

<sect3 id="extrastereo">
<title>Extrastereo</title>

<para>
This plugin (linearly) increases the difference between left and right
channels (like the <application>XMMS</application> extrastereo plugin) which gives some

defaults to 2.5. 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>
</sect3>


<sect3 id="volnorm">
<title>Volume normalizer</title>

<para>
This plugin maximizes the volume without distorting the sound.
</para>

<para>
Usage:
<screen>mplayer <replaceable>media.avi</replaceable> -aop list=volnorm</screen>
</para>
</sect3>
</sect2>
</sect1>