path: root/DOCS/xml/en/audio.xml

<?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:
</para>

<informaltable>
<tgroup cols="2">
<thead>
  <row><entry>Driver</entry><entry>Comment</entry></row>
</thead>
<tbody>
<row><entry>oss</entry><entry>
  OSS (ioctl) driver (supports hardware AC3 passthrough)
  </entry></row>
<row><entry>sdl</entry><entry>
  SDL driver (supports sound daemons like <emphasis role="bold">ESD</emphasis>
  and <emphasis role="bold">ARTS</emphasis>)
  </entry></row>
<row><entry>nas</entry><entry>
  NAS (Network Audio System) driver
  </entry></row>
<row><entry>alsa5</entry><entry>
  native ALSA 0.5 driver
  </entry></row>
<row><entry>alsa9</entry><entry>
  native ALSA 0.9 driver (supports hardware AC3 passthrough)
  </entry></row>
<row><entry>sun</entry><entry>
  SUN audio driver (<filename>/dev/audio</filename>) for BSD and Solaris8 users
  </entry></row>
<row><entry>macosx</entry><entry>
  native MacOSX driver
  </entry></row>
<row><entry>win32</entry><entry>
  native Win32 driver
  </entry></row>
<row><entry>arts</entry><entry>
  native ARTS driver (mostly for KDE users)
  </entry></row>
<row><entry>esd</entry><entry>
  native ESD driver (mostly for GNOME users)
  </entry></row>
</tbody>
</tgroup>
</informaltable>

<para>
Linux sound card drivers have compatibility problems. This is because
<application>MPlayer</application> relies on an in-built feature of
<emphasis>properly</emphasis> coded sound drivers that enable them to
maintain correct audio/video sync. Regrettably, some driver authors
don't take the care to code this feature since it is not needed for
playing MP3s or sound effects.
</para>

<para>
Other media players like <ulink url="http://avifile.sourceforge.net">aviplay</ulink>
or <ulink url="http://xine.sourceforge.net">xine</ulink> possibly work
out-of-the-box with these drivers because they use "simple" methods
with internal timing. Measuring showed that their methods are not as
efficient as <application>MPlayer</application>'s.
</para>

<para>
Using <application>MPlayer</application> with a properly written audio
driver will never result in A/V desyncs related to the audio, except
only with very badly created files (check the man page for workarounds).
</para>

<para>
If you happen to have a bad audio driver, try the <option>-autosync</option>
option, it should sort out your problems. See the man page for detailed
information.
</para>

<itemizedlist>
<title>Some notes:</title>
<listitem><para>
  If you have an OSS driver, first try <option>-ao oss</option> (this is
  the default).  If you experience glitches, halts or anything out of the
  ordinary, try <option>-ao sdl</option> (NOTE: you need to have SDL libraries
  and header files installed). The SDL audio driver helps in a lot of cases
  and also supports ESD (GNOME) and ARTS (KDE).
  </para></listitem>
<listitem><para>
  If you have ALSA version 0.5, then you almost always have to use
  <option>-ao alsa5</option>, since ALSA 0.5 has buggy OSS emulation code,
  and will <emphasis role="bold">crash <application>MPlayer</application></emphasis>
  with a message like this:
  <screen>
DEMUXER: Too many (945 in 8390980 bytes) video packets in the buffer!<!--
--></screen>
  </para></listitem>
<listitem><para>
  On Solaris, use the SUN audio driver with the <option>-ao sun</option> option,
  otherwise neither video nor audio will work.
  </para></listitem>
<listitem><para>
  If the sound clicks when playing from CD-ROM, turn on IRQ unmasking, e.g.
  <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>
Linux sound drivers are primarily provided by the free version of OSS.
These drivers have been superseded by <ulink url="http://www.alsa-project.org">ALSA</ulink>
(Advanced Linux Sound Architecture) in the 2.5 development series. If
your distribution does not already use ALSA you may wish to try their
drivers if you experience sound problems. ALSA drivers are generally
superior to OSS in compatibility, performance and features. But some
sound cards are only supported by the commercial OSS drivers from
<ulink url="http://www.opensound.com/">4Front Technologies</ulink>.
They also support several non-Linux systems.
</para>

<informaltable>
<tgroup cols="8">
  <colspec colname="c1"/>
  <colspec colname="c2"/>
  <colspec colname="c3"/>
  <colspec colname="c4"/>
  <colspec colname="c5"/>
  <colspec colname="c6"/>
  <colspec colname="c7"/>
  <colspec colname="c8"/>
  <spanspec spanname="driver" namest="c2" nameend="c5"/>
  <spanspec spanname="ossfree" namest="c2" nameend="c2"/>
  <spanspec spanname="alsa" namest="c3" nameend="c3"/>
  <spanspec spanname="osspro" namest="c4" nameend="c4"/>
  <spanspec spanname="others" namest="c5" nameend="c5"/>
