<!--
     The FreeBSD Documentation Project

     $FreeBSD$
-->

<chapter id="sound">
  <chapterinfo>
    <authorgroup>
      <author>
        <firstname>Moses</firstname>
	<surname>Moore</surname>
	<contrib>Contributed by </contrib>
      </author>
    </authorgroup>
    <!-- 20 November 2000 -->
  </chapterinfo>

  <title>Sound</title>

  <sect1 id="sound-synopsis">
    <title>Synopsis</title>

    <para>FreeBSD supports a wide variety of sound cards, allowing you
      to enjoy high fidelity output from your computer.  This includes
      the ability to record and playback audio in the MPEG Audio Layer
      3 (MP3), WAV, and Ogg Vorbis formats as well as many other
      formats.  The FreeBSD Ports Collection also contains
      applications allowing you to edit your recorded audio, add sound
      effects, and control attached MIDI devices.</para>

    <para>After reading this chapter, you will know:</para>
    <itemizedlist>
      <listitem><para>How to locate your sound card.</para></listitem>
      <listitem><para>How to configure your system so that your sound card is
      recognized.</para></listitem>
      <listitem><para>Methods to test that your card is working using
      sample applications.</para></listitem>
      <listitem><para>How to troubleshoot your sound setup.</para></listitem>
      <listitem><para>How to playback and encode MP3s.</para></listitem>
      <listitem><para>How to rip CD audio tracks into data files.</para></listitem>
    </itemizedlist>

    <para>Before reading this chapter, you should:</para>

    <itemizedlist>
      <listitem><para>Know how to configure and install a new kernel (<xref
        linkend="kernelconfig">).</para></listitem>
    </itemizedlist>
  </sect1>

  <sect1 id="sound-device">
    <title>Locating the Correct Device</title>

    <indexterm><primary>PCI</primary></indexterm>
    <indexterm><primary>ISA</primary></indexterm>
    <indexterm><primary>sound cards</primary></indexterm>
    <para>Before you begin, you should know the model of the card you
      have, the chip it uses, and whether it is a PCI or ISA card.
      FreeBSD supports a wide variety of both PCI and ISA cards.  If
      you do not see your card in the following list, check the
      &man.pcm.4; manual page.  This is not a complete list; however,
      it does list some of the most common cards.</para>

    <itemizedlist>
      <listitem>
	<para>Crystal 4237, 4236, 4232, 4231</para>
      </listitem>

      <listitem>
	<para>Yamaha OPL-SAx</para>
      </listitem>

      <listitem>
	<para>OPTi931</para>
      </listitem>

      <listitem>
	<para>Ensoniq AudioPCI 1370/1371</para>
      </listitem>

      <listitem>
	<para>ESS Solo-1/1E</para>
      </listitem>

      <listitem>
	<para>NeoMagic 256AV/ZX</para>
      </listitem>

      <listitem>
	<para>Sound Blaster Pro, 16, 32, AWE64, AWE128, Live</para>
      </listitem>

      <listitem>
	<para>Creative ViBRA16</para>
      </listitem>

      <listitem>
	<para>Advanced Asound 100, 110, and Logic ALS120</para>
      </listitem>

      <listitem>
	<para>ES 1868, 1869, 1879, 1888</para>
      </listitem>

      <listitem>
	<para>Gravis UltraSound</para>
      </listitem>

      <listitem>
	<para>Aureal Vortex 1 or 2</para>
      </listitem>
    </itemizedlist>

    <indexterm>
      <primary>kernel</primary>
      <secondary>configuration</secondary>
    </indexterm>

    <para>To use your sound device, you will need to load the proper
      device driver.  This may be accomplished in one of two ways.
      The easiest way is to simply load a kernel module for your sound
      card with &man.kldload.8;.  Alternatively, you may statically
      compile in support for your sound card in your kernel.  The
      sections below provide the information you need to add support
      for your hardware in this manner.  For more information about
      recompiling your kernel, please see <xref
      linkend="kernelconfig">.</para>

    <sect2>
      <title>Creative, Advance, and ESS Sound Cards</title>

      <para>If you have one of the above cards, you will need to
	add:</para>
	
      <programlisting>device pcm</programlisting>

      <para>to your kernel configuration file.  If you have a PnP ISA
	card, you will also need to add:</para>

      <programlisting>device sbc</programlisting>

      <para>For a non-PnP ISA card, add:</para>

      <programlisting>device pcm
