doc/en/alsa-guide.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/alsa-guide.xml,v 1.49 2005/03/06 12:27:59 swift Exp $ -->
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">

<guide link="/doc/en/alsa-guide.xml">
<title>Gentoo Linux ALSA Guide</title>
<author title="Author">
  <mail link="zu@pandora.be">Vincent Verleye</mail>
</author>
<author title="Author">
  <mail link="g2boojum@gentoo.org">Grant Goodyear</mail>
</author>
<author title="Author">
  <mail link="agenkin@gentoo.org">Arcady Genkin</mail>
</author>
<author title="Author">
  <mail link="eradicator@gentoo.org">Jeremy Huddleston</mail>
</author>
<author title="Editor"><!-- zhen@gentoo.org -->
  John P. Davis
</author>
<author title="Editor">
  <mail link="swift@gentoo.org">Sven Vermeulen</mail>
</author>
<author title="Editor">
  <mail link="bennyc@gentoo.org">Benny Chuang</mail>
</author>
<author title="Editor">
  <mail link="blubber@gentoo.org">Tiemo Kieft</mail>
</author>
<author title="Editor">
  <mail link="erwin@gentoo.org">Erwin</mail>
</author>

<abstract>
This guide will show you how to set up the Advanced Linux Sound Architecture
(ALSA) on Gentoo Linux. In addition to the Gentoo Linux Desktop Configuration
Guide, this guide is supposed to give you more information on this subject.
</abstract>

<license/>

<version>1.5.12</version>
<date>2005-04-24</date>

<chapter>
<title>The Advanced Linux Sound Architecture</title>
<section>
<title>What is ALSA?</title>
<body>

<p>
ALSA is the <e>Advanced Linux Sound Architecture</e>, a project dedicated to the
development of a high-quality Linux sound subsystem. It has replaced OSS
(<e>Open Sound System</e>) as default sound subsystem in the 2.6 kernel series.
</p>

<p>
ALSA provides efficient support for all types of audio interfaces, is fully
modularized, is SMP and thread-safe and provides a high-quality user space
library called <e>alsa-lib</e> to simplify application programming. It also
provides a backwards compatibility layer with OSS.
</p>

</body>
</section>
</chapter>
<chapter>
<title>Installing ALSA</title>
<section>
<title>USE Flags</title>
<body>

<p>
Gentoo provides an <c>alsa</c> USE flag which you should set in
<path>/etc/make.conf</path> to allow our available packages to compile with
ALSA support. If you have <c>oss</c> in your USE variable as well, ALSA will
compile with OSS backward compatibility.
</p>

</body>
</section>
<section>
<title>Kernel Modules</title>
<body>

<p>
First of all, before continuing, make sure your kernel has <e>Sound Card
Support</e> enabled. If you used <c>genkernel</c> to build your kernel, then
this is automatically true. Otherwise reconfigure your kernel.  Additionally,
make sure you disable <e>Open Sound System</e> in your kernel configuration.
If you don't, your system may try to use these drivers rather than the alsa
ones.  If you see a message about 'sound card not detected' and you are sure
you have the correct driver, this is probably the reason.
</p>

<warn>
If you use a 2.6 kernel, you may use the drivers provided in the kernel, but
we still recommend that you use media-sound/alsa-driver as they are more up
to date than what is provided in the kernel tree.  If you still wish to use
the drivers provided with your kernel, you can skip the rest of this section
and continue with <uri link="#alsa-utils">Installing the ALSA Utils</uri>.
</warn>

<p>
The first step in installing your sound drivers is figuring out what sound
card you have.  If you don't already know, an easy trick is to search
for "audio" in the output of the <c>lspci</c> command. You can install
this tool with <c>emerge pciutils</c>.
</p>

<pre caption="Finding out the soundcard type">
# <i>lspci | grep -i audio</i>
Multimedia audio controller: VIA Technologies, Inc. VT82C686 AC97 Audio Controller (rev 64).
</pre>

<p>
Now go to the <uri link="http://www.alsa-project.org/alsa-doc">ALSA Soundcard
Matrix</uri> and search for your soundcard. In the above example you should go
to the "VIA" manufacturer. You will receive a table with the known chipsets of
that vendor. The chipset in the above example is "via82c686"; the "Details" link
then informs me that the driver is called <path>via82xx</path>. This is all the
information you need, so you can safely discard the rest of that document.
</p>

<p>
Based on this information we can now install the <c>alsa-driver</c> for our
soundcard. First edit <path>/etc/make.conf</path> and <e>add</e> a new option
called ALSA_CARDS to it. Inside this variable you declare the soundcard driver
you want to use:
</p>

<pre caption="Editing /etc/make.conf for ALSA_CARDS">
ALSA_CARDS="via82xx"
</pre>

<warn>
If you have multiple sound cards in your system, separate them with a comma
in the ALSA_CARDS variable.  Ex: ALSA_CARDS="via82xx,emu10k1"
</warn>

