Introduction to Sound Programming with ALSA

Make maximum use of all the functionality in the new 2.6 kernel sound architecture using a simple API.
Device Naming

The library API works with logical device names rather than device files. The device names can be real hardware devices or plugins. Hardware devices use the format hw:i,j, where i is the card number and j is the device on that card. The first sound device is hw:0,0. The alias default refers to the first sound device and is used in all of the examples in this article. Plugins use other unique names; plughw:, for example, is a plugin that provides access to the hardware device but provides features, such as sampling rate conversion, in software for hardware that does not directly support it. The dmix and dshare plugins allow you to downmix several streams and split a single stream dynamically among different applications.

Sound Buffers and Data Transfer

A sound card has a hardware buffer that stores recorded samples. When the buffer is sufficiently full, it generates an interrupt. The kernel sound driver then uses direct memory access (DMA) to transfer samples to an application buffer in memory. Similarly, for playback, another application buffer is transferred from memory to the sound card's hardware buffer using DMA.

These hardware buffers are ring buffers, meaning the data wraps back to the start when the end of the buffer is reached. A pointer is maintained to keep track of the current positions in both the hardware buffer and the application buffer. Outside of the kernel, only the application buffer is of interest, so from here on we discuss only the application buffer.

The size of the buffer can be programmed by ALSA library calls. The buffer can be quite large, and transferring it in one operation could result in unacceptable delays, called latency. To solve this, ALSA splits the buffer up into a series of periods (called fragments in OSS/Free) and transfers the data in units of a period.

A period stores frames, each of which contains the samples captured at one point in time. For a stereo device, the frame would contain samples for two channels. Figure 1 illustrates the breakdown of a buffer into periods, frames and samples with some hypothetical values. Here, left and right channel information is stored alternately within a frame; this is called interleaved mode. A non-interleaved mode, where all the sample data for one channel is stored followed by the data for the next channel, also is supported.

Figure 1. The Application Buffer

Over and Under Run

When a sound device is active, data is transferred continuously between the hardware and application buffers. In the case of data capture (recording), if the application does not read the data in the buffer rapidly enough, the circular buffer is overwritten with new data. The resulting data loss is known as overrun. During playback, if the application does not pass data into the buffer quickly enough, it becomes starved for data, resulting in an error called underrun. The ALSA documentation sometimes refers to both of these conditions using the term XRUN. Properly designed applications can minimize XRUN and recover if it occurs.

A Typical Sound Application

Programs that use the PCM interface generally follow this pseudo-code:

open interface for capture or playback
set hardware parameters
(access mode, data format, channels, rate, etc.)
while there is data to be processed:
   read PCM data (capture)
   or write PCM data (playback)
close interface

We look at some working code in the following sections. I recommend you compile and run these on your Linux system, look at the output and try some of the suggested modifications. The full listings for the example programs that accompany this article are available for download from ftp.linuxjournal.com/pub/lj/listings/issue126/6735.tgz.

Listing 1 displays some of the PCM data types and parameters used by ALSA. The first requirement is to include the header file that brings in the definitions for all of the ALSA library functions. One of the definitions is the version of ALSA, which is displayed.

The remainder of the program iterates through a number of PCM data types, starting with the stream types. ALSA provides symbolic names for the last enumerated value and a utility function that returns a descriptive string for a value. As you can see in the output, ALSA supports many different data formats, 38 for the version of ALSA on my system.

The program must be linked with the ALSA library, libasound, to run. Typically, you would add the option -lasound on the linker command line. Some ALSA library functions use the dlopen function and floating-point operations, so you also may need to add -ldl and -lm.

Listing 2 opens the default PCM device, sets some parameters and then displays the values of most of the hardware parameters. It does not perform any sound playback or recording. The call to snd_pcm_open opens the default PCM device and sets the access mode to PLAYBACK. This function returns a handle in the first function argument that is used in subsequent calls to manipulate the PCM stream. Like most ALSA library calls, the function returns an integer return status, a negative value indicating an error condition. In this case, we check the return code; if it indicates failure, we display the error message using the snd_strerror function and exit. In the interest of clarity, I have omitted most of the error checking from the example programs. In a production application, one should check the return code of every API call and provide appropriate error handling.