device sbc0 at isa? port 0x220 irq 5 drq 1 flags 0x15</programlisting>

      <para>to your kernel configuration file.  The settings shown
	above are the defaults.  You may need to change the IRQ or the
	other settings to match your card.  See the &man.sbc.4; manual
	page for more information.</para>

      <note>
	<para>The Sound Blaster Live is not supported under FreeBSD 4.0
	  without a patch, which this section will not cover.  It is
	  recommended that you update to the latest -STABLE before
	  trying to use this card.</para>
      </note>
    </sect2>

    <sect2>
      <title>Gravis UltraSound Cards</title>

      <para>For a PnP ISA card, you will need to add:</para>

      <programlisting>device pcm
device gusc</programlisting>

      <para>to your kernel configuration file.  If you have a non-PnP
	ISA card, you will need to add:</para>

      <programlisting>device pcm
device gus0 at isa? port 0x220 irq 5 drq 1 flags 0x13</programlisting>

      <para>to your kernel configuration file.  You may need to change
	the IRQ or the other settings to match your card. See the
	&man.gusc.4; manual page for more information.</para>
    </sect2>

    <sect2>
      <title>Crystal Sound Cards</title>

      <para>For Crystal cards, you will need to add:</para>

      <programlisting>device pcm
device csa</programlisting>

      <para>to your kernel configuration file.</para>
    </sect2>

    <sect2>
      <title>Generic Support</title>

      <para>For PnP ISA or PCI cards, you will need to add:</para>

      <programlisting>device pcm</programlisting>

      <para>to your kernel configuration file.  If you have a non-PnP
	ISA sound card that does not have a bridge driver, you will
	need to add:</para>

      <programlisting>device pcm0 at isa? irq 10 drq 1 flags 0x0</programlisting>

      <para>to your kernel configuration file.  You may need to change
	the IRQ or the other settings to match your card.</para>

    </sect2>

    <sect2>
      <title>Onboard Sound</title>

      <para>Some systems with built-in motherboard sound devices may
	require the following option in your kernel
	configuration:</para>

      <programlisting>options PNPBIOS</programlisting>
    </sect2>
  </sect1>

  <sect1 id="sound-devicenodes">
    <title>Creating and Testing the Device Nodes</title>

    <indexterm><primary>device nodes</primary></indexterm>
    <para>After you reboot, log in and run <command>dmesg | grep
      pcm</command> as shown below:</para>

    <screen>&prompt.root; dmesg | grep pcm
pcm0: &lt;SB16 DSP 4.11&gt; on sbc0</screen>

    <para>The output from your system may look different.  If no
      <devicename>pcm</devicename> devices show up, something went
      wrong earlier.  If that happens, go through your kernel
      configuration file again and make sure you chose the correct
      device.  Consult the troubleshooting section for additional
      options.</para>

    <para>If the previous command returned
      <devicename>pcm0</devicename>, you will have to run the
      following as <username>root</username>:</para>

    <screen>&prompt.root; cd /dev
