Subject: Linux Sound HOWTO
From: [email-masked] (Jeff Tranter)
Newsgroups: comp.os.linux.announce,comp.os.linux.help

Archive-name: linux/howto/sound
Last-modified: 1 Feb 94

The Linux Sound HOWTO
by Jeff Tranter, <[email-masked]>
v1.2, Last Modified 1 February 1994

---------------------------------------------------------------------------

INDEX

0    Introduction
0.1    Acknowledgments
0.2    New versions of this document
0.3    Feedback
0.4    Other sources of information
0.5    Version Information
1    Supported Sound Hardware
1.1    Sound Cards
1.2    PC Speaker
1.3    Parallel Port
2    Configuring Linux for Sound Support
2.1    Installing Sound Card
2.2    Configuring Kernel
2.4    Creating Device Files
2.4    Testing Configuration
3    Applications Supporting Sound
3.1    Tools and Utilities
3.2    Games
4    Answers To Frequently Asked Questions

------------------------------------------------------------------------
0 Introduction

This HOWTO document describes sound support for Linux -- how to
configure the kernel, what applications run under Linux that support
sound, and answers to frequently asked questions about sound
cards. The intent is to bring new users up to speed more quickly and
reduce the amount of traffic in the usenet news groups.

The scope is limited to the aspects of sound cards pertaining to
Linux. See the other documents listed in section 0.4 for more
general information on sound cards.

0.1  Acknowledgments

Much of this information came from the Readme files provided with the
sound driver source code, by Hannu Savolainen. Thanks go to Hannu and
the many other people who developed the Linux kernel sound drivers and
utilities.

0.2  New versions of this document

New versions of this document will be periodically posted to
comp.os.linux.announce. They will also be uploaded to the various
anonymous ftp sites that archive such information including
sunsite.unc.edu:/pub/Linux/docs/HOWTO.

0.3  Feedback

If you have and suggestions, corrections, or comments on the HOWTO,
please send them to the author and I will try to incorporate them in
the next release.

0.4  Other sources of information

The following FAQs are regularly posted to the usenet newsgroup
news.announce as well as being archived at the site rtfm.mit.edu in
the directory /pub/usenet/news.answers:

PCsoundcards/generic-faq            Generic PC Soundcard FAQ
PCsoundcards/soundcard-faq          comp.sys.ibm.pc.soundcard FAQ
PCsoundcards/gravis-ultrasound/faq  Gravis Ultrasound FAQ
audio_fmts/part1                    Audio file format descriptions
audio_fmts/part2                    Audio file format descriptions

These FAQs also list several product specific mailing lists and
archive sites.

The following Usenet news groups discuss sound and/or music related
issues:

alt.binaries.sounds.misc       Digitized sounds and software
alt.binaries.sounds.d          Discussion and follow-up group
alt.binaries.multimedia        Multimedia sounds and software
alt.sb.programmer              Soundblaster programming topics
comp.multimedia                Multimedia topics
comp.music                     Computer music theory and research
comp.sys.ibm.pc.soundcard      IBM PC soundcard topics

The Linux Activists mailing list has a SOUND channel. To find out how
to join the mailing list, send mail to
"[email-masked]".

The Readme files included with the kernel sound driver source code
contain useful information about the sound card drivers. These can
typically be found in the directory "/usr/src/linux/drivers/sound".

The Linux Software Map (LSM) is an invaluable reference for locating
Linux software. Searching the LSM for keywords such as "sound" is a
good way to identify applications related to sound hardware. The LSM
can be found on various anonymous FTP sites, including
sunsite.unc.edu:/pub/Linux/docs/LSM.gz

0.5  Version Information

At time of writing, the latest Linux sound driver was version 2.4,
and was included as part of the Linux kernel version 0.99 ALPHA-pl14t
and later.

------------------------------------------------------------------------
1 Supported Sound Hardware

1.1 Sound Cards

The following sound cards are supported by the Linux kernel:

- MPU-401 MIDI interface
- AdLib
- SoundBlaster (1.0-2.0) and compatibles, including ThunderBoard and Ati
  Stereo F/X.