In order to set the hardware parameters for the stream, we need to allocate a variable of type snd_pcm_hw_params_t. We do this with the macro snd_pcm_hw_params_alloca. Next, we initialize the variable using the function snd_pcm_hw_params_any, passing the previously opened PCM stream.

We now set the desired hardware parameters using API calls that take the PCM stream handle, the hardware parameters structure and the parameter value. We set the stream to interleaved mode, 16-bit sample size, 2 channels and a 44,100 bps sampling rate. In the case of the sampling rate, sound hardware is not always able to support every sampling rate exactly. We use the function snd_pcm_hw_params_set_rate_near to request the nearest supported sampling rate to the requested value. The hardware parameters are not actually made active until we call the function snd_pcm_hw_params.

The rest of the program obtains and displays a number of the PCM stream parameters, including the period and buffer sizes. The results displayed vary somewhat depending on the sound hardware.

After running the program on your system, experiment and make some changes. Change the device name from default to hw:0,0 or plughw: and see whether the results change. Change the hardware parameter values and observe how the displayed results change.

Listing 3 extends the previous example by writing sound samples to the sound card to produce playback. In this case we read bytes from standard input, enough for one period, and write them to the sound card until five seconds of data has been transferred.

The beginning of the program is the same as in the previous example—the PCM device is opened and the hardware parameters are set. We use the period size chosen by ALSA and make this the size of our buffer for storing samples. We then find out that period time so we can calculate how many periods the program should process in order to run for five seconds.

In the loop that manages data, we read from standard input and fill our buffer with one period of samples. We check for and handle errors resulting from reaching the end of file or reading a different number of bytes from what was expected.

To send data to the PCM device, we use the snd_pcm_writei call. It operates much like the kernel write system call, except that the size is specified in frames. We check the return code for a number of error conditions. A return code of EPIPE indicates that underrun occurred, which causes the PCM stream to go into the XRUN state and stop processing data. The standard method to recover from this state is to use the snd_pcm_prepare function call to put the stream in the PREPARED state so it can start again the next time we write data to the stream. If we receive a different error result, we display the error code and continue. Finally, if the number of frames written is not what was expected, we display an error message.

The program loops until five seconds' worth of frames has been transferred or end of file read occurs on the input. We then call snd_pcm_drain to allow any pending sound samples to be transferred, then close the stream. We free the dynamically allocated buffer and exit.

We should see that the program is not useful unless the input is redirected to something other than a console. Try running it with the device /dev/urandom, which produces random data, like this:


./example3 < /dev/urandom

______________________

Comments

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

CROSS_COMPILE

Anonymous's picture

Hi,

I compile the source codes on my pc(ubuntu) with gcc play.c -o play -lasound and test with ./play < sample.raw. It works properly. But i want to use it on my beagleboarg(ARM platform). I tried to compile with
arm-none-linux-gcc play.c -o play -lasound
it doesn't work. It gives
/opt/arm-2009q1/bin/../lib/gcc/arm-none-linux-gnueabi/4.3.3/../../../../arm-none-linux-gnueabi/bin/ld: cannot find -lasound
collect2: ld returned 1 exit status

what is my mistake? Please help me.

Fatih

CROSS_COMPILE

rangel's picture

try: "strace ./play < sample.raw"
or "ldd play" and view if the correct path of library is linking

Volume needs to increase

djguha's picture

It is brilliant tutorial for beginners.I have run the capture and playback code.I noticed my volume level is very low when I capture my voice followed by playback code.But if I playback http://freewavesamples.com/files/Roland-JD-990-Windchimes.wav file, the sound volume is very good.I have followed a code to get the Capability of /dev/dsp from: http://www.oreilly.de/catalog/multilinux/excerpt/ch14-09.htm .
Here is the output :
Information on /dev/dsp:

Defaults:
sampling rate: 8000 Hz
channels: 1
sample size: 8 bits
block size: 4097 bytes

Supported Formats:
mu-law
unsigned 8-bit (default)
signed 16-bit little-endian
signed 16-bit big-endian
signed 8-bit
unsigned 16-bit little-endian
unsigned 16-bit big-endian

Capabilities:
revision: 1
full duplex: yes
real-time: yes
batch: no
coprocessor: no
trigger: yes
mmap: yes

Modes and Limits:
Device Sample Minimum Maximum
Channels Size Rate Rate
-------- -------- -------- --------
1 8 1000 100000
1 16 1000 100000
2 8 1000 100000
2 16 1000 100000

