Recording audio

In order to play or record sound, you must open a connection to a PCM playback or recording device.

The functions used to open a PCM device are:

snd_pcm_open_name()

Use this function when you want to open a specific hardware device and you know its name.

snd_pcm_open()

Use this function when you want to open a specific hardware device and you know its card and device number.

snd_pcm_open_preferred()

Use this function to open the user's preferred device. Using this function makes your app more flexible because you don't need to know the card and device numbers. The function can provide you with the card and device that it opened.

All of these functions set a PCM connection handle that you can use as an argument to all other PCM functions. This handle is analogous to a file stream handle. It's a pointer to a snd_pcm_t structure, which is an opaque data type.

These functions, like others in the QSA API, work for both record and playback channels. They take as an argument a channel direction, which is one of:

• SND_PCM_OPEN_CAPTURE
• SND_PCM_OPEN_PLAYBACK

The following code sample uses these functions to open a playback device:

When a card and device number are specified, the code opens a connection to that specific PCM playback device. When a card is not specified, the code creates a connection to the preferred PCM playback device, then snd_pcm_open_preferred() stores the card and device numbers in the given variables.

if (card == -1)
{
    if ((rtn = snd_pcm_open_preferred (&pcm_handle,
                  &card, &dev,
                  SND_PCM_OPEN_PLAYBACK)) < 0)
        return err ("device open");
}
else
{
    if ((rtn = snd_pcm_open (&pcm_handle, card, dev,
                  SND_PCM_OPEN_PLAYBACK)) < 0)
        return err ("device open");
}

Before you can begin playing or capturing a sound stream, you must let the device know the format of the data that you're about to send to it or that you want to receive from it. You can define the data format by creating a structure and using it to call snd_pcm_channel_params() or snd_pcm_plugin_params(). For more information, see PCM plugin converters.

Both of these functions will fail when the device cannot support the data parameters that you set, or when all of the subchannels of the device are currently in use.

The functions used to determine the current capabilities of a PCM device are:

snd_pcm_plugin_info()

Use the plugin converters. When the hardware has a free subchannel, the capabilities that are returned are extensive because the plugin converters make any necessary conversion.

snd_pcm_channel_info()

Access the hardware directly. This function returns only what the hardware capabilities are.

When you configure the channel, a subchannel is allocated to your app. Stated another way, hundreds of apps can open a handle to a PCM device with only one subchannel, but only one can configure it. After a client app allocates a subchannel, it isn't returned to the free pool until the handle is closed. One result of this mechanism is that, from moment to moment, the capabilities of a PCM device change as other applications allocate and free subchannels. Additionally configuring and allocating a subchannel changes its state from SND_PCM_STATUS_NOTREADY to SND_PCM_STATUS_READY.

If the function succeeds, all specified parameters are accepted and are guaranteed to be in effect, except for the frag_size parameter, which is only a suggestion to the hardware. The hardware may adjust the fragment size, based on hardware requirements. For example, if the hardware can't deal with fragments crossing 64-kilobyte boundaries, and the suggested frag_size is 60 KB, the driver adjusts it to 64 KB.

Another aspect of configuration is determining how big to make the hardware buffer. This size determines how much latency that the app has when sending data to the driver or reading data from it. The hardware buffer size is determined by multiplying the frag_size by the max_frags parameter, so for the app to know the buffer size, it must determine the actual frag_size that the driver is using.

You can determine the actual frag_size that the driver is using by calling snd_pcm_channel_setup() or snd_pcm_plugin_setup(), depending on whether or not your application is using the plugin converters. Both of these functions take a pointer to a snd_pcm_channel_setup_t structure that they fill with information about how the channel is configured, including the true frag_size.

The libasound library supports devices with up to eight voices. Configuration of the libasound library is based on the maximum number of voices that are supported in hardware. If the numbers of source and destination voices are different, then snd_pcm_plugin_params() creates an instance of a voice converter.

The default voice conversion behavior is as follows:

You can use the voice conversion API to configure the conversion behavior and place any source channel in any destination channel slot:

snd_pcm_plugin_get_voice_conversion()

Get the current voice conversion structure for a channel

snd_pcm_plugin_set_voice_conversion()

Set the current voice conversion structure for a channel

The snd_pcm_voice_conversion_t structure, which is defined below, controls the actual conversion:

typedef struct snd_pcm_voice_conversion
{       
   uint32_t     app_voices;
   uint32_t     hw_voices;
   uint32_t     matrix[32];
} snd_pcm_voice_conversion_t

The matrix member forms a 32-by-32-bit array that specifies how to convert the voices. The array is ranked with rows representing app voices, with voice 0 first. The columns represent hardware voices, with the low voice being Least Significant Bit (LSB) aligned and increasing right to left.

For example, consider a mono app stream sent to a 4-voice hardware device. A bit array of:

matrix[0] = 0x1;  //  00000001

causes the sound to be output on only the first hardware channel. A bit array of:

matrix[0] = 0x9;   // 00001001

causes the sound to be output on the first and last hardware channel.

Another example is a stereo app stream to a 6-channel (5.1) output device. A bit array of:

matrix[0] = 0x1;  //  00000001
matrix[1] = 0x2;  //  00000010

causes the sound to be output on only the front two channels, while:

matrix[0] = 0x5;  //  00000101
matrix[1] = 0x2;  //  00000010

causes the stream signal to be output on the first four channels (likely the front and rear pairs, but not on the center or Low-Frequency Effects (LFE) channels). The bitmap that's used to describe the hardware (the columns) depends on the hardware. Further, the actual hardware that it's running on determines how the channels are mapped. For example:

• When the hardware arranges the channels such that the center channel is the third channel, then bit 2 represents the center.
• When the hardware arranges the channels such that the rear left is the third channel, then bit 2 represents the rear left.

When you call snd_pcm_plugin_get_voice_conversion() or snd_pcm_plugin_set_voice_conversion() before the voice conversion plugin has been instantiated, the functions fail and return -ENOENT.

Before you can begin playing or recording a sound stream, you must prepare the allocated PCM subchannel to run. Call one of the following functions to prepare the allocated PCM subchannel:

• snd_pcm_plugin_prepare() if you're using the plugin interface
• snd_pcm_channel_prepare(), snd_pcm_capture_prepare(), or snd_pcm_playback_prepare() if you aren't using the plugin interface

The snd_pcm_channel_prepare() function calls snd_pcm_capture_prepare() or snd_pcm_playback_prepare(), depending on the channel direction that you specify.

This step and the SND_PCM_STATUS_PREPARED state are required to correctly handle buffer underrun conditions when playing a sound stream and buffer overrun conditions when capturing a sound stream. For more information, see PCM subchannel stops during playback or PCM subchannel stops during recording.

When you've finished playing or recording audio, you must close the subchannel by calling snd_pcm_close(). The call to snd_pcm_close() releases the subchannel and closes the handle.

To open a connection to the mixer device, call snd_mixer_open(). You can select the card and mixer device number to open by passing them as parameters to the function. Most sound cards have one mixer, but there may be additional mixers in special cases.

The snd_mixer_open() function returns a mixer handle that you can use as an argument for additional function calls that are applied to this device. The mixer handle is a pointer to a snd_mixer_t structure, which is an opaque data type.

The best way to control a mixer group is to use the read-modify-write technique. Using this technique, you can examine the group capabilities and ranges before adjusting the group.

To read the properties and settings of a mixer group, your app must identify the group. Every mixer group has a name, but because two groups may have the same name, a name alone isn't enough to identify a specific mixer group. In order to make groups unique, mixer groups are identified by the combination of name and index. The index is an integer that represents the instance number of the name. In most cases, the index is 0. In the case of two mixer groups with the same name, the first has an index of 0, and the second has an index of 1.

To read a mixer group, call the snd_mixer_group_read() function. The arguments to this function are the mixer handle and the group control structure. The group control structure is of type snd_mixer_group_t.

To read a particular group, you must set its name and index in the gid substructure (see snd_mixer_gid_t) before making the call. If the call to snd_mixer_group_read() succeeds, the function fills in the structure with the group's capabilities and current settings.

Now that you have the group capabilities and current settings, you can change them before you write them back to the mixer group.

To write the changes to the mixer group, call snd_mixer_group_write(), passing as arguments the mixer handle and the group control structure.

In a typical mixer, there are many playback mixer group controls. Several of these controls manage the volume and mute functionality of the stream that your app is playing.

Consider what happens when you increase your .wav file volume by using the Master group. Other streams, such as those playing an .mp3 file, are affected as well. The best group to use is the PCM subchannel because it affects only your stream. However, on some cards, a subchannel group may not exist, so you need a better way to find the best group.