- SoundBlaster Pro and SoundBlaster Pro 2
- SoundBlaster 16 (this is a BETA test version)
- ProAudioSpectrum 16 (The original ProAudioSpectrum and the
  ProAudioSpectrum+ are not supported and will probably remain
  unsupported)
- Gravis UltraSound

The Linux kernel supports the SCSI port provided on some sound cards
(e.g. ProAudioSpectrum 16).

The Linux kernel version 0.99pl14x and later has support for CD-ROM
drives attached to the Soundblaster Pro and SoundBlaster 16 CD-ROM
port.  The drivers can also be added to earlier kernels as a
patch. Check the Linux Software Map for "sbpcd".

A Kernel patch to support joystick ports, including those provided on
some sound cards, is also available. The latest version can be found
in tsx-11.mit.edu:/pub/linux/patches/joystick-0.5.tar.z (these patches
may not apply cleanly as they were written for the 0.99pl9 kernel).

1.2 PC Speaker

An alternate sound driver is available that requires no additional
sound hardware; it uses the internal PC speaker. It is mostly software
compatible with the sound card driver, but, as you might expect,
provides much lower quality output and has much more CPU overhead. The
results seem to vary, being dependent on the characteristics of the
loudspeaker.

For more information, see the documentation provided with the
release.

The current version is 0.4, and can be found at
ftp.informatik.hu-berlin.de:pub/os/linux/hu-sound/pcsndrv-0.4.tar.z as
well as many other Linux archive sites.

1.3 Parallel Port

Another option it to build a digital to analog converter using the
parallel port. This provides better sound quality but still has a lot
of CPU overhead. The PC sound driver package mentioned above supports
this, and includes instructions for building the necessary hardware.

------------------------------------------------------------------------
2 Configuring Linux for Sound Support

Configuring Linux to support sound involves the following steps:

- installing a sound card
- configuring and building the kernel for sound support
- creating the device files
- testing the installation

2.1 Installing Sound Card

Follow the instructions provided with your sound card. Be sure to note
down the jumper settings for IRQ, DMA channel, etc... If you are
unsure, use the factory defaults. Try to avoid conflicts with other
devices (e.g. ethernet cards) if possible.

2.2 Configuring Kernel

If you are using a recent kernel (0.99pl14 or later), the sound
drivers are included with the kernel release. Follow the usual
procedure for building the kernel. When you run "make config", a
configuration program will ask you what sound card options you want.

If you are upgrading from an older sound driver, remove any old copies
of /usr/include/sys/soundcard.h and /usr/include/sys/ultrasound.h (if
they exist). Then make sure that /usr/include/sys/soundcard.h is a
file containing just the line #include <linux/soundcard.h> and
/usr/include/sys/ultrasound.h is a file containing just the line
#include <linux/ultrasound.h>.

It's good idea to read the Readme* files in the kernel drivers/sound
directory since there could be some last minute information. The file
CHANGELOG contains a list of enhancements and new features since the
previous version.

2.4 Create Device Files

Once the kernel is configured, you need to create the sound device
files. The easiest way to do this is to cut the short shell script
from the end of the file /usr/src/linux/drivers/sound/Readme.linux,
and run it as root.

2.4 Testing Configuration

You can now follow these steps to verify the sound hardware and
software:

1. Reboot with the new kernel

Follow your usual procedure for installing and rebooting the new
kernel (keep the old kernel around in case of problems, of course).

2. Verify that sound card is recognized during kernel initialization

Check for a message such as the following on powerup:

    <6>snd2 <SoundBlaster Pro 3.2> at 0x220 irq 5 drq 1
    <6>snd1 <Yamaha OPL-3 FM> at 0x388 irq 0 drq 0

This should match your sound card type and jumper settings.

The driver may also display some error messages and warnings during
boot. Watch for these when booting the first time after configuring
the sound driver.

If no sound card is detected when booting, there are two possible
reasons:

1) The configuration of the driver is incorrect and the driver was not
able to detect your card in the given I/O address, or

2) The sound driver was configured to be inactive or you booted with an
old kernel (a common error).

3. Check device file /dev/sndstat

Reading the sound driver status device file should provide additional
information on whether the sound card driver initialized
properly. Sample output should look something like this:

% cat /dev/sdndstat

Sound Driver:2.3b (Tue Jan 4 18:14:00 EST 1994 root@fizzbin.)
Config options: 1aa2

HW config:
Type 2: SoundBlaster at 0x220 irq 5 drq 1
Type 1: AdLib at 0x388 irq 0 drq 0

PCM devices:
0: SoundBlaster Pro 3.2

Synth devices:
0: Yamaha OPL-3

Midi devices:
0: SoundBlaster

Mixer(s) installed

If the cat command displays "No such device", the sound driver is not
active in the kernel.

If the printout contains no devices (PCM, Synth or MIDI), your
soundcard was not detected. Verify that the "HW config" section
contains correct information.

4. Play a simple sound file

Get hold of a sample sound file, and send it to the sound device as
a basic check of sound output, e.g.

% cat endoftheworld >/dev/dsp
% cat crash.au >/dev/audio

Some sample sound files can be obtained from the file
snd-data-0.1.tar.Z

5. Verify sound recording

If you have sound input capability, you can do a quick test of this
using commands such as the following:

# record 4 seconds of audio from microphone
% dd bs=8k count=4 </dev/audio >sample.au
# play back sound
% cat sample.au >/dev/audio

If these tests pass, you can be reasonably confident that the sound
hardware and software are working. If you experience problems, read
section 4 of this document.

------------------------------------------------------------------------
3 Applications Supporting Sound

This section lists a sampling of some of the more important tools,
utilities, and games that run under Linux and support sound. The Linux
Software Map should be consulted for the latest version and archive
sites for these files.

3.1 Tools and Utilities

adagio
- adagio score file player ("ad")
- MIDI file player ("mp")
- includes XView GUI version ("xmp")
- "mp" also has limited ability to play Amiga mod files

aumix
- ncurses based (colour) utility for controlling volume and mixing of
  sound sources
- also an experimental dB level meter

auplay
- a standalone program that allows playing Sun .au files through PC
  speaker without any kernel support
- this was the precursor to the PC speaker sound driver package
  (pcsndrv)

glib
- FM synthesizer library and patch editor ("glib")
- "xgl" is an OpenLook GUI version of "glib"
- contains some documentation on programming AdLib/SoundBlaster FM
  music chips

lsox
- sound file conversion utility ("sox")
- read/writes many sound formats
- provides conversion and effects
- also supports playing sound files ("play")

ogi
- speech data manipulation tools

pcsndrv
- kernel sound driver that supports PC speaker
- mostly compatible with kernel sound card driver
- also supports printer parallel port D/A converter
- "pcsel" utility to select which sound device to use
- "vplay" and "vrec" for playing and recording sound files
- includes explanation of how PC sound driver works

rsynth
- speech synthesizer uses synthesized instead of sampled
  phonemes
- good quality speech (with a British accent), but slow on a machine
  without a math coprocessor (e.g. 3 minutes to generate 4 words)

snd-data-0.1
- various sound files (sampled sounds, mod files, patches, etc...)

snd-driv-2.0
- VoxWare kernel drivers for sound cards
- now included in Linux kernel distribution as of 0.99pl14
- only really needed if building for OS other than Linux

snd-util-2.3
- various sound utilities
- some of these are obsolete and replaced by Adagio, Tracker, etc...

speak
- speech synthesis program
- very crude (uses 42 fixed, sampled phonemes)
- somewhat entertaining

tracker
- Amiga mod file player ("tracker")
- command line interface only

wavplay
- plays .wav sound files ("play")
- Sox is probably better (supports more file types)
- also an X interface version ("xplay")
- to work with the latest sound driver, need to apply patch found in
  wavplay021_patch.tar.gz

3.2 Games

The following games support sound:

b-dash
- a clone of B*ulderDash
- see sunsite:/pub/Linux/games/bdash021b.tgz

xboing
- "breakout" type arcade game
- see sunsite:/pub/Linux/X11/games/xboing-1.5-bin.tar.gz)

------------------------------------------------------------------------
4 Answers To Frequently Asked Questions

4.1 What are the various sound device files?

/dev/audio     - Sun workstation compatible audio device (read/write)
                 (only a partial implementation, does not support Sun
                 ioctl interface, just u-law encoding)