&prompt.root; sh MAKEDEV snd0</screen>

    <para>If the command returned <devicename>pcm1</devicename>,
      follow the same steps as shown above, replacing
      <devicename>snd0</devicename> with
      <devicename>snd1</devicename>.</para>

    <note>
      <para>The above commands will <emphasis>not</emphasis> create a
	<devicename>/dev/snd</devicename> device!</para>
    </note>

    <para><command>MAKEDEV</command> will create a group of device
      nodes, including:</para>

    <informaltable frame="none">
      <tgroup cols="2">
	<thead>
	  <row>
	    <entry>Device</entry>
	    <entry>Description</entry>
	  </row>
	</thead>

	<tbody>
	  <row>
	    <entry><devicename>/dev/audio</devicename></entry>
	    <entry>SPARC-compatible audio device</entry>
	  </row>

	  <row>
	    <entry><devicename>/dev/dsp</devicename></entry>
	    <entry>Digitized voice device</entry>
	  </row>

	  <row>
	    <entry><devicename>/dev/dspW</devicename></entry>
	    <entry>Like <devicename>/dev/dsp</devicename>, but 16 bits
	      per sample</entry>
	  </row>

	  <row>
	    <entry><devicename>/dev/midi</devicename></entry>
	    <entry>Raw midi access device</entry>
	  </row>

	  <row>
	    <entry><devicename>/dev/mixer</devicename></entry>
	    <entry>Control port mixer device</entry>
	  </row>

	  <row>
	    <entry><devicename>/dev/music</devicename></entry>
	    <entry>Level 2 sequencer interface</entry>
	  </row>

	  <row>
	    <entry><devicename>/dev/sequencer</devicename></entry>
	    <entry>Sequencer device</entry>
	  </row>

	  <row>
	    <entry><devicename>/dev/pss</devicename></entry>
	    <entry>Programmable device interface</entry>
	  </row>
	</tbody>
      </tgroup>
    </informaltable>

    <para>If all goes well, you should now have a functioning sound
      card.  You may want to install an application such as
      <filename role="package">audio/mpg123</filename> to listen to audio files.</para>

    <sect2>
      <title>Common Problems</title>

      <informaltable>
        <tgroup cols="2">
  	  <thead>
	    <row>
	     <entry>Error</entry>
	      <entry>Solution</entry>
	    </row>
          </thead>
          <indexterm><primary>device node</primary></indexterm>

	  <tbody>
	    <row>
	      <entry><errorname>unsupported subdevice XX</errorname></entry>
	      <entry><para>One or more of the device nodes was not created
	        correctly.  Repeat the steps above.</para></entry>
            </row>

            <indexterm><primary>I/O port</primary></indexterm>
            <row>
              <entry><errorname>sb_dspwr(XX) timed out</errorname></entry>
              <entry><para>The I/O port is not set correctly.</para></entry>
            </row>

            <indexterm><primary>IRQ</primary></indexterm>
            <row>
              <entry><errorname>bad irq XX</errorname></entry>
	      <entry><para>The IRQ is set incorrectly.  Make sure that
  	        the set IRQ and the sound IRQ are the same.</para></entry>
            </row>

            <row>
              <entry><errorname>xxx: gus pcm not attached, out of 
    	        memory</errorname></entry>
              <entry><para>There is not enough available memory to use
                the device.</para></entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </sect2>
  </sect1>

  <sect1 id="sound-mp3">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Chern</firstname>
	  <surname>Lee</surname>
	  <contrib>Contributed by </contrib>
	</author>
      </authorgroup>
      <!-- 11 Sept 2001 -->
    </sect1info>

    <title>MP3 Audio</title>

    <para>MP3 (MPEG Layer 3 Audio) accomplishes near CD-quality sound,
      leaving no reason to let your FreeBSD workstation fall short of
      its offerings.</para>

    <sect2 id="mp3-players">
      <title>MP3 Players</title>

      <para>By far, the most popular XFree86 MP3 player is
	<application>XMMS</application> (X Multimedia System).  
	<application>Winamp</application>
	skins can be used with <application>XMMS</application> since the
	GUI is almost identical to that of Nullsoft's 
	<application>Winamp</application>.
	<application>XMMS</application> also has native plug-in
	support.</para>

      <para><application>XMMS</application> can be installed from the
	<filename role="package">audio/xmms</filename> port or package.</para>

      <para><application>XMMS'</application> interface is intuitive,
	with a playlist, graphic equalizer, and more.  Those familiar
	with <application>Winamp</application> will find
	<application>XMMS</application> simple to use.</para>

      <para>The <filename role="package">audio/mpg123</filename> port is an alternative,
	command-line MP3 player.</para>

      <para><application>mpg123</application> can be run by specifying
	the sound device and the MP3 file on the command line, as
	shown below:</para>

      <screen>&prompt.root; mpg123 -a <replaceable>/dev/dsp1.0</replaceable> Foobar-GreatestHits.mp3
High Performance MPEG 1.0/2.0/2.5 Audio Player for Layer 1, 2 and 3.
Version 0.59r (1999/Jun/15). Written and copyrights by Michael Hipp.
Uses code from various people. See 'README' for more!
THIS SOFTWARE COMES WITH ABSOLUTELY NO WARRANTY! USE AT YOUR OWN RISK!