<thead>
  <row>
    <entry morerows="2" valign="middle">SOUND CARD</entry>
    <entry spanname="driver">DRIVER</entry>
    <entry morerows="2" valign="middle">Max kHz</entry>
    <entry morerows="2" valign="middle">Max Channels</entry>
    <entry morerows="2" valign="middle">Max Opens
      <footnote id="maxopens">
        <para>the number of applications that are able to use
          the device <emphasis>at the same time</emphasis>.</para>
      </footnote>
    </entry>
  </row>

  <row>
    <entry spanname="ossfree">OSS/Free</entry>
    <entry spanname="alsa">ALSA</entry>
    <entry spanname="osspro">OSS/Pro</entry>
    <entry spanname="others">other</entry>
  </row>
</thead>

<tbody>
  <row>
    <entry>VIA onboard (686/A/B, 8233, 8235)</entry>
    <entry>
      <ulink url="http://sourceforge.net/project/showfiles.php?group_id=3242&amp;release_id=59602">via82cxxx_audio</ulink>
    </entry>
    <entry>snd-via82xx</entry>
    <entry></entry>
    <entry></entry>
    <entry>4-48 kHz or 48 kHz only, depending on the chipset</entry>
    <entry></entry>
    <entry></entry>
  </row>

  <row>
    <entry>Aureal Vortex 2</entry>
    <entry>none</entry>
    <entry>none</entry>
    <entry>OK</entry>
    <entry>
      <ulink url="http://aureal.sourceforge.net">Linux Aureal Drivers</ulink>
      <ulink url="http://makacs.poliod.hu/~pontscho/aureal/au88xx-1.1.3.tar.bz2">buffer size increased to 32k</ulink>
    </entry>
    <entry>48</entry>
    <entry>4.1</entry>
    <entry>5+</entry>
  </row>

  <row>
    <entry>SB Live!</entry>
    <entry>Analog OK, S/PDIF not working</entry>
    <entry>Both OK</entry>
    <entry>Both OK</entry>
    <entry>
      <ulink url="http://opensource.creative.com">Creative's OSS driver (S/PDIF support)</ulink>
    </entry>
    <entry>192</entry>
    <entry>4.0/5.1</entry>
    <entry>32</entry>
  </row>

  <row>
    <entry>SB 128 PCI (es1371)</entry>
    <entry>OK</entry>
    <entry>?</entry>
    <entry></entry>
    <entry></entry>
    <entry>48</entry>
    <entry>stereo</entry>
    <entry>2</entry>
  </row>

  <row>
    <entry>SB AWE 64</entry>
    <entry>max 44kHz</entry>
    <entry>48kHz sounds bad</entry>
    <entry></entry>
    <entry></entry>
    <entry>48</entry>
    <entry></entry>
    <entry></entry>
  </row>

  <row>
    <entry>GUS PnP</entry>
    <entry>none</entry>
    <entry>OK</entry>
    <entry>OK</entry>
    <entry></entry>
    <entry>48</entry>
    <entry></entry>
    <entry></entry>
  </row>

  <row>
    <entry>Gravis UltraSound ACE</entry>
    <entry></entry>
    <entry></entry>
    <entry></entry>
    <entry></entry>
    <entry></entry>
    <entry></entry>
    <entry></entry>
  </row>

  <row>
    <entry>Gravis UltraSound MAX</entry>
    <entry>OK</entry>
    <entry>OK (?)</entry>
    <entry></entry>
    <entry></entry>
    <entry>48</entry>
    <entry></entry>
    <entry></entry>
  </row>

  <row>
    <entry>ESS 688</entry>
    <entry>OK</entry>
    <entry>OK (?)</entry>
    <entry></entry>
    <entry></entry>
    <entry>48</entry>
    <entry></entry>
    <entry></entry>
  </row>

  <row>
    <entry>C-Media cards (CMI8338/8738)</entry>
    <entry>OK</entry>
    <entry>OK S/PDIF is supported with ALSA 0.9.x</entry>
    <entry>?</entry>
    <entry></entry>
    <entry>44</entry>
    <entry>stereo</entry>
    <entry>1</entry>
  </row>

  <row>
    <entry>Yamaha cards (*ymf*)</entry>
    <entry>not OK (?) (maybe <option>-ao sdl</option>)</entry>
    <entry>OK only with ALSA 0.5 with OSS emulation
      <emphasis role="bold">AND</emphasis> <option>-ao sdl</option> (!) (?)</entry>
    <entry></entry>
    <entry></entry>
    <entry></entry>
    <entry></entry>
    <entry></entry>
  </row>

  <row>
    <entry>Cards with envy24 chips (like Terratec EWS88MT)</entry>
    <entry>?</entry>
    <entry>?</entry>
    <entry>OK</entry>
    <entry></entry>
    <entry>?</entry>
    <entry></entry>
    <entry></entry>
  </row>

  <row>
    <entry>PC Speaker or DAC</entry>
    <entry>OK</entry>
    <entry>none</entry>
    <entry></entry>
    <entry>
      <ulink url="http://www.geocities.com/stssppnn/pcsp.html">Linux PC speaker OSS driver</ulink>
    </entry>
    <entry>The driver emulates 44.1, maybe more.</entry>
    <entry>mono</entry>
    <entry>1</entry>
  </row>

</tbody>
</tgroup>
</informaltable>

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

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

<variable