<p>
If you want OSS compatibility (highly recommended), you should add 'oss' to
your USE flags in <path>/etc/make.conf</path>.  After that, you are ready to
install <c>alsa-driver</c>:
</p>

<pre caption="Installing ALSA Drivers">
# <i>emerge alsa-driver</i>
</pre>

<impo>
Whenever you (re)compile your kernel sources, chances are that the ALSA drivers
will be deleted. It is therefore adviseable to rerun <c>emerge alsa-driver</c>
every time you (re)compile your kernel.  Note that this will compile the
drivers for the kernel in /usr/src/linux, NOT the running kernel.
</impo>

</body>
</section>
<section id="alsa-utils">
<title>Installing the ALSA Utils</title>
<body>

<p>
If the in-kernel OSS compatibility is not sufficient for your needs, you will
want to install <c>alsa-oss</c>.  This will provide you with the 'aoss'
executable which can be used as demonstrated:
</p>

<pre caption="More OSS compatibility layer">
# <i>emerge alsa-oss</i>
# <i>aoss mpg123 music.mp3</i>
</pre>

<p>
Now install the ALSA Utils on your system (this is mandatory):
</p>

<pre caption="Installing ALSA Utils">
# <i>emerge alsa-utils</i>
</pre>

<p>
Now that the utils are installed, it is time to configure ALSA...
</p>

</body>
</section>
</chapter>
<chapter>
<title>Configuring ALSA</title>
<section>
<title>Automatically Loading the Kernel Modules</title>
<body>

<p>
If you use a modular kernel (such as when using <c>genkernel</c>) you have to
edit <path>/etc/modules.d/alsa</path> so that it activates the necessary
modules at boot time. For the soundcard in our example:
</p>

<pre caption="/etc/modules.d/alsa">
alias snd-card-0 snd-via82xx
<comment># The following is only needed when you want OSS compatibility</comment>
alias sound-slot-0 snd-via82xx
alias /dev/mixer snd-mixer-oss
alias /dev/dsp snd-pcm-oss
alias /dev/midi snd-seq-oss
</pre>

<p>
Now run <c>modules-update</c> to save the changes you made to the
<path>alsa</path> file into <path>/etc/modules.conf</path>:
</p>

<pre caption="Running modules-update">
# <i>modules-update</i>
</pre>

</body>
</section>
<section>
<title>Verifying the Device Files</title>
<body>

<p>
This should be done automatically for you on recent installs, but if you run
into problems, check that your ALSA devices and permissions are set correctly
by your /dev manager.  If you use DevFS, check <path>/etc/devfsd.conf</path>
</p>

<pre caption="/etc/devfsd.conf">
# ALSA/OSS stuff
# Comment/change these if you want to change the permissions on
# the audio devices
LOOKUP          snd          MODLOAD ACTION snd
LOOKUP          dsp          MODLOAD
LOOKUP          mixer        MODLOAD
LOOKUP          midi         MODLOAD
REGISTER        sound/.*     PERMISSIONS root.audio 660
REGISTER        snd/.*       PERMISSIONS root.audio 660
</pre>

</body>
</section>
<section>
<title>Having ALSA Activated at Boot</title>
<body>

<p>
To activate ALSA support at boot, add the <c>alsasound</c> init script to the
boot runlevel:
</p>

<pre caption="Adding alsasound to the boot runlevel">
# <i>rc-update add alsasound boot</i>
# <i>/etc/init.d/alsasound start</i>
</pre>

</body>
</section>
<section>
<title>Unmute the Channels</title>
<body>

<p>
By default, all sound channels are muted. To fix this, run <c>amixer</c>:
</p>

<pre caption="Running amixer">
# <i>amixer</i>
</pre>

<p>
If <c>amixer</c> produces lots of output then you're ready to unmute the
channels. If you receive an error, doublecheck that your soundcard module is
started.
</p>

<p>
Now unmute the <e>Master</e> and <e>PCM</e> channels. If this isn't sufficient,
also unmute the <e>Center</e> and <e>Surround</e> channels. Do not unmute the
channels of which you can not change the volume; this might actually result in
ALSA producing no sound at all...
</p>

<pre caption="Unmuting the sound channels">
<comment>(If you prefer an ncurses method:)</comment>

# <i>alsamixer</i>

<comment>(or)</comment>

