/[gentoo]/xml/htdocs/doc/en/alsa-guide.xml
Gentoo

Contents of /xml/htdocs/doc/en/alsa-guide.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.22 - (show annotations) (download) (as text)
Sat Dec 20 18:39:29 2003 UTC (10 years, 7 months ago) by aaby
Branch: MAIN
Changes since 1.21: +9 -9 lines
File MIME type: application/xml
updated (closes bug #36186)

1 <?xml version='1.0' encoding="UTF-8"?>
2 <!-- $Header: /home/cvsroot/gentoo/xml/htdocs/doc/en/alsa-guide.xml,v 1.21 2003/11/23 16:30:50 swift Exp $ -->
3 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4
5 <guide link = "/doc/en/alsa-guide.xml">
6 <title>Gentoo Linux ALSA Guide</title>
7 <author title="Author">
8 <mail link="zu@pandora.be">Vincent Verleye</mail>
9 </author>
10 <author title="Author">
11 <mail link="g2boojum@gentoo.org">Grant Goodyear</mail>
12 </author>
13 <author title="Author">
14 <mail link="agenkin@gentoo.org">Arcady Genkin</mail>
15 </author>
16 <author title="Editor"><!-- zhen@gentoo.org -->
17 John P. Davis
18 </author>
19 <author title="Editor">
20 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
21 </author>
22 <author title="Editor">
23 <mail link="bennyc@gentoo.org">Benny Chuang</mail>
24 </author>
25 <author title="Editor">
26 <mail link="blubber@gentoo.org">Tiemo Kieft</mail>
27 </author>
28
29 <license/>
30
31 <abstract>
32 This guide will show you how to set up the Advanced Linux Sound Architecture
33 (ALSA) on Gentoo Linux. In addition to the Gentoo Linux Desktop Configuration
34 Guide, this guide is supposed to give you more information on this subject.
35 </abstract>
36
37 <version>1.3.4</version>
38 <date>November 23, 2003</date>
39
40 <chapter>
41 <title>Introduction</title>
42 <section>
43 <title>What is ALSA?</title>
44 <body>
45
46 <p>
47 The Advanced Linux Sound Architecture (ALSA) is a project to improve the Linux
48 sound subsystem by rewriting large chunks of it. It is anticipated that ALSA
49 will make it into Linux kernel 2.6.x (or 3.x.x -- whichever comes first) as it
50 becomes ready.
51 </p>
52
53 <p>
54 ALSA provides audio and MIDI functionality for Linux.
55 </p>
56
57 <p>
58 Quoted from <uri>http://www.alsa-project.org</uri>, ALSA has the following
59 features:
60 </p>
61
62 <ul>
63 <li>
64 Efficient support for all types of audio interfaces, from consumer
65 soundcards to professional multichannel audio interfaces
66 </li>
67 <li>Fully modularized sound drivers</li>
68 <li>SMP and thread-safe design</li>
69 <li>
70 User space library (alsa-lib) to simplify application programming and
71 provide higher level functionality
72 </li>
73 <li>
74 Support for the older OSS API, providing binary compatibility for most OSS
75 programs
76 </li>
77 </ul>
78
79 <p>
80 There's lots more to ALSA however, like support for Full Duplex playback and
81 recording, multiple soundcard support, hardware mixing of streams, extensive
82 mixer capabilities (to support advanced features of new soundcards), ...
83 </p>
84
85 </body>
86 </section>
87 <section>
88 <title>Why use ALSA?</title>
89 <body>
90
91 <p>
92 If your soundcard is supported by the Linux kernel sound system or the
93 commercial OSS/4Front sound driver system, which can be found in all 2.4.x
94 Linux kernels, you could just aswell build <e>those modules</e> for use with
95 your soundcard. If you want this, just read through the <uri
96 link="http://www.tldp.org/HOWTO/Sound-HOWTO/index.html">Linux Sound HOWTO</uri>.
97 </p>
98
99 <p>
100 However, those OSS/4Front drivers have some limitations -- being commercial is
101 one. ALSA is an attempt to go beyond these limitations and to do so in an open-source fashion. ALSA is a fully GPL and LGPL'ed sound driver system, that
102 provides a professional quality system for recording, playback, and MIDI
103 sequencing.
104 </p>
105
106 </body>
107 </section>
108 <section>
109 <title>What cards does ALSA support?</title>
110 <body>
111
112 <p>
113 ALSA tries to support as many (new) cards as possible by providing open-source
114 drivers. However, some vendors may provide binary-only packages.
115 </p>
116
117 <p>
118 To know if your card is supported, you can find a Soundcard Matrix of supported
119 and not-supported cards here: <uri>http://www.alsa-project.org/alsa-doc/</uri>.
120 </p>
121
122 </body>
123 </section>
124 </chapter>
125
126 <chapter>
127 <title>Installation</title>
128 <section>
129 <title>Gentoo USE flags</title>
130 <body>
131
132 <p>
133 To compile programs with ALSA-support, be sure to add <e>alsa</e> to
134 your USE-variable. However, several tools don't support alsa yet, and
135 require OSS. ALSA provides OSS-emulation if you define <e>oss</e> in your
136 USE-variable before you start.
137 </p>
138
139 </body>
140 </section>
141 <section>
142 <title>Kernel modules</title>
143 <body>
144
145 <p>
146 Since we're still using 2.4.x kernel sources, we'll have to compile kernel
147 modules and ALSA modules separately. People who are using a 2.5.x kernel can
148 do this from within their kernel configuration, since the ALSA modules are
149 included in the kernel sources and should be built there.
150 </p>
151
152 <p>
153 First we'll make sure that our kernel configuration is ready for use with ALSA.
154 All you need in your kernel configuration is having Sound Card Support set to
155 be built as a module (M). This will build <path>soundcore.o</path>.
156 </p>
157
158 <note>
159 Possibly, this will also work when you built Sound Card Support in the kernel
160 (Y) instead of building it as a module (M). However, the official ALSA
161 documentation suggests building it as a module, since ALSA will try loading it.
162 </note>
163
164 <p>
165 If you already have a working kernel configuration, make sure you remove all
166 sound drivers (except for Sound Card Support). If you wish to do this without
167 having to reboot, you could do like this:
168 </p>
169
170 <pre caption="Kernel configuration">
171 # <i>cd /usr/src/linux</i>
172 # <i>cp .config ~/</i>
173 # <i>make mrproper</i>
174 # <i>cp ~/.config .</i>
175 # <i>make menuconfig</i>
176 </pre>
177
178 <p>
179 Now select <e>Sound Card Support</e> as Module (M) and deselect all other sound
180 drivers. Exit and say Y to save your kernel configuration. After that, build
181 the modules:
182 </p>
183
184 <pre caption="Kernel compilation">
185 # <i>make dep clean</i>
186 # <i>make modules modules_install</i>
187 </pre>
188
189 <p>
190 Before installing your new modules, this last line will delete all your previous
191 modules, even the ones from a previous ALSA installation.
192 </p>
193
194 <impo>
195 This means, whenever you recompile your kernel later on, you MUST recompile
196 <c>alsa-driver</c>.
197 </impo>
198
199 </body>
200 </section>
201 <section>
202 <title>ALSA modules</title>
203 <body>
204
205 <p>
206 Now it's time to install the ALSA drivers for your soundcard(s). If your
207 soundcard is PCI, you can find out the name and type of your soundcard by
208 looking at the output of <path>/proc/pci</path>.
209 </p>
210
211 <pre caption="Search for soundcard information">
212 # <i>grep audio /proc/pci</i>
213 </pre>
214
215 <warn>
216 If you had a previous sound setup and there are still non-ALSA sound modules
217 loaded, unload them <e>now</e>. Check with <c>lsmod</c> and use <c>rmmod</c>
218 to unload all sound-related modules on your system.
219 </warn>
220
221 <p>
222 We could simply do an <c>emerge alsa-driver</c> now, this would compile and
223 install <e>all</e> ALSA sound drivers.
224 </p>
225
226 <p>
227 However, to save some time, lookup the <e>Module Name</e> of your soundcard(s)
228 on the <uri link="http://www.alsa-project.org/alsa-doc">ALSA Soundcard
229 Matrix</uri> by following the <e>Details</e> link in the <e>Driver and Docs</e>
230 column in the row of the chipset of your soundcard. Mine is <c>snd-emu10k1</c>,
231 since I have an SBlive! soundcard, with the <e>EMU10K1</e> chipset. We'll set
232 ALSA_CARDS environment to the value of the module name before emerging (but
233 without the snd prefix), so emerge will only compile the drivers we need.
234 </p>
235
236 <pre caption="Compile correct modules">
237 # <i>env ALSA_CARDS='emu10k1' emerge alsa-driver</i>
238 </pre>
239
240 <note>
241 You can also add this value in <path>/etc/make.conf</path>, so when you have
242 to emerge the alsa-driver later on you can just run <c>emerge alsa-driver</c>.
243 For example, like this: <c>echo 'ALSA_CARDS="emu10k1"' >> /etc/make.conf</c>
244 </note>
245
246 <note>
247 When you want to install ALSA drivers for more than one soundcard, you could
248 set ALSA_CARDS to a space-separated list of drivers; like this: <c>env
249 ALSA_CARDS='emu10k1 intel8x0 ens1370' emerge alsa-driver</c>
250 </note>
251
252 <note>
253 If you want to have OSS compatibility, make sure to emerge <i>alsa-oss</i>, it
254 is the ALSA/OSS compatibility wrapper.
255 </note>
256
257 <note>
258 If you plan on recompiling your kernels numerous times, it might
259 be adviseable to emerge <c>alsa-driver</c> with <c>--buildpkg</c>. This
260 will create a binary package for it. Later, after recompiling your kernel,
261 you can just do <c>emerge --usepkg alsa-driver</c> which will install the
262 binary package instead of recompiling it completely.
263 </note>
264
265 <p>
266 After this, the ALSA modules should be installed on your system.
267 </p>
268
269 </body>
270 </section>
271 <section>
272 <title>Configuration of ALSA</title>
273 <body>
274
275 <p>
276 Let's start configuring now to get ALSA working properly. We'll need to edit
277 some files, to let our system know about the freshly installed ALSA modules.
278 </p>
279
280 <p>
281 First, install <c>alsa-utils</c> on your system:
282 </p>
283
284 <pre caption = "Emerging alsa-utils">
285 # <i>emerge alsa-utils</i>
286 </pre>
287
288 <p>
289 Hereafter, we need to edit <path>/etc/modules.d/alsa</path>.
290 </p>
291
292 <warn>
293 There is no need to edit <path>/etc/modules.conf</path>. Instead, always edit
294 files in <path>/etc/modules.d</path>.
295 </warn>
296
297 <p>
298 Check the ALSA portion <e>at the bottom of the file</e>. By tweaking this line
299 you can specify the max number of soundcards you have (generally, just one).
300 </p>
301
302 <pre caption="At the bottom of /etc/modules.d/alsa">
303 <comment>Set this to the correct number of cards.</comment>
304 options snd cards_limit=1
305 </pre>
306
307 <p>
308 Now we'll specify the sounddriver(s) ALSA should use. In the same file, edit
309 like this:
310 </p>
311
312 <pre caption="In /etc/modules.d/alsa">
313 ## and then run `modules-update' command.
314 ## Read alsa-driver's INSTALL file in /usr/share/doc for more info.
315 ##
316 ## ALSA portion
317 alias snd-card-0 snd-emu10k1
318 <comment>## If you have more than one, add:</comment>
319 ## alias snd-card-1 snd-intel8x0
320 ## alias snd-card-2 snd-ens1370
321 ## OSS/Free portion
322 ## alias sound-slot-0 snd-card-0
323 ## alias sound-slot-1 snd-card-1
324 ##
325 </pre>
326
327 <note>
328 If you have more than one soundcard, adjust the <c>cards_limit</c> value and add
329 more snd-card aliases to the file. I don't have experience with this, but you
330 can find examples for configurations with two or more soundcards in <uri
331 link="http://www.alsa-project.org/alsa-doc/alsa-howto/c1660.htm">Chapter 6</uri>
332 of the <uri
333 link="http://www.alsa-project.org/alsa-doc/alsa-howto/alsa-howto.html">ALSA
334 Howto</uri>.
335 </note>
336
337 <p>
338 Last thing to do in this file, almost at the end, check if these lines are there
339 and uncommented:
340 </p>
341
342 <pre caption="Near the end of /etc/modules.d/alsa">
343 alias /dev/mixer snd-mixer-oss
344 alias /dev/dsp snd-pcm-oss
345 alias /dev/midi snd-seq-oss
346 </pre>
347
348 <p>
349 Now double-check the file <path>/etc/modules.d/alsa</path> and when you're sure
350 everyting is ok, run <c>modules-update</c>.
351 </p>
352
353 <pre caption="Running modules-update">
354 # <i>modules-update</i>
355 </pre>
356
357 <note>
358 Running <c>modules-update</c> here will insert the data from
359 <path>/etc/modules.d/alsa</path> into <path>/etc/modules.conf</path>
360 </note>
361
362 <p>
363 You should also verify that <path>/etc/devfsd.conf</path> has the alsa devices
364 and permissions correctly registered.
365 </p>
366
367 <pre caption="/etc/devfsd.conf">
368 # ALSA/OSS stuff
369 # Comment/change these if you want to change the permissions on
370 # the audio devices
371 LOOKUP snd MODLOAD ACTION snd
372 LOOKUP dsp MODLOAD
373 LOOKUP mixer MODLOAD
374 LOOKUP midi MODLOAD
375 REGISTER sound/.* PERMISSIONS root.audio 660
376 REGISTER snd/.* PERMISSIONS root.audio 660
377 </pre>
378
379 <note>
380 Notice that devfsd.conf sets <path>/dev/sound</path> permissions to be
381 root.audio. Thus, for non-root users to use audio they will have to be part of
382 the audio group.
383 </note>
384
385 </body>
386 </section>
387 </chapter>
388
389 <chapter>
390 <title>Starting ALSA</title>
391 <section>
392 <title>Adding alsasound to a runlevel</title>
393 <body>
394
395 <p>
396 First thing to do now, is to make ALSA startup at boottime. Like this:
397 </p>
398
399 <pre caption="Add ALSA to the boot runlevel">
400 # <i>rc-update add alsasound boot</i>
401 </pre>
402
403 <warn>
404 Note that the alsasound script should be added to the "boot" runlevel, not the
405 "default" runlevel.
406 </warn>
407
408 </body>
409 </section>
410 <section>
411 <title>Running and unmuting</title>
412 <body>
413
414 <p>
415 Since we're Linux users, we don't want to reboot. So we'll start the alsasound
416 script manually.
417 </p>
418
419 <pre caption="Starting ALSA">
420 # <i>/etc/init.d/alsasound start</i>
421 </pre>
422
423 <p>
424 ALSA is running now. If everything is ok, you should be able to see the ALSA
425 modules loaded when running <c>lsmod</c>. However, sound won't work yet,
426 because the channels are still muted. We need <c>amixer</c> to fix this.
427 </p>
428
429 <pre caption = "Running amixer">
430 # <i>amixer</i>
431 </pre>
432
433 <warn>
434 You shouldn't get this, but <e>if</e> you get an error about "amixer: Mixer
435 attach default error: No such file or directory", you should manually modprobe
436 <c>snd-mixer-oss</c> and <c>snd-pcm-oss</c> once. After that run amixer again.
437 </warn>
438
439 <pre caption="Only if you get an error when running amixer">
440 # <i>modprobe snd-mixer-oss</i>
441 # <i>modprobe snd-pcm-oss</i>
442 # <i>amixer</i>
443 </pre>
444
445 <p>
446 If you got this far, now unmute Master and PCM channels. Some hardware
447 even requires you to unmute the center channel or even the surround
448 channel.
449 </p>
450
451 <pre caption = "Unmuting channels">
452 # <i>amixer set Master 100 unmute</i>
453 # <i>amixer set PCM 100 unmute</i>
454 <comment>Only if the above doesn't succeed on its own:</comment>
455 # <i>amixer set Center 100 unmute</i>
456 # <i>amixer set Surround 100 unmute</i>
457 <comment>Test the sound:</comment>
458 # <i>aplay $KDEDIR/share/sounds/pop.wav</i> <codenote>(pop.wav is part of KDE)</codenote>
459 </pre>
460
461 <p>
462 We check to see if sound is working by using the aplay (alsa play) command. If
463 you hear a pop, then sound is indeed working. Then, adjust the volume settings
464 to your liking; the ncurses-based <c>alsamixer</c> is a great way to get them
465 "just so".
466 </p>
467
468 <p>
469 You may want to emerge <c>alsa-xmms</c> as that will provide ALSA support for
470 XMMS.
471 </p>
472
473 <p>
474 When you reboot your system, the <c>alsasound</c> init script will
475 properly save and restore your volume settings.
476 </p>
477
478 </body>
479 </section>
480 </chapter>
481
482 <chapter>
483 <title>Final Notes</title>
484 <section>
485 <title>After kernel-upgrades...</title>
486 <body>
487
488 <p>
489 When you ever rebuild your kernel, or upgrade to another kernel, you'll have to
490 rebuild the ALSA modules.
491 </p>
492
493 <p>
494 Although you might have installed <c>alsa-driver</c>, <c>alsa-libs</c> and
495 <c>alsa-utils</c>, only the first will have to be installed again, since it will
496 put the alsa modules in <path>/lib/modules/*/kernel/sound/pci/</path>.
497 </p>
498
499 <pre caption="Needed after each kernel compile">
500 # <i>emerge alsa-driver</i>
501 </pre>
502
503 </body>
504 </section>
505 <section>
506 <title>/etc/modules.autoload</title>
507 <body>
508
509 <p>
510 You won't have to edit this file for use with ALSA. After our <c>rc-update add
511 alsasound boot</c>, our system will load the correct modules at startup.
512 </p>
513
514 <p>
515 It's not necessary to add <c>snd-pcm-oss</c> or <c>snd-mixer-oss</c> in this
516 file. Check the <uri link="http://www.djcj.org/LAU/guide/alsbook/faq1.html">this
517 FAQ</uri> for more info.
518 </p>
519
520 </body>
521 </section>
522 <section>
523 <title>Known bugs</title>
524 <body>
525
526 <note>
527 This guide lags behind on the alsa-development. Chances are these bugs
528 are already fixed when you read this.
529 </note>
530
531 <ul>
532 <li>
533 If you have <b>lots of noise</b> when using <b>oss</b> emulation, add
534 <e>options snd-pcm-oss dsp_map=1</e> to <path>/etc/modules.d/alsa</path>
535 </li>
536 </ul>
537
538 </body>
539 </section>
540 <section>
541 <title>Activating Joystick Support</title>
542 <body>
543
544 <p>
545 If your soundcard has a joystick plug, you might be interested in activating
546 joystick support for your soundcard. If so, start by verifying if your soundcard
547 driver has a joystick parameter. You can verify this by running <c>modinfo</c>
548 against your <path>snd-&lt;your chipset&gt;</path>. For instance, for the
549 <c>snd-via82xx</c>:
550 </p>
551
552 <pre caption="Running modinfo">
553 # <i>modinfo snd-via82xx</i>
554 filename: /lib/modules/2.4.22-ck2/snd-via82xx.o
555 description: "VIA VT82xx audio"
556 author: "Jaroslav Kysela &lt;perex@suse.cz&gt;"
557 license: "GPL"
558 parm: index int array (min = 1, max = 8), description "Index value for VIA 82xx bridge."
559 parm: id string array (min = 1, max = 8), description "ID string for VIA 82xx bridge."
560 parm: enable int array (min = 1, max = 8), description "Enable audio part of VIA 82xx bridge."
561 parm: mpu_port long array (min = 1, max = 8), description "MPU-401 port. (VT82C686x only)"
562 <i>parm: joystick int array (min = 1, max = 8), description "Enable joystick. (VT82C686x only)"</i>
563 parm: ac97_clock int array (min = 1, max = 8), description "AC'97 codec clock (default 48000Hz)."
564 parm: dxs_support int array (min = 1, max = 8), description "Support for DXS channels
565 (0 = auto, 1 = enable, 2 = disable, 3 = 48k only, 4 = no VRA)"
566 </pre>
567
568 <p>
569 If it has the <c>joystick</c> parameter, then append <c>joystick=1</c> to your
570 <c>options</c> line in <path>/etc/modules.d/alsa</path>. For instance, for the
571 <c>snd-via82xx</c>:
572 </p>
573
574 <pre caption="Adding the joystick parameter">
575 alias snd-card-0 snd-via82xx
576 options snd-via82xx joystick=1
577 </pre>
578
579 </body>
580 </section>
581 <section>
582 <title>More links...</title>
583 <body>
584
585 <p>
586 You could check these for additional info:
587 </p>
588
589 <ul>
590 <li>
591 <uri link="http://www.gentoo.org/doc/en/desktop.xml">The Gentoo Linux
592 Desktop Configuration Guide</uri>
593 </li>
594 <li>
595 <uri link="http://www.alsa-project.org">ALSA Project Homepage</uri>
596 </li>
597 <li>
598 <uri link="http://www.alsa-project.org/documentation.php3">ALSA Users
599 Documentation</uri>
600 </li>
601 <li>
602 <uri link="http://www.djcj.org">ALSA Howto's and FAQ's</uri>
603 </li>
604 <li>
605 <uri link="http://tldp.org/HOWTO/Sound-HOWTO/index.html">Linux Sound
606 HOWTO</uri>
607 </li>
608 <li>
609 <uri link="http://linux-sound.org/">Sound and MIDI Software For Linux</uri>
610 </li>
611 </ul>
612
613 </body>
614 </section>
615 </chapter>
616 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20