Please let me know how do I increase volume while capturing from /dev/dsp.
With regards,
-- Guha.

Example 3

Milos's picture

Hi to all.... Very good article for ALSA bigginers. I was trying to run this example on my PC. I want to play my .wav file (I will use file bugs_bye.wav as my input) and to hear that. When I run this example ./example3 bugs_bye.wav program executes but I can't hear anything. I am using file descriptor of this file insted of 0 (stdin) when I call function read like this:
int fd = open( argv[1] , O_RDONLY );
......
rc = read(fd, buffer, size);

The rest is same as example 3. What am I wrong??? Can someone help??? I am little bit confused.

Milos

Very Much informative

Anonymous's picture

Thanks for this article

listing3

Anonymous's picture

hi,i have a problem,i'm verry new to alsa programming,i didn't understand exactly how listing3 works.how do i put data into application buffer,to be transmitted to the sound card???i assume that the program is running correctly,but i don't know what to do after i run the program.Can anyone help me??

Re: Listing 3

Anonymous's picture

Hello,

The program allocates a buffer,

buffer = (char *) malloc(size);

then in the loop it fills it from file descriptor 0,
i.e. stdin,

rc = read(0, buffer, size);

so to test, you could feed it something from the
command line.

It is set up for "CD" audio, 44100Hz, 2ch. I grabbed a sample here,

$ wget http://freewavesamples.com/files/Roland-JD-990-Windchimes.wav

I saved listing 3 as "listing3.c" and compiled,

$ gcc $(pkg-config --cflags --libs alsa) listing3.c -o listing3

Then to test,

$ cat Roland-JD-990-Windchimes.wav | ./listing3

If you wanted to generate your own sound, you could fill the buffer programmatically instead of reading from stdin.

Hope this helps.

jamie@goonathon.net

Kudoos and hats off for the Article

Anonymous's picture

Hi

I had been ssearching on net just to know how to start about with ALSA.

This article is simply great, starts from scratch building foundation and then takes you as far as you want to go..

Great work..

Regards
samir

question about one command of the program

manu's picture

hello,

I run your 4 programs coding in C with linux but i don't understand how does it work the next command :

snd_pcm_hw_params_get_period_time(params, &Val, &dir) who is used like that in Example 3 for example:

/* We want to loop for 5 seconds */
snd_pcm_hw_params_get_period_time(params,
&val, &dir);
/* 5 seconds in microseconds divided by
* period time */
loops = 5000000 / val;

If I add some lines of code, I can read the value of the variable "val" after and before the function " snd_pcm_hw_params_get_period_time(params, &val, &dir); ".

I can read that "val" before this function as a value 44099 (sample frequency minus 1), and after, "val" has the value 21333 at each time, whatever the others values enter as a parameters.

I don't understand how this function works and i would to know.

Would someone help me?

Thanks

Manu

5 sec

MK's picture

/* 5 seconds in microseconds divided by
* period time */
loops = 5000000 / val;

How did he calculate this?

how to read & play a sound file

Shubham's picture

hi,

I am new to ALSA programing. Could anyone tell how i can read & play a sound file using above example code for playback?

how to read & play a sound file

Anonymous's picture

You complie the example Listing 4 then plug the Headpone in the system.firsly check that your headphone is properly working by running the sound recorder program.after compiling code some output file is generated in the particular folder.
just start recording by typing ./.outfile name > sound.raw and record your voice through headphone for 5 sec.
For plaback compile code for playback in the seprate folder and run
./.outfile name

Converting to ALSA

Anonymous's picture

Firstly, this article is really good.

I need to write an application for FXS interface. the drivers are implements using ioctl system calls. How difficult is it to convert to ALSA API.
Or the otherway, what is to be done if i need to access these drivers in an application which is already supporting ALSA.

ok I just found it. for code

Elie's picture

ok I just found it. for code called 'alsa.c' it's

gcc alsa.c -lasound

Linking Libraries

Elie's picture

Umm... what libraries do i need to link? I tried the code (listings 3 & 4) and it compiled but didn't link. What gcc parameters need to be added?

(currently using Ubuntu Feisty 7.04)

undocumented bs wtf!

mark manning's picture

your second piece of example code has the following funciton call..

rc = snd_pcm_open(&handle, "default", SND_PCM_STREAM_PLAYBACK, 0);