Playing MPEG stream from BT - Foobar-GreastHits.mp3 ...
MPEG 1.0 layer III, 128 kbit/s, 44100 Hz joint-stereo
</screen>

      <para><literal>/dev/dsp1.0</literal> should be replaced with the
	<devicename>dsp</devicename> device entry on your system.</para>

    </sect2>

    <sect2 id="rip-cd">
      <title>Ripping CD Audio Tracks</title>

      <para>Before encoding a CD or CD track to MP3, the audio data on
	the CD must be ripped onto the hard drive.  This is done by
	copying the raw CDDA (CD Digital Audio) data to WAV
	files.</para>

      <para>The <command>cdda2wav</command> tool, which is a part of
	the <filename role="package">sysutils/cdrtools</filename> suite, is used for ripping
	audio information of CDs and the information associated with
	it.</para>

      <para>With the audio CD in the drive, the following command can
	be issued (as <username>root</username>) to rip an entire CD
	into individual (per track) WAV files:</para>

      <screen>&prompt.root; cdda2wav -D <replaceable>0,1,0</replaceable> -B</screen>

      <para>The <option>-D <replaceable>0,1,0</replaceable></option>
	indicates the SCSI device <devicename>0,1,0</devicename>,
	which corresponds to the output of <command>cdrecord
	-scanbus</command>.</para>

      <para>To rip individual tracks, make use of the
	<option>-t</option> option as shown:</para>

      <screen>&prompt.root; cdda2wav -D <replaceable>0,1,0</replaceable> -t 7</screen>

      <para>This example rips track seven of the audio CDROM.  To rip
	a range of tracks, for example, track one to seven, specify a
	range:</para>

      <screen>&prompt.root; cdda2wav -D <replaceable>0,1,0</replaceable> -t 1+7</screen>

      <para><application>cdda2wav</application> will also support
	ATAPI (IDE) CDROM drives.  To rip from an IDE drive, specify
	the device name in place of the SCSI unit numbers.  For
	example, to rip track 7 from an IDE drive:</para>

      <screen>&prompt.root; cdda2wav -D <replaceable>/dev/acd0a</replaceable> -t 7</screen>

    </sect2>

    <sect2 id="mp3-encoding">
      <title>Encoding MP3s</title>

      <para>Nowadays, the mp3 encoder of choice is
	<application>lame</application>.
	<application>Lame</application> can be found at
	<filename role="package">audio/lame</filename> in the ports tree.</para>

      <para>Using the ripped WAV files, the following command will
	convert <filename>audio01.wav</filename> to
	<filename>audio01.mp3</filename>:</para>

      <screen>&prompt.root; lame -h -b <replaceable>128</replaceable> \
--tt "<replaceable>Foo Song Title</replaceable>" \
--ta "<replaceable>FooBar Artist</replaceable>" \
--tl "<replaceable>FooBar Album</replaceable>" \
--ty "<replaceable>2001</replaceable>" \
--tc "<replaceable>Ripped and encoded by Foo</replaceable>" \
--tg "<replaceable>Genre</replaceable>" \
<replaceable>audio01.wav audio01.mp3</replaceable></screen>

      <para>128 kbits seems to be the standard MP3 bitrate in use.
	Many enjoy the higher quality 160, or 192.  The higher the
	bitrate, the more disk space the resulting MP3 will
	consume--but the quality will be higher.  The
	<option>-h</option> option turns on the <quote>higher quality
	but a little slower</quote> mode.  The options beginning with
	<option>--t</option> indicate ID3 tags, which usually contain
	song information, to be embedded within the MP3 file.
	Additional encoding options can be found by consulting the
	lame man page.</para>
    </sect2>

    <sect2 id="mp3-decoding">
      <title>Decoding MP3s</title>

      <para>In order to burn an audio CD from MP3s, they must be
	converted to a non-compressed WAV format.  Both
	<application>XMMS</application> and
	<application>mpg123</application> support the output of MP3 to
	an uncompressed file format.</para>

      <para>Writing to Disk in <application>XMMS</application>:</para>

      <procedure>
	<step>
	  <para>Launch <application>XMMS</application>.</para>
	</step>

	<step>
	  <para>Right-click on the window to bring up the
	    <application>XMMS</application> menu.</para>
	</step>

	<step>
	  <para>Select <literal>Preference</literal> under
	    <literal>Options</literal>.</para>
	</step>

	<step>
	  <para>Change the Output Plugin to <quote>Disk Writer
	      Plugin</quote>.</para>
	</step>

	<step>
	  <para>Press <literal>Configure</literal>.</para>
	</step>

	<step>
	  <para>Enter (or choose browse) a directory to write the
	    uncompressed files to.</para>
	</step>

	<step>
	  <para>Load the MP3 file into <application>XMMS</application>
	    as usual, with volume at 100% and EQ settings turned
	    off.</para>
	</step>

	<step>
	  <para>Press <literal>Play</literal> &mdash;
	    <application>XMMS</application> will appear as if it is
	    playing the MP3, but no music will be heard.  It is
	    actually playing the MP3 to a file.</para>
	</step>

	<step>
	  <para>Be sure to set the default Output Plugin back to what
	    it was before in order to listen to MP3s again.</para>
	</step>
      </procedure>

      <para>Writing to stdout in <application>mpg123</application>:</para>

      <procedure>
	<step>
	  <para>Run mpg123 -s <replaceable>audio01.mp3</replaceable>
	    &gt; audio01.pcm</para>
	</step>
      </procedure>

      <para><application>XMMS</application> writes a file in the WAV
	format, while <application>mpg123</application> converts the
	MP3 into raw PCM audio data.  Both of these formats can be
	used with <application>cdrecord</application> or
	<application>burncd</application> to create audio
	CDROMs.</para>

      <para>Read <xref linkend="creating-cds"> for more information on using a
	  CD burner in FreeBSD.</para>
    </sect2>
  </sect1>
</chapter>