/dev/dsp       - digital sampling device (read/write)
/dev/mixer     - sound mixer
/dev/sequencer - MIDI, FM, and GUS access
/dev/midi      - MIDI device (not yet implemented in current sound driver)
/dev/sndstat   - displays sound driver status when read
/dev/audio1    - for second sound card
/dev/dsp1      - for second sound card

The PC speaker driver provides the following devices:

/dev/pcaudio    - equivalent to /dev/audio
/dev/pcsp       - equivalent to /dev/dsp
/dev/pcmixer    - equivalent to /dev/mixer

4.2 How can I play a sound sample?

Sun workstation (.au) sound files can be played by sending them to the
/dev/audio device. Raw samples can be send to /dev/dsp. Using a
program such as "play" is preferable, as it will recognize most file
types and set the sound card to the correct sampling rate, etc..

4.3 How can I record a sample?

Reading /dev/audio or /dev/dsp will return sampled data that can be
redirected to a file. A program such as "vrec" makes it easier to
control the sampling rate, duration, etc...

4.4 Can I have more than one sound card?

Up to two sound cards is supported. It's possible to install a
Gravis UltraSound or MPU-401 with a SoundBlaster, SoundBlaster Pro,
SoundBlaster16 or ProAudioSpectrum16. It's NOT possible to have a
ProAudioSpectrum16 and SoundBlaster at the same time (PAS16 has a SB
emulator in it). It's also not possible to have more than one card of
the same type at the same time -- for example, a GUS + GUS combination
is not possible.

You can change the sound card configuration parameters at boot time
using command line options from a boot loader such as LILO. See the
kernel sound driver file Readme.linux for details.

4.5 I get the error "/dev/???????: No such file or directory" when
    accessing a sound device.

You need to create the sound driver device files. See section 2.4.

4.6 I get the error "/dev/???????: No such device" when accessing a
    sound device.

You have not booted with a kernel containing the sound driver or the
I/O address configuration doesn't match your hardware.

4.7 A sound sample plays for a second and then stops completely and/or
    reports an error message about missing IRQ or "DMA Timed out".

You have incorrect IRQ or DMA channel settings. Verify that the kernel
configuration matches the sound card jumper settings and that they do
not conflict with some other card.

4.8 There are pauses in the playback of the module player (str,
    tracker)

Playing mod files requires considerable CPU power. You may have too
many processes running or your computer may be too slow to play in
real time. Your options are to:

  - try playing with a lower sampling rate or in mono mode
  - eliminate other processes
  - buy a faster computer
  - buy a more powerful sound card (e.g. Gravis Ultrasound)

Sometimes (very rarely) an IRQ conflict can cause similar problems
with SoundBlaster cards.

4.9 I get compile errors when compiling applications that support
    sound.

The version 1.0c and earlier sound driver used a different and
incompatible ioctl() scheme. Obtain newer source code or make the
necessary changes to adapt it to the new sound driver. See the sound
driver Readme file for details.

Also ensure that you have used the latest version of soundcard.h (and
ultrasound.h) when compiling the application. See the installation
instructions at beginning of this text.

4.10 I get segmentation violations when running sound application
     binaries that worked previously

This is probably the same problem described in section 4.8.

4.11 I have problems with Tracker 3.10

Version 3.10 of tracker contains some bugs. Try to obtain version 3.19
from an archive site, or wait until version 4.0 is out.

4.12 What known bugs or limitations are there in the sound driver?

See the Readme and CHANGELOG files included with the sound driver
kernel source.

4.13 What version of the sound driver I should use?

If you are using version 1.0c or earlier, you definitely need to
upgrade. Version 1.0c is not compatible with the applications written
for version 2.0 or later.

There have been no significant changes after version 2.0, so if you
don't have problems and that particular version fulfills your
requirements, there are no compelling reasons to move to a more recent
version (this should be true at least until September 1994).

The latest official version is in the latest Linux kernel
distribution.  There may also be some test and prototype versions
lying around. If the version number is smaller than 2.9, the version
should be quite safe. Any driver release having a version number of
the form 2.99.XX is an incompletely implemented and experimental test
release.