looking at the API reference for this call we see that the last parameter in this call is int mode. Mode may be one of the following values.

SND_PCM_NONBLOCK or SND_PCM_ASYNC. The first of these is equal to 0x01 and the second is equal to 0x02. WHAT is this undocumented mode zero that your example code AND the alsa example code uses.

undocumented == BAD MOJO!

great article tho :)

i am working on a project

Anonymous's picture

i am working on a project that needs a simple voice recording to be saved to a file, before further processing can be done on it... i am new to alsa (sound programming in general).
i believe alsa and oss can accomplish what i want but i need further guidance.
thanks.

ALSA Duplex Working code

Santoshkumar's picture

Does any body tested ALSA duplex (Record and playback)? Can you please point the place where i can get some reference source code?

Thank you,
Santosh
santosh.pattar@gmail.com

Updated code for FC6?

William Estrada's picture

I read this article and tried to run the sample code. It did compile and run but the record program produces garbage/noise. Is there an update for a Fedora Core 6 kernel? What kind of sound file does this code produce, wav, au, etc?

I don't know if anyone is

Anonymous's picture

I don't know if anyone is reading this.

But there are a few problems.

It records as far as I can see, but I get a lot of random garbage data which I don't want when recording. Anything I record is messed up in random data.

I´ve tried Sound

David's picture

I´ve tried Sound Programming with ALSA in a seminar, but i´m afraid, it is just too difficult for me. But i have to point out that i´m progging since one year, so i think i need just a bit more time. patience is all :-)

in listing 2, dir should be initialized

Fabrice Pardo's picture

Very useful article.

In listing 2, you should replace
int dir;
by
int dir = 0;
or replace &dir by NULL later

In my first test case, dir was randomly initialized to a negative
value, giving as a result
rate = 44099 bps

Actually, the snd_pcm_hw_params_set_rate_near function is poorly documented.

Display format

MikeW's picture

It would be nice if the (fixed) page width were a little greater, without having to shrink the browser text size.

Hard to read code that's full of line wraps.

Problem in opening default device in listing2 of this article

Nagaraja S's picture

Hi guys am new to this ALSA, I downloaded all driver, library utils from www.alsa-project.com and i installed.

when i run the listing1 of this doc it went fine and when i tried to run the second listing it says like this.
Unable to open the default device No such file.And i am using slackware with linux 2.4.22
Please help me out guys.

Thanx in advance for help

Re: Introduction to Sound Programming with ALSA

JKCunningham's picture

Great article. I tried the first source and it worked fine, but the second bombed:

> ./listing_2
unable to set hw parameters: Invalid argument

Any idea why this would be? I didn't modify the source.

-Jeff

Problem in listing2 program Unable to open default device

Nagaraja's picture

Hi guys am new to this ALSA, I downloaded all driver, library utils from www.alsa-project.com and i installed.

when i run the listing1 of this doc it went fine and when i tried to run the second listing it says like this.
Unable to open the default device No such file.And i am using slackware with linux 2.4.22
Please help me out guys.

Thanx in advance for help

Re: Introduction to Sound Programming with ALSA

Pablo's picture

It happened the same to me. When I change the sampling frequency value to 48 kHz then I got the error message:
unable to set hw parameters: Invalid argument
For any other sampling frequency it works ok.

Pablo

It happened the same to me. W

Pablo's picture

It happened the same to me. When I change the sampling frequency value to 48 kHz then I got the error message:
unable to set hw parameters: Invalid argument
For any other sampling frequency it works ok.

Pablo

Re: Introduction to Sound Programming with ALSA

Anonymous's picture

Someone has posted a note at the Resources page
,
saying that the variable "dir" needs to be initialized to 0 (zero).
That seemed to solve my problems, at least.

Re: Introduction to Sound Programming with ALSA

Anonymous's picture

I am having the same problems with listing 4. (And it seems that others have too, see the Resources page.) In my case the problem seems to be the sampling frequency, if I change 44100 til 88200 the program will run.

What I really would like to know is whether this is a problem with the example program from the article (I did not modify it), a problem with ALSA (I use Debian Sarge with 2.6-kernel) or a problem with my sound card (SoundBlaster Live).

problem

Anonymous's picture

Hi,