# <i>amixer set Master 100% unmute</i>
# <i>amixer set PCM 100% unmute</i>
<comment>(Only if the above isn't sufficient:)</comment>
# <i>amixer set Center 100% unmute</i>
# <i>amixer set Surround 100% unmute</i>
# <i>amixer set Headphone 100% unmute</i>
</pre>


<p>
To check if your sound works, play a wave file (using <c>aplay</c>), mp3 (using
<c>mpg123</c> or even <c>mplayer</c>) or any other sound file for that matter.
</p>

</body>
</section>
</chapter>
<chapter>
<title>Activating MIDI Support</title>
<section>
<title>Installing the Necessary Packages</title>
<body>

<p>
Some soundcards come with onboard MIDI synthesizers. To use them, you must first
install the <c>awesfx</c> package:
</p>

<pre caption="Installing the awesfx package">
# <i>emerge awesfx</i>
</pre>

<p>
If you have a collection of sound fonts somewhere, place them in
<path>/usr/share/sfbank</path>. For instance, the SBLive has a sound font file
called <path>8MBGMSFX.SF2</path> or <path>CT4GMSFX.SF2</path>.
</p>

<p>
After copying over the sound font, select them using <c>asfxload</c>:
</p>

<pre caption="Loading the sound font">
# <i>asfxload /usr/share/sfbank/8MBGMSFX.SF2</i>
</pre>

<p>
You must have this command run every time you boot, so it is adviseable to add
it to <path>/etc/conf.d/local.start</path> as well.
</p>

<p>
If you can't find soundfonts on your driver CD you can download some online from
<uri>http://www.parabola.demon.co.uk/alsa/awe64.html</uri>.
</p>

</body>
</section>
<section>
<title>Timidity++ Virtual Synthesizer</title>
<body>

<p>
If your sound card does not come with a hardware synthesizer (or you don't want
to use it), you can use <c>timidity++</c> to provide you with a virtual
synthesizer. Start by emerging this package:
</p>

<pre caption="Installing Timidity++">
# <i>emerge timidity++</i>
</pre>

<p>
For timidity to play sounds, it needs a soundfont. If you do not have any,
install <c>timidity-eawpatches</c> or <c>timidity-shompatches</c> which will
give you some soundfonts.  You can have multiple soundfont configurations
installed, and you can place your own in <path>/usr/share/timidity/</path>.
To switch between different timidity configurations, you should use the
<e>timidity-update</e> tool provided in the timidity++ package.
</p>

<pre caption="Installing soundfonts">
# <i>emerge timidity-eawpatches</i>
# <i>timidity-update -g -s eawpatches</i>

<comment>(or)</comment>

# <i>emerge timidity-shompatches</i>
# <i>timidity-update -g -s shompatches</i>
</pre>

<p>
Don't forget to add <c>timidity</c> to the default runlevel.
</p>

<pre caption="Adding timidity to the default runlevel">
# <i>rc-update add timidity default</i>
# <i>/etc/init.d/timidity start</i>
</pre>

</body>
</section>
<section>
<title>Testing MIDI Support</title>
<body>

<p>
You can use <c>aplaymidi</c> from the ALSA Utils to test your MIDI
configuration.
</p>

<p>
To see what MIDI output ports are available on your system, use the <c>-l</c>
option:
</p>

<pre caption="Viewing the MIDI output ports">
# <i>aplaymidi -l</i>
</pre>

<p>
If all looks fine, try playing a MIDI file to make sure everything works. With
the <c>-p</c> option you define what MIDI port you want to use.
</p>

<pre caption="Playing a MIDI file">
# <i>aplaymidi -p 65:0 "Final Fantasy 7 - Aerith' Theme.mid"</i>
</pre>

</body>
</section>
</chapter>
<chapter>
<title>Final Remarks</title>
<section>
<title>Tools and Firmware</title>
<body>

<p>
Some specific sound cards can benefit from certain tools provided by the
<c>alsa-tools</c> and <c>alsa-firmware</c> packages. If you need
<c>alsa-tools</c>, be sure to define the ALSA_TOOLS variable in
<path>/etc/make.conf</path> with the tools you require. For instance:
</p>

<pre caption="Selecting ALSA Tools in /etc/make.conf">
ALSA_TOOLS="as10k1 ac3dec"
</pre>

<p>
Then install the <c>alsa-tools</c> (and/or <c>alsa-firmware</c>) package(s):
</p>

<pre caption="Installing ALSA Tools">
# <i>emerge alsa-tools</i>
</pre>

</body>
</section>
<section>
<title>Activating Joystick Support</title>
<body>

<p>
If your soundcard has a joystick plug, you might be interested in activating
joystick support for your soundcard. If so, start by verifying if your soundcard
driver has a joystick parameter. You can verify this by running <c>modinfo</c>
against your kernel module. For instance, for the <c>snd-via82xx</c>:
</p>

<pre caption="Running modinfo">
# <i>modinfo snd-via82xx</i>
filename:    /lib/modules/2.4.22-ck2/snd-via82xx.o
description: "VIA VT82xx audio"
author:      "Jaroslav Kysela &lt;perex@suse.cz&gt;"
license:     "GPL"
parm:        index int array (min = 1, max = 8), description "Index value for
             VIA 82xx bridge."
parm:        id string array (min = 1, max = 8), description "ID string for VIA
             82xx bridge."
parm:        enable int array (min = 1, max = 8), description "Enable audio part
             of VIA 82xx bridge."
parm:        mpu_port long array (min = 1, max = 8), description "MPU-401 port.
             (VT82C686x only)"
<i>parm:        joystick int array (min = 1, max = 8), description "Enable
             joystick. (VT82C686x only)"</i>
parm:        ac97_clock int array (min = 1, max = 8), description "AC'97 codec
             clock (default 48000Hz)."
parm:        dxs_support int array (min = 1, max = 8), description "Support for
             DXS channels (0 = auto, 1 = enable, 2 = disable, 3 = 48k only, 4 =
             no VRA)
</pre>

<p>
If it has the <c>joystick</c> parameter, append <c>joystick=1</c> to your
<c>options</c> line in <path>/etc/modules.d/alsa</path>. For instance:
</p>

<pre caption="Adding the joystick parameter">
alias snd-card-0 snd-via82xx
options snd-via82xx joystick=1
</pre>

</body>
</section>
<section>
<title>Resources</title>
<body>

<ul>
  <li><uri link="http://www.alsa-project.org">The ALSA Project</uri></li>
  <li><uri link="http://www.djcj.org">ALSA Howto's and FAQs</uri></li>
  <li><uri link="http://linux-sound.org">Linux Sound/MIDI Software</uri></li>
</ul>

</body>
</section>
</chapter>
</guide>
1	cam	1.42	<?xml version="1.0" encoding="UTF-8"?>
2	swift	1.50	<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/alsa-guide.xml,v 1.49 2005/03/06 12:27:59 swift Exp $ -->
3	drobbins	1.1	<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4
5	cam	1.42	<guide link="/doc/en/alsa-guide.xml">
6	drobbins	1.1	<title>Gentoo Linux ALSA Guide</title>
7	swift	1.20	<author title="Author">
8			<mail link="zu@pandora.be">Vincent Verleye</mail>
9	drobbins	1.1	</author>
10	swift	1.20	<author title="Author">
11			<mail link="g2boojum@gentoo.org">Grant Goodyear</mail>
12	peesh	1.10	</author>
13	swift	1.20	<author title="Author">
14			<mail link="agenkin@gentoo.org">Arcady Genkin</mail>
15	peesh	1.10	</author>
16	erwin	1.26	<author title="Author">
17			<mail link="eradicator@gentoo.org">Jeremy Huddleston</mail>
18			</author>
19	swift	1.18	<author title="Editor"><!-- zhen@gentoo.org -->
20	cam	1.42	John P. Davis
21	drobbins	1.1	</author>
22	swift	1.20	<author title="Editor">
23			<mail link="swift@gentoo.org">Sven Vermeulen</mail>
24	swift	1.12	</author>
25	swift	1.20	<author title="Editor">
26			<mail link="bennyc@gentoo.org">Benny Chuang</mail>
27	bennyc	1.14	</author>
28	swift	1.20	<author title="Editor">
29			<mail link="blubber@gentoo.org">Tiemo Kieft</mail>
30	blubber	1.16	</author>
31	erwin	1.26	<author title="Editor">
32			<mail link="erwin@gentoo.org">Erwin</mail>
33			</author>
34	drobbins	1.1
35			<abstract>
36	cam	1.42	This guide will show you how to set up the Advanced Linux Sound Architecture
37			(ALSA) on Gentoo Linux. In addition to the Gentoo Linux Desktop Configuration
38	swift	1.20	Guide, this guide is supposed to give you more information on this subject.
39			</abstract>
40	drobbins	1.1
41	swift	1.25	<license/>
42
43	swift	1.50	<version>1.5.12</version>
44			<date>2005-04-24</date>
45	drobbins	1.1
46			<chapter>
47	swift	1.35	<title>The Advanced Linux Sound Architecture</title>
48	drobbins	1.1	<section>
49	swift	1.20	<title>What is ALSA?</title>
50	drobbins	1.1	<body>
51	swift	1.20
52	drobbins	1.1	<p>
53	swift	1.35	ALSA is the <e>Advanced Linux Sound Architecture</e>, a project dedicated to the
54			development of a high-quality Linux sound subsystem. It has replaced OSS
55			(<e>Open Sound System</e>) as default sound subsystem in the 2.6 kernel series.
56	drobbins	1.1	</p>
57
58			<p>
59	swift	1.35	ALSA provides efficient support for all types of audio interfaces, is fully
60			modularized, is SMP and thread-safe and provides a high-quality user space
61			library called <e>alsa-lib</e> to simplify application programming. It also
62			provides a backwards compatibility layer with OSS.
63	drobbins	1.1	</p>
64	swift	1.20
65	drobbins	1.1	</body>
66			</section>
67			</chapter>
68			<chapter>
69	swift	1.35	<title>Installing ALSA</title>
70	drobbins	1.1	<section>
71	swift	1.35	<title>USE Flags</title>
72	swift	1.17	<body>
73
74			<p>
75	swift	1.35	Gentoo provides an <c>alsa</c> USE flag which you should set in
76	cam	1.42	<path>/etc/make.conf</path> to allow our available packages to compile with
77	swift	1.35	ALSA support. If you have <c>oss</c> in your USE variable as well, ALSA will
78			compile with OSS backward compatibility.
79	swift	1.17	</p>
80
81			</body>
82			</section>
83			<section>
84	swift	1.35	<title>Kernel Modules</title>
85	drobbins	1.1	<body>
86	swift	1.20
87	drobbins	1.1	<p>
88	swift	1.35	First of all, before continuing, make sure your kernel has <e>Sound Card
89			Support</e> enabled. If you used <c>genkernel</c> to build your kernel, then
90	neysx	1.46	this is automatically true. Otherwise reconfigure your kernel. Additionally,
91			make sure you disable <e>Open Sound System</e> in your kernel configuration.
92			If you don't, your system may try to use these drivers rather than the alsa
93			ones. If you see a message about 'sound card not detected' and you are sure
94			you have the correct driver, this is probably the reason.
95	drobbins	1.1	</p>
96	swift	1.20
97	dertobi123	1.45	<warn>
98	neysx	1.46	If you use a 2.6 kernel, you may use the drivers provided in the kernel, but
99			we still recommend that you use media-sound/alsa-driver as they are more up
100			to date than what is provided in the kernel tree. If you still wish to use
101			the drivers provided with your kernel, you can skip the rest of this section
102			and continue with <uri link="#alsa-utils">Installing the ALSA Utils</uri>.
103	dertobi123	1.45	</warn>
104	swift	1.20
105			<p>
106	neysx	1.46	The first step in installing your sound drivers is figuring out what sound
107			card you have. If you don't already know, an easy trick is to search
108			for "audio" in the output of the <c>lspci</c> command. You can install
109			this tool with <c>emerge pciutils</c>.
110	drobbins	1.1	</p>
111	swift	1.20
112	swift	1.35	<pre caption="Finding out the soundcard type">
113	neysx	1.40	# <i>lspci \| grep -i audio</i>
114			Multimedia audio controller: VIA Technologies, Inc. VT82C686 AC97 Audio Controller (rev 64).
115	drobbins	1.1	</pre>
116	swift	1.20
117	drobbins	1.1	<p>
118	swift	1.35	Now go to the <uri link="http://www.alsa-project.org/alsa-doc">ALSA Soundcard
119			Matrix</uri> and search for your soundcard. In the above example you should go
120			to the "VIA" manufacturer. You will receive a table with the known chipsets of
121			that vendor. The chipset in the above example is "via82c686"; the "Details" link
122	swift	1.41	then informs me that the driver is called <path>via82xx</path>. This is all the
123			information you need, so you can safely discard the rest of that document.
124	drobbins	1.1	</p>
125	swift	1.20
126	swift	1.35	<p>
127			Based on this information we can now install the <c>alsa-driver</c> for our
128			soundcard. First edit <path>/etc/make.conf</path> and <e>add</e> a new option
129			called ALSA_CARDS to it. Inside this variable you declare the soundcard driver
130			you want to use:
131			</p>
132	swift	1.20
133	swift	1.35	<pre caption="Editing /etc/make.conf for ALSA_CARDS">
134			ALSA_CARDS="via82xx"
135	erwin	1.26	</pre>
136
137	neysx	1.46	<warn>
138			If you have multiple sound cards in your system, separate them with a comma
139			in the ALSA_CARDS variable. Ex: ALSA_CARDS="via82xx,emu10k1"
140			</warn>
141
142	erwin	1.26	<p>
143	neysx	1.46	If you want OSS compatibility (highly recommended), you should add 'oss' to
144			your USE flags in <path>/etc/make.conf</path>. After that, you are ready to
145			install <c>alsa-driver</c>:
146	erwin	1.26	</p>
147
148	swift	1.35	<pre caption="Installing ALSA Drivers">
149			# <i>emerge alsa-driver</i>
150			</pre>
151	swift	1.20
152	drobbins	1.1	<impo>
153	swift	1.35	Whenever you (re)compile your kernel sources, chances are that the ALSA drivers
154	neysx	1.46	will be deleted. It is therefore adviseable to rerun <c>emerge alsa-driver</c>
155			every time you (re)compile your kernel. Note that this will compile the
156			drivers for the kernel in /usr/src/linux, NOT the running kernel.
157	drobbins	1.1	</impo>
158	swift	1.20
159	drobbins	1.1	</body>
160			</section>
161	swift	1.35	<section id="alsa-utils">
162			<title>Installing the ALSA Utils</title>
163	drobbins	1.1	<body>
164
165			<p>
166	neysx	1.46	If the in-kernel OSS compatibility is not sufficient for your needs, you will
167			want to install <c>alsa-oss</c>. This will provide you with the 'aoss'
168			executable which can be used as demonstrated:
169	drobbins	1.1	</p>
170	swift	1.20
171	neysx	1.46	<pre caption="More OSS compatibility layer">
172	swift	1.35	# <i>emerge alsa-oss</i>
173	neysx	1.46	# <i>aoss mpg123 music.mp3</i>
174	blubber	1.16	</pre>
175
176	drobbins	1.1	<p>
177	swift	1.35	Now install the ALSA Utils on your system (this is mandatory):
178	drobbins	1.1	</p>
179	swift	1.20
180	swift	1.35	<pre caption="Installing ALSA Utils">
181			# <i>emerge alsa-utils</i>
182	drobbins	1.1	</pre>
183	swift	1.20
184	drobbins	1.1	<p>
185	swift	1.35	Now that the utils are installed, it is time to configure ALSA...
186	drobbins	1.1	</p>
187	swift	1.20
188	drobbins	1.1	</body>
189			</section>
190	swift	1.35	</chapter>
191			<chapter>
192			<title>Configuring ALSA</title>
193	drobbins	1.1	<section>
194	swift	1.35	<title>Automatically Loading the Kernel Modules</title>
195	drobbins	1.1	<body>
196	swift	1.20
197	drobbins	1.1	<p>
198	swift	1.35	If you use a modular kernel (such as when using <c>genkernel</c>) you have to
199	neysx	1.46	edit <path>/etc/modules.d/alsa</path> so that it activates the necessary
200			modules at boot time. For the soundcard in our example:
201	drobbins	1.1	</p>
202	swift	1.12
203	swift	1.35	<pre caption="/etc/modules.d/alsa">
204			alias snd-card-0 snd-via82xx
205			<comment># The following is only needed when you want OSS compatibility</comment>
206	swift	1.49	alias sound-slot-0 snd-via82xx
207	drobbins	1.1	alias /dev/mixer snd-mixer-oss
208			alias /dev/dsp snd-pcm-oss
209			alias /dev/midi snd-seq-oss
210			</pre>
211	swift	1.20
212	drobbins	1.1	<p>
213	swift	1.35	Now run <c>modules-update</c> to save the changes you made to the
214			<path>alsa</path> file into <path>/etc/modules.conf</path>:
215	swift	1.20	</p>
216
217			<pre caption="Running modules-update">
218	bennyc	1.14	# <i>modules-update</i>
219	drobbins	1.1	</pre>
220	swift	1.20
221	swift	1.35	</body>
222			</section>
223			<section>
224			<title>Verifying the Device Files</title>
225			<body>
226	swift	1.20
227	drobbins	1.1	<p>
228	neysx	1.46	This should be done automatically for you on recent installs, but if you run
229			into problems, check that your ALSA devices and permissions are set correctly
230			by your /dev manager. If you use DevFS, check <path>/etc/devfsd.conf</path>
231	drobbins	1.1	</p>
232	swift	1.20
233	seo	1.8	<pre caption="/etc/devfsd.conf">
234	drobbins	1.1	# ALSA/OSS stuff
235			# Comment/change these if you want to change the permissions on
236			# the audio devices
237			LOOKUP snd MODLOAD ACTION snd
238			LOOKUP dsp MODLOAD
239			LOOKUP mixer MODLOAD
240			LOOKUP midi MODLOAD
241			REGISTER sound/.* PERMISSIONS root.audio 660
242			REGISTER snd/.* PERMISSIONS root.audio 660
243			</pre>
244	swift	1.20
245	drobbins	1.1	</body>
246			</section>
247			<section>
248	swift	1.35	<title>Having ALSA Activated at Boot</title>
249	drobbins	1.1	<body>
250	swift	1.20
251	drobbins	1.1	<p>
252	swift	1.35	To activate ALSA support at boot, add the <c>alsasound</c> init script to the
253			boot runlevel:
254	swift	1.20	</p>
255
256	swift	1.35	<pre caption="Adding alsasound to the boot runlevel">
257	blubber	1.16	# <i>rc-update add alsasound boot</i>
258	swift	1.35	# <i>/etc/init.d/alsasound start</i>
259	drobbins	1.1	</pre>
260	swift	1.20
261	drobbins	1.1	</body>
262			</section>
263			<section>
264	swift	1.35	<title>Unmute the Channels</title>
265	drobbins	1.1	<body>
266	swift	1.20
267	drobbins	1.1	<p>
268	swift	1.35	By default, all sound channels are muted. To fix this, run <c>amixer</c>:
269	drobbins	1.1	</p>
270	swift	1.20
271	swift	1.35	<pre caption="Running amixer">
272			# <i>amixer</i>
273	drobbins	1.1	</pre>
274	swift	1.20
275	drobbins	1.1	<p>
276	swift	1.35	If <c>amixer</c> produces lots of output then you're ready to unmute the
277			channels. If you receive an error, doublecheck that your soundcard module is
278			started.
279	drobbins	1.1	</p>
280	swift	1.20
281	drobbins	1.1	<p>
282	swift	1.35	Now unmute the <e>Master</e> and <e>PCM</e> channels. If this isn't sufficient,
283	swift	1.50	also unmute the <e>Center</e> and <e>Surround</e> channels. Do not unmute the
284			channels of which you can not change the volume; this might actually result in
285			ALSA producing no sound at all...
286	drobbins	1.1	</p>
287	swift	1.20
288	swift	1.35	<pre caption="Unmuting the sound channels">
289	cam	1.47	<comment>(If you prefer an ncurses method:)</comment>
290
291	neysx	1.46	# <i>alsamixer</i>
292
293	cam	1.47	<comment>(or)</comment>
294	neysx	1.46
295	swift	1.48	# <i>amixer set Master 100% unmute</i>
296			# <i>amixer set PCM 100% unmute</i>
297	swift	1.35	<comment>(Only if the above isn't sufficient:)</comment>
298	swift	1.48	# <i>amixer set Center 100% unmute</i>
299			# <i>amixer set Surround 100% unmute</i>
300			# <i>amixer set Headphone 100% unmute</i>
301	drobbins	1.1	</pre>
302	swift	1.20
303	neysx	1.46
304	swift	1.20	<p>
305	swift	1.35	To check if your sound works, play a wave file (using <c>aplay</c>), mp3 (using
306			<c>mpg123</c> or even <c>mplayer</c>) or any other sound file for that matter.
307	drobbins	1.1	</p>
308	swift	1.20
309	erwin	1.26	</body>
310			</section>
311			</chapter>
312			<chapter>
313	swift	1.35	<title>Activating MIDI Support</title>
314	erwin	1.26	<section>
315	swift	1.35	<title>Installing the Necessary Packages</title>
316	erwin	1.26	<body>
317
318			<p>
319	swift	1.35	Some soundcards come with onboard MIDI synthesizers. To use them, you must first
320			install the <c>awesfx</c> package:
321	erwin	1.26	</p>
322
323	swift	1.35	<pre caption="Installing the awesfx package">
324	erwin	1.26	# <i>emerge awesfx</i>
325			</pre>
326
327			<p>
328	swift	1.35	If you have a collection of sound fonts somewhere, place them in
329			<path>/usr/share/sfbank</path>. For instance, the SBLive has a sound font file
330			called <path>8MBGMSFX.SF2</path> or <path>CT4GMSFX.SF2</path>.
331	erwin	1.26	</p>
332
333			<p>
334	cam	1.39	After copying over the sound font, select them using <c>asfxload</c>:
335	erwin	1.26	</p>
336
337	swift	1.35	<pre caption="Loading the sound font">
338	cam	1.39	# <i>asfxload /usr/share/sfbank/8MBGMSFX.SF2</i>
339	erwin	1.26	</pre>
340
341	swift	1.35	<p>
342			You must have this command run every time you boot, so it is adviseable to add
343			it to <path>/etc/conf.d/local.start</path> as well.
344			</p>
345	erwin	1.26
346	swift	1.32	<p>
347			If you can't find soundfonts on your driver CD you can download some online from
348			<uri>http://www.parabola.demon.co.uk/alsa/awe64.html</uri>.
349			</p>
350
351	erwin	1.26	</body>
352			</section>
353			<section>
354			<title>Timidity++ Virtual Synthesizer</title>
355			<body>
356
357			<p>
358	swift	1.35	If your sound card does not come with a hardware synthesizer (or you don't want
359			to use it), you can use <c>timidity++</c> to provide you with a virtual
360	erwin	1.26	synthesizer. Start by emerging this package:
361			</p>
362
363			<pre caption="Installing Timidity++">
364			# <i>emerge timidity++</i>
365			</pre>
366
367			<p>
368	swift	1.35	For timidity to play sounds, it needs a soundfont. If you do not have any,
369	neysx	1.46	install <c>timidity-eawpatches</c> or <c>timidity-shompatches</c> which will
370			give you some soundfonts. You can have multiple soundfont configurations
371			installed, and you can place your own in <path>/usr/share/timidity/</path>.
372			To switch between different timidity configurations, you should use the
373			<e>timidity-update</e> tool provided in the timidity++ package.
374	cam	1.33	</p>
375
376	neysx	1.46	<pre caption="Installing soundfonts">
377	cam	1.33	# <i>emerge timidity-eawpatches</i>
378	cam	1.47	# <i>timidity-update -g -s eawpatches</i>
379	neysx	1.46
380	cam	1.47	<comment>(or)</comment>
381	neysx	1.46
382			# <i>emerge timidity-shompatches</i>
383	cam	1.47	# <i>timidity-update -g -s shompatches</i>
384	cam	1.33	</pre>
385
386			<p>
387	swift	1.35	Don't forget to add <c>timidity</c> to the default runlevel.
388	erwin	1.26	</p>
389
390	swift	1.35	<pre caption="Adding timidity to the default runlevel">
391	erwin	1.26	# <i>rc-update add timidity default</i>
392			# <i>/etc/init.d/timidity start</i>
393			</pre>
394
395			</body>
396			</section>
397			<section>
398			<title>Testing MIDI Support</title>
399			<body>
400
401			<p>
402	cam	1.42	You can use <c>aplaymidi</c> from the ALSA Utils to test your MIDI
403			configuration.
404	swift	1.20	</p>
405
406	drobbins	1.1	<p>
407	swift	1.35	To see what MIDI output ports are available on your system, use the <c>-l</c>
408			option:
409	erwin	1.26	</p>
410
411	swift	1.35	<pre caption="Viewing the MIDI output ports">
412	cam	1.42	# <i>aplaymidi -l</i>
413	erwin	1.26	</pre>
414
415			<p>
416	swift	1.35	If all looks fine, try playing a MIDI file to make sure everything works. With
417	cam	1.42	the <c>-p</c> option you define what MIDI port you want to use.
418	drobbins	1.1	</p>
419	swift	1.20
420	swift	1.35	<pre caption="Playing a MIDI file">
421	cam	1.42	# <i>aplaymidi -p 65:0 "Final Fantasy 7 - Aerith' Theme.mid"</i>
422	erwin	1.26	</pre>
423
424	drobbins	1.1	</body>
425			</section>
426			</chapter>
427			<chapter>
428	swift	1.35	<title>Final Remarks</title>
429	drobbins	1.1	<section>
430	swift	1.35	<title>Tools and Firmware</title>
431	drobbins	1.1	<body>
432	swift	1.20
433			<p>
434	swift	1.35	Some specific sound cards can benefit from certain tools provided by the
435	cam	1.36	<c>alsa-tools</c> and <c>alsa-firmware</c> packages. If you need
436	swift	1.35	<c>alsa-tools</c>, be sure to define the ALSA_TOOLS variable in
437			<path>/etc/make.conf</path> with the tools you require. For instance:
438	swift	1.20	</p>
439
440	swift	1.35	<pre caption="Selecting ALSA Tools in /etc/make.conf">
441			ALSA_TOOLS="as10k1 ac3dec"
442	drobbins	1.1	</pre>
443	swift	1.20
444	erwin	1.26	<p>
445	swift	1.35	Then install the <c>alsa-tools</c> (and/or <c>alsa-firmware</c>) package(s):
446	erwin	1.26	</p>
447
448	swift	1.35	<pre caption="Installing ALSA Tools">
449			# <i>emerge alsa-tools</i>
450	erwin	1.26	</pre>
451
452			</body>
453			</section>
454			<section>
455	swift	1.21	<title>Activating Joystick Support</title>
456			<body>
457
458			<p>
459			If your soundcard has a joystick plug, you might be interested in activating
460	bennyc	1.37	joystick support for your soundcard. If so, start by verifying if your soundcard
461	swift	1.21	driver has a joystick parameter. You can verify this by running <c>modinfo</c>
462	swift	1.35	against your kernel module. For instance, for the <c>snd-via82xx</c>:
463	swift	1.21	</p>
464
465			<pre caption="Running modinfo">
466			# <i>modinfo snd-via82xx</i>
467			filename: /lib/modules/2.4.22-ck2/snd-via82xx.o
468			description: "VIA VT82xx audio"
469			author: "Jaroslav Kysela <perex@suse.cz>"
470			license: "GPL"
471	swift	1.35	parm: index int array (min = 1, max = 8), description "Index value for
472			VIA 82xx bridge."
473			parm: id string array (min = 1, max = 8), description "ID string for VIA
474			82xx bridge."
475			parm: enable int array (min = 1, max = 8), description "Enable audio part
476			of VIA 82xx bridge."
477			parm: mpu_port long array (min = 1, max = 8), description "MPU-401 port.
478			(VT82C686x only)"
479			<i>parm: joystick int array (min = 1, max = 8), description "Enable
480			joystick. (VT82C686x only)"</i>
481	cam	1.42	parm: ac97_clock int array (min = 1, max = 8), description "AC'97 codec
482	swift	1.35	clock (default 48000Hz)."
483	cam	1.42	parm: dxs_support int array (min = 1, max = 8), description "Support for
484			DXS channels (0 = auto, 1 = enable, 2 = disable, 3 = 48k only, 4 =
485	swift	1.35	no VRA)
486	swift	1.21	</pre>
487
488			<p>
489	swift	1.35	If it has the <c>joystick</c> parameter, append <c>joystick=1</c> to your
490			<c>options</c> line in <path>/etc/modules.d/alsa</path>. For instance:
491	swift	1.21	</p>
492
493			<pre caption="Adding the joystick parameter">
494			alias snd-card-0 snd-via82xx
495			options snd-via82xx joystick=1
496			</pre>
497	swift	1.17
498			</body>
499			</section>
500	drobbins	1.1	<section>
501	swift	1.35	<title>Resources</title>
502	drobbins	1.1	<body>
503	swift	1.20
504	drobbins	1.1	<ul>
505	swift	1.35	<li><uri link="http://www.alsa-project.org">The ALSA Project</uri></li>
506			<li><uri link="http://www.djcj.org">ALSA Howto's and FAQs</uri></li>
507			<li><uri link="http://linux-sound.org">Linux Sound/MIDI Software</uri></li>
508	drobbins	1.1	</ul>
509	swift	1.20
510	drobbins	1.1	</body>
511			</section>
512			</chapter>
513			</guide>