The best way to find the best group for a PCM subchannel is to let the driver (for example, the driver author) do it for you. You can obtain the identity of the best mixer group for a PCM subchannel by calling snd_pcm_channel_setup() or snd_pcm_plugin_setup(), as shown:

memset (&setup, 0, sizeof (setup));
memset (&group, 0, sizeof (group));
setup.channel = SND_PCM_CHANNEL_PLAYBACK;
setup.mixer_gid = &group.gid;
if ((rtn = snd_pcm_plugin_setup (pcm_handle, &setup)) < 0)
{
    return -1;
}

The best group may change depending on the state of the PCM subchannel. The PCM subchannels aren't allocated to an app until the parameters of the channel are established. Similarly, the subchannel mixer group isn't available until the subchannel is allocated. Using the Sound Blaster Live! example, the best mixer group before the subchannel is allocated is the PCM group and, after allocation, the PCM subchannel group.

You can get a complete list of mixer groups by calling snd_mixer_groups(). You call snd_mixer_groups() twice: once to get the total number of mixer groups, then a second time to read their IDs.

The arguments to the call are the mixer handle and an snd_mixer_group_t structure. The structure contains a pointer to where the groups' identifiers are stored, which is an array of snd_mixer_gid_t structures, and the size of that array. The call fills in the structure with the number of identifiers that were stored, and indicates when some couldn't be stored because they would exceed the storage size.

Here's an example where the snd_strerror() function prints error messages for the sound functions:

while (1)
{
    memset (&groups, 0, sizeof (groups));
    if ((ret = snd_mixer_groups (mixer_handle, &groups) < 0))
    {
       fprintf (stderr, "snd_mixer_groups function - %s",
                snd_strerror (ret));
    }

    mixer_n_groups = groups.groups_over;
    if (mixer_n_groups > 0)
    {
        groups.groups_size = mixer_n_groups;
        groups.pgroups = (snd_mixer_gid_t *) malloc (
           sizeof (snd_mixer_gid_t) * mixer_n_groups);

        if (groups.pgroups == NULL)
            fprintf (stderr, "Unable to malloc group array - %s",
                     strerror (errno));

        groups.groups_over = 0;
        groups.groups = 0;

        if (snd_mixer_groups (mixer_handle, &groups) < 0)
            fprintf (stderr, "No Mixer Groups ");

        if (groups.groups_over > 0)
        {
            free (groups.pgroups);
            continue;
        }
        else
        {
            printf ("sorting GID table \n");
            snd_mixer_sort_gid_table (groups.pgroups, mixer_n_groups,
                snd_mixer_default_weights);
            break;
        }
    }
}

By default, all mixer apps are required to keep current with all mixer changes. Keeping current with all mixer changes is done by queuing a mixer-change event on all apps other than the app that is making the change. The driver queues these events on all apps that have an open mixer handle, unless the app uses the snd_mixer_set_filter() function to mask out events that it's not interested in.

Apps use the snd_mixer_read() function to read the queued mixer events. The arguments to these functions are the mixer handle and a structure of callback functions to call based on the event type.

static void mixer_callback_group (void *private_data,
                                  int cmd,
                                  snd_mixer_gid_t * gid)
{
    switch (cmd)
    {
    case SND_MIXER_READ_GROUP_VALUE:
        printf ("Mixer group %s %d changed value \n",
                gid->name, gid->index);
        break;

    case SND_MIXER_READ_GROUP_ADD:
        break;

    case SND_MIXER_READ_GROUP_REMOVE:
        break;
    }
}

int mixer_update (int fd, void *data, unsigned mode)
{
    snd_mixer_callbacks_t callbacks = { 0, 0, 0, 0 };

    callbacks.group = mixer_callback_group;
    snd_mixer_read (mixer_handle, &callbacks);
    return (Pt_CONTINUE);
}

int main (void)
{
    snd_mixer_t *mixer_handle;
    int ret;

    if ((ret = snd_mixer_open (&mixer_handle, 0, 0) < 0))
        printf ("Unable to open/read mixer - %s",
                snd_strerror (ret));

    PtAppAddFd (NULL,
                snd_mixer_file_descriptor (mixer_handle),
                Pt_FD_READ, mixer_update, NULL);
    ...
}

Closing the mixer device frees all of the resources that are associated with the mixer handle and shuts down the connection to the sound mixer interface. To close the mixer handle, call snd_mixer_close() function.