I tried to run the codes under beagleboard. I got the error message:
unable to set hw parameters: Invalid argument
I change the sampling frequency from 44100 to 88200 even to 132300 as you said. This time it works but when i run
./example3 < /dev/urandom
this command it gives me veri bad sound like "CCcczzZZZZzzzrrttTtTT".

My beagleboards parameters are this : //my pc(ubuntu)

PCM handle name = 'default'
PCM state = PREPARED
access type = RW_INTERLEAVED
format = 'S16_LE' (Signed 16 bit Little Endian)
subformat = 'STD' (Standard)
channels = 2
rate = 44100 bps
period time = 5804 us //23219
period size = 256 frames //1024
buffer time = 743038 us //23219
buffer size = 32768 frames //1048576
periods per buffer = 128 frames //1024
exact rate = 44100/1 bps
significant bits = 16
tick time = 16 us
is batch = 0
is block transfer = 0 //1
is double = 0
is half duplex = 0
is joint duplex = 0
can overrange = 0
can mmap = 1 //0
can pause = 1
can resume = 1 //0
can sync start = 0

The parameters which are bold are difference between my pc(ubuntu).
Please Can you give me a suggestion how to modify the code?

Thx in Advance.

Fatih

problem

Anonymous's picture

Hi,

I tried to run the codes under beagleboard. I got the error message:
unable to set hw parameters: Invalid argument
I change the sampling frequency from 44100 to 88200 even to 132300 as you said. This time it works but when i run
./example3 < /dev/urandom
this command it gives me veri bad sound like "CCcczzZZZZzzzrrttTtTT".

My beagleboards parameters are this : //my pc(ubuntu)

PCM handle name = 'default'
PCM state = PREPARED
access type = RW_INTERLEAVED
format = 'S16_LE' (Signed 16 bit Little Endian)
subformat = 'STD' (Standard)
channels = 2
rate = 44100 bps
period time = 5804 us //23219
period size = 256 frames //1024
buffer time = 743038 us //23219
buffer size = 32768 frames //1048576
periods per buffer = 128 frames //1024
exact rate = 44100/1 bps
significant bits = 16
tick time = 16 us
is batch = 0
is block transfer = 0 //1
is double = 0
is half duplex = 0
is joint duplex = 0
can overrange = 0
can mmap = 1 //0
can pause = 1
can resume = 1 //0
can sync start = 0

The parameters which are bold are difference between my pc(ubuntu).
Please Can you give me a suggestion how to modify the code?

Thx in Advance.

Fatih

Re: Introduction to Sound Programming with ALSA

Anonymous's picture

A simple question: Why can't the ALSA developers make sure that ALSA provides sound support at least as good as OSS? After having tested it on a number of boards, it was always a pain in the neck to configure properly, and getting it to work, an adventure. I will stay with OSS until ALSA becomes much more user-friendly.

Re: Introduction to Sound Programming with ALSA

Anonymous's picture

Excellent informatiom. Now lets have a simple real time mixer with chnangeable effect to really show what ALSA + 2.6 Linux can do

Re: Introduction to Sound Programming with ALSA

Anonymous's picture

Yes, I agree, excellent article and a brilliant introduction to ALSA.

Keep up the good work!

Re: Introduction to Sound Programming with ALSA

Anonymous's picture

Informative article. More intros to popular or obscure libraries please!

Webinar
One Click, Universal Protection: Implementing Centralized Security Policies on Linux Systems

As Linux continues to play an ever increasing role in corporate data centers and institutions, ensuring the integrity and protection of these systems must be a priority. With 60% of the world's websites and an increasing share of organization's mission-critical workloads running on Linux, failing to stop malware and other advanced threats on Linux can increasingly impact an organization's reputation and bottom line.

Learn More

Sponsored by Bit9

Webinar
Linux Backup and Recovery Webinar

Most companies incorporate backup procedures for critical data, which can be restored quickly if a loss occurs. However, fewer companies are prepared for catastrophic system failures, in which they lose all data, the entire operating system, applications, settings, patches and more, reducing their system(s) to “bare metal.” After all, before data can be restored to a system, there must be a system to restore it to.

In this one hour webinar, learn how to enhance your existing backup strategies for better disaster recovery preparedness using Storix System Backup Administrator (SBAdmin), a highly flexible bare-metal recovery solution for UNIX and Linux systems.

Learn More

Sponsored by Storix