/[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.24 - (show annotations) (download) (as text)
Wed Dec 31 09:51:41 2003 UTC (10 years, 10 months ago) by neysx
Branch: MAIN
Changes since 1.23: +4 -4 lines
File MIME type: application/xml
#36872 (alsa-lib, not alsa-libs)

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

  ViewVC Help
Powered by ViewVC 1.1.20