If you are interested about development of the sound driver, join the
SOUND channel (see section 0.4).

4.14 What do all the sound driver configuration options mean?

During configuration of the sound driver, a "configure" program is
compiled and executed. This program asks you some questions and then
generates the header file "local.h" that defines the sound card
configuration.

The configuration file local.h defines (or undefines) the following
symbols:

Symbol			Meaning
======			=======
KERNEL_SOUNDCARD        enable/disable sound driver
CONFIGURE_SOUNDCARD     enable/disable sound driver
EXCLUDE_PAS		ProAudioSpectrum support
EXCLUDE_SB		SoundBlaster support
EXCLUDE_ADLIB		AdLib support
EXCLUDE_GUS		GravisUltrasound support
EXCLUDE_MPU401		MPU-401 MIDI interface support
EXCLUDE_SBPRO		SoundBlaster Pro support
EXCLUDE_SB16		SoundBlaster 16 support
EXCLUDE_AUDIO		Digitized voice support
EXCLUDE_MIDI		MIDI interface support
EXCLUDE_YM3812		FM synthesizer (YM3812/OPL-3) support
EXCLUDE_SEQUENCER	MIDI sequencer support
EXCLUDE_PRO_MIDI	SoundBlaster Pro MIDI support
EXCLUDE_CHIP_MIDI	MIDI on CHIP support
SBC_IRQ			SoundBlaster IRQ number
SBC_DMA			SoundBlaster DMA channel
SB16_DMA		SoundBlaster 16 DMA channel
SB16_MIDI_BASE		base address of SoundBlaster 16 MIDI port
PAS_IRQ			ProAudioSpectrum IRQ number
PAS_DMA			ProAudioSpectrum DMA channel
GUS_IRQ			Gravis Ultrasound IRQ number
GUS_DMA			GravisUltrasound DMA channel
GUS_BASE		base address of GravisUltrasound
MPU_IRQ			MPU-401 IRQ number
MPU_BASE		base address of MPU-401 port
DSP_BUFFSIZE 32768	DMA buffer size

Several other defines are also created, defining such things as the
sound driver revision level and the time and date when configure was
run.

There are other parameters that are not set by the configure program
(e.g. SoundBlaster i/o base address). If you need to change these,
edit the file sound_config.h

To disable the sound driver, run configure and answer "y" to the
question "Do you want to DISABLE the Sound Driver (n/y) ?"

4.15 What future enhancements are planned for the sound driver?

The sound driver is not just for Linux, it also supports, or will
support, other Intel-based Unix operating systems. The package is now
called "VoxWare".

Some of the enhancements being considered are:
- implementing MIDI support
- patch manager support
- document sound card driver (Hacker's Guide)
- support for ISC, SCO, BSD, SVR4 operating systems
- support for new sound cards
- miscellaneous bug fixes

4.16 Where are the sound driver ioctls() etc... documented?

The sound driver is not currently documented, other than the Readme
and source files in the kernel.  The interface to the kernel sound
drivers is defined in <linux/soundcard.h>.

For now you'll have to look at the source code for the sound drivers,
and/or other applications that use the sound card.

Hannu Savolainen is planning to write a Hacker's Guide to the sound
driver.

4.17 What CPU resources are needed to play or record without pauses?

There is no easy answer to this, as it depends on:
- whether using PCM sampling or FM synthesis
- sampling rate and sample size
- which application is used to play or record
- Sound Card hardware
- disk I/O rate, CPU clock speed, cache size, etc...

In general, any 386 machine should be able to play samples or FM
synthesized music on an 8 bit soundcard with ease.

Playing mod files, however, requires considerable CPU resources. Some
experimental measurements have shown that playing at 44kHz requires
more than 40% of the speed of a 486/50 and a 386/25 can hardly play
faster than 22 kHz. These are with an 8 bit card sound such as a
SoundBlaster. A card such as the Gravis Ultrasound card performs more
functions in hardware, and will require less CPU resources.

These statements assume the computer is not performing any other CPU
intensive tasks.

Converting sound files or adding effects using a utility such as Sox
is also much faster if you have a math coprocessor. The kernel driver
itself does not do any floating point calculations, though.