man pages section 7: Device and Network Interfaces

mixer(7I)

Name

mixer– audio mixer audio personality module interface

Synopsis

#include <sys/mixer.h>

OVERVIEW

The audio mixer extends the audio(7I) interface, allowing more then one process to play or record audio at the same time. Understanding the audio(7I) interface thoroughly is a prerequisite to understanding the mixer(7I) interface.

Backward Compatibility

It is possible to disable the mixing function and return to 100% backward compatibility with the audio(7I) interface. These two modes of operation are referred to as the mixer mode and the compatible mode. This is done by using either the mixerctl(1) or sdtaudiocontrol(1) applications, or by editing the audio driver's .conf file and then unloading and reloading the audio driver.

Multi-Stream Codecs

The audio mixer supports multi-stream Codecs. Examples of these Codecs are the Crystal Semiconductor 4410/4422 and the Aureal 8820/8830. These devices have DSP engines that provide sample rate conversion and other features. Each play/record channel is mapped to an individual channel straight into the Codec. The audio mixer does not perform sample rate or encoding conversion. (See below). However, the programming interfaces remain the same and applications cannot distinguish between multi-stream Codec and traditional Codec.

Buffer Size

An application can use the audio information structure to set the size of the play/record buffers. As with the audio(7I) interface, the audio mixer does not support changing of the play buffer size. Instead, the audio driver takes sound samples as it can handle them, regardless of how many are delivered to the driver with each write.

The audio mixer supports changing of the record buffer size. When captured by the audio driver, buffer size bytes are sent to the application for reading.

AUDIO FORMATS

See the audio(7I) manual page for a brief discussion of audio formats. To mix the various audio streams, the audio mixer must convert all audio formats to a common format. The following describes how the audio mixer deals with these different components.

Sample Rate

When /dev/audio is opened, the initial sample rate is 8KHz, as defined in audio(7I).

In mixer mode, the audio mixer always configures the Codec for the highest possible sample rate for both play and record. This ensures that none of the audio streams require compute-intensive low pass filtering. The result is that high sample rate audio streams are not degraded by filtering.

Sample rate conversion can be a compute-intensive operation, depending on the number of channels and a device's sample rate. For example, an 8KHz signal can be easily converted to 48KHz, requiring a low cost up sampling by 6. However, converting from 44.1KHz to 48KHz is compute intensive because it must be up sampled by 160 and then down sampled by 147. (This is only done using integer multipliers.)

Applications can greatly reduce the impact of sample rate conversion by carefully picking the sample rate. Applications should always use the highest sample rate the device supports. An application can also do its own sample rate conversion (to take advantage of floating point and accelerated instruction) or use small integers for up and down sampling.

In compatible mode, the audio mixer programs the Codec to the sample rate set by the application to avoid incurring any sample rate conversion overhead. If the Codec cannot support different play and record sample rates, the AUDIO_SETINFO ioctl(2) fails.

Encodings and Precision

When /dev/audio is opened, initial encoding and precision is 8-bit µ-Law (as in the Greek letter mu) . (As defined in audio(7I)

In mixer mode, the audio mixer supports formats in the following precisions:

Encoding	Precision	Channels
Signed Linear PCM	16-bit	Mono or Stereo
Signed Linear PCM	8-bit	Mono or Stereo
µ-Law	8-bit	Mono or Stereo
A-Law	8-bit	Mono or Stereo

The audio mixer converts all audio streams to 16–bit Linear PCM before mixing. After mixing, conversion is made to the best possible Codec format. The conversion process is not compute intensive and audio applications can choose the encoding format that best meets its needs.

In compatibility mode, the audio mixer sets the Codec to the encoding and precision set by the application. If the Codec cannot support different play and record encodings or precisions, the AUDIO_SETINFO ioctl(2) call fails.

Channels

When /dev/audio is opened, the number of initial channels is 1, left channel mono. (As defined in audio(7I)). Most Codecs play or record mono audio on the left channel.

In mixer mode, the audio mixer sets the Codec to the maximum number of channels supported. If a mono signal is played or recorded, it is mixed on the first (usually the left) channel only. Silence is mixed on the remaining channels.

In compatible mode, the audio mixer sets the Codec to the number of channels set by the application. If the Codec cannot support a different number of play and record channels, the AUDIO_SETINFO ioctl(2) call fails.

Description

The device /dev/audio is a device driver that dispatches audio requests to the appropriate underlying audio personality module. The audio driver is implemented as a STREAMS driver. To record audio input, applications open(2) the /dev/audio device and read data from it using the read(2) system call. Similarly, sound data is queued to the audio output port by using the write(2) system call. Device configuration is performed using the ioctl(2) interface.

Opening the Audio Device

In mixer mode, the audio device is no longer treated as an exclusive resource. Each process may open the audio device once unless the process has made an AUDIO_MIXER_MULTIPLE_OPEN ioctl(2) call. See below for details.

Each open() will complete as long as there are channels available to be allocated. If no channels are available to be allocated:

if either the O_NDELAY or O_NONBLOCK flags are set in the open() oflag argument, –1 is immediately returned, with errno set to EBUSY.
if neither the O_NDELAY nor the O_NONBLOCK flags are set, then open() hangs until a channel becomes available or a signal is delivered to the process. In the latter case, a –1 is returned with errno set to EINTR.

Upon the initial open() of the audio channel, the audio mixer sets the data format of the audio channel to the default state of 8-bit, 8Khz, mono µ-Law data. If the audio device does not support this configuration, it informs the audio mixer of the initial configuration. Audio applications should explicitly set the encoding characteristics to match the audio data requirements, and not depend on the default configuration. See the audio(7I) manual page for details on how the audio mixer behaves when in compatible mode.

Recording Audio Data

The read(2) system call copies data from the system buffers to the application. Ordinarily, read() blocks until the user buffer is filled. The I_NREAD ioctl (see streamio(7I)) may be used to determine the amount of data that may be read without blocking. The device may also be set to a non-blocking mode, where read() completes immediately but may return fewer bytes than requested. See the read(2) manual page for a complete description of this behavior.

When the audio device is opened with read access, the device driver immediately starts buffering audio input data. Because this consumes system resources, processes that do not record audio data should open the device write-only (O_WRONLY).

The transfer of input data to STREAMS buffers may be paused (or resumed) by using the AUDIO_SETINFO ioctl to set (or clear) the record.pause flag in the audio information structure. (See audio(7I).) All unread input data in the STREAMS queue may be discarded by using the I_FLUSH STREAMS ioctl (see streamio(7I)). When changing record parameters, the input stream should first be paused and flushed before the change. Otherwise, subsequent reads may return samples in the old format, followed by samples in the new format.

Input data accumulates in STREAMS buffers rapidly. For 8-bit, 8 KHz, mono µ-Law data, it accumulates at 8000 bytes per second. If a device is configured for 16-bit linear or higher sample rates, it accumulates even faster. If the application that consumes the data is unable to meet the input data rate, the STREAMS queue may become full. When this happens, the record.error flag is set in the audio information structure and input sampling ceases until there is room for additional data, resulting in a data stream discontinuity. To prevent this, audio recording applications should open the audio device when they are ready to begin reading data and not at the start of extensive initialization.

Playing Audio Data

The write(2) system call copies data from an application's buffer to the STREAMS output queue. Ordinarily, write() blocks until the entire user buffer is transferred. The device may alternatively be set to a non-blocking mode, in which case write() completes immediately, but may transfer fewer bytes than requested. (See the write(2) manual page for a complete description of this behavior).

Although write() returns when the data is successfully queued, the actual completion of audio output may take considerably longer. The AUDIO_DRAIN ioctl may be issued to allow an application to block until all of the queued output data has been played. Alternatively, a process may request asynchronous notification of output completion by writing a zero-length buffer (end-of-file record) to the output stream. When such a buffer has been processed, the play.eof flag in the audio information structure (see below) is incremented.

The final close(2) of the audio device file descriptor hangs until all of the process' remaining audio output has drained. If a signal interrupts the close() or if the process exits without closing the audio device, any remaining data queued for audio output is flushed and the audio device is closed immediately.

The conversion of output data may be paused (or resumed) by using the AUDIO_SETINFO ioctl to set (or clear) the play.pause flag in the audio information structure. Queued output data may be discarded by using the I_FLUSH STREAMS ioctl. (See streamio(7I).)

Output data is played from the STREAMS buffers at a default rate of 8000 bytes per second for µ-Law, A-Law, or 8–bit PCM data, or at a faster rate for 16-bit linear data or higher sampling rates. If the output queue becomes empty, the play.error flag is set in the audio information structure and output is stopped until additional data is queued. If an application attempts to write a number of bytes that is not a multiple of the current sample frame size, an error is generated and the bad data is thrown away. Additional writes are allowed.

Asynchronous I/O

The I_SETSIG STREAMS ioctl (see streamio(7I)) enables asynchronous notification through the SIGPOLL signal of input and output ready conditions. The O_NONBLOCK flag may be set using the F_SETFL fcntl(2) to enable non-blocking read() and write() requests. This is normally sufficient for applications to maintain a background audio stream.

Audio Control Pseudo-Device

The /dev/audioctl pseudo-device enables an application to modify characteristics of the audio device while it is being used by an unrelated process. Any number of processes may open the /dev/audioctl pseudo device simultaneously. /dev/audioctl ignores read() and write() system calls.

Note –

The audio control device name is constructed by appending the letters "ctl" to the path name of the audio device.

Audio Status Change Notification

Applications that open the audio control pseudo-device may request asynchronous notification of changes in the state of the audio device by setting the S_MSG flag in an I_SETSIG STREAMS ioctl. (See streamio(7I)). Such processes receive a SIGPOLL signal when any of the following events occur:

AUDIO_SETINFO, AUDIO_MIXERCTL_SETINFO, AUDIO_MIXERCTL_SET_CHINFO, or AUDIO_MIXERCTL_SET_MODE ioctl () has altered the device state.
Input overflow or output underflow has occurred.
End-of-file record (zero-length buffer) has been processed on output.
open() or close() of /dev/audio has altered the device state.
An external event (such as speakerbox's volume control) has altered the device state.

ioctls

The audio mixer implements all the ioctl()s defined in audio(7I) and uses the audio_prinfo_t, audio_info_t, and audio_device_t structures. See the audio(7I) manual page for details on these ioctl()s and structures. The audio mixer also uses the data structures described below.

Audio Mixer Control Structure

The state of the audio device may be polled or modified using the AUDIO_MIXERCTL_GETINFO and AUDIO_MIXERCTL_SETINFO ioctl commands.

struct am_control {
  audio_info_t dev_info;       /* the audio device's state */
  int8_t      ch_open[1];     /* variable sized array of */
                             /* of open channels */
};
typedef struct am_control_t;

See CODE EXAMPLES for sample code on how to use this structure and the related macro AUDIO_MIXER_CTL_STRUCT_SIZE(num_ch).

Audio Mixer Sample Rates Structure

The following structure is used by the AUDIO_MIXER_GET_SAMPLE_RATES ioctl to get a list of all the supported sample rates.

struct am_sample_rates {

  uint_t type;            /* play or capture */
  uint_t flags;
  uint_t num_samp_rates;  /* number of elements */
/* in samp_rates[] */
  uint_t samp_rates[1];  /*variable sized array */
/* of sample rates */
};
typedef struct am_sample_rates am_sample_rates_t;

#define AUDIO_PLAY   1  /* output */
#define AUDIO_RECORD 2  /* input */

#define MIXER_SR_LIMITS 0x00000001/* sample rates */
/* set limits */

See CODE EXAMPLES for example code on how to use this structure and the related macro AUDIO_MIXER_SAMP_RATES_STRUCT_SIZE(num_srs).

Audio Info Structure

When in mixer mode, the AM_MIXER bit in the audio_info_t structure's sw_features_enabled field is set. When in compatibility mode, that bit is clear.

The defines for the sw_features and the sw_features_enabled fields are:

#define AM_MIXER 0x00000001 /* mixer is present/enabled */

Streamio IOCTLS

All streamio(7I) ioctl commands may be issued for the /dev/audio and /dev/audioctl devices. I_SETSIG ioctl may be issued for /dev/audioctl to enable the notification of audio status changes as described above.

Audio Mixer IOCTLS

Except for AUDIO_MIXER_GET_SAMPLE_RATE, AUDIO_MIXERCTL_GET_MODE, and AUDIO_MIXERCTL_SET_MODE, these ioctl()s are valid only in mixer mode. Using them in compatible mode returns an EINVAL error.

AUDIO_MIXER_MULTIPLE_OPEN: This command allows an individual process to open /dev/audio more than once for play or record. The argument is ignored. This feature is useful for mixing panels that may control multiple audio streams.
AUDIO_MIXER_SINGLE_OPEN: This command gets a list of supported sample rates for either play or record for the audio mixer's current mode. The argument is ignored. This command returns /dev/audio back to an exclusive access device on per process basis after an AUDIO_MIXER_MULTIPLE_OPEN ioctl() is executed. This ioctl() fails if the process has more than one play or record stream open.
AUDIO_MIXER_GET_SAMPLE_RATES: This command retrieves sample rates. The argument is a pointer to an am_samples_rates_t structure. It is legal for the supported sample rates to be different for mixer mode vs. compatible mode. The type field must be set to either AUDIO_PLAY or AUDIO_RECORD to get a list of either play or record sample rates, respectively. Setting to both or neither is an error. The num_samp_rates field is set to the number of sample rates that the samp_rates[] array may hold. When the ioctl returns, num_samp_rates is set either to the number of sample rates in the array samp_rates[], or the total number of sample rates available if there are more than the array can hold. In the former case, there are num_samp_rates valid sample rates in the array. In the latter case, all the elements of the array have valid sample rates, but there are more available. The size of the array should be increased to get all available sample rates. If the flags field has the MIXER_SR_LIMITS flag set, the returned sample rates are the lowest and the highest rates possible, with all sample rates in-between being legal. Some Codecs that have DSP engines on them have this capability.
AUDIO_MIXERCTL_GETINFO: This command gets device and channel state information. The argument is a pointer to an am_control_t structure. The dev_info field contains the state of the hardware device. It provides a convenient way to determine the hardware's state. The ch_open array is used to specify which channels are open and which are closed. Open channels have non-zero values, closed channels are set to zero, The channel number corresponds to the array index. The number of elements in the ch_open array may change over time and a macro is provided to allocate the correct amount of space. The MACROS section below provides more information.
AUDIO_MIXERCTL_SETINFO: This command sets the device state but cannot modify any channel's state. (Use AUDIO_MIXERCTL_SET_CHINFO (below) to modify a channel's state.) The argument is a pointer to an am_control_t structure. The dev_info field sets the device state. The dev_info field is used to set the device state. However, there are several limitations. Only the gain, balance, port and pause fields for play and record, monitor_gain and output_muted fields may be modified. (Modifying other fields would interfere with how the audio mixer programs the audio device.) The ch_open array is not used when setting the audio device and may be set to a size of one.
AUDIO_MIXERCTL_GET_CHINFO: This command gets a channel's state information. The argument is a pointer to an audio_channel_t structure. This command gets a channel's state information. To enable the audio mixer to determine channel information, set the ch_number field before making the ioctl() call. The info_size field must be set to the size of the audio_info_t structure. The *info field must point to an audio_info_t structure. When the ioctl() returns, the pid field should be checked. If it is set to 0, the remaining data in the audio_channel_t structure is invalid because the channel has not been allocated. The dev_type field describes the type of channel; the *info pointer points to a buffer where the audio_info_t structure for the audio channel is populated.
AUDIO_MIXERCTL_SET_CHINFO: This command sets a channel's state information. The argument is a pointer to an audio_channel_t structure. Prior to issuing the ioctl call, specify the channel to be set in the argument's ch_number field, set *info to point to an audio_info_t structure containing info used to program the state of the channel, and set the info_size field to the size of an audio_info_t structure. When the ioctl() returns, the pid field contains the process ID of the process that has the channel open, and dev_type contains the type of the device. If pid is 0 (zero), the channel is not open.
AUDIO_MIXERCTL_GET_MODE: This command retrieves the mode of the audio mixer. The argument is a pointer to an integer that contains the audio mixer's mode upon return. It is set to either AM_MIXER_MODE for mixer mode or AM_COMPAT_MODE for compatible mode.
AUDIO_MIXERCTL_SET_MODE: This command sets the mode of the audio mixer. The argument is a pointer to an integer that contains the audio mixer mode to be set. It must be set to either AM_MIXER_MODE or AM_COMPAT_MODE. The audio mixer may be set to mixer mode at any time, but can only be set to compatible mode when there is a single read/write open within one process, or a single read process and a single write process. Otherwise the ioctl() will fail. Because the Codec is being reprogrammed to a different data format, there may be brief pause or burst of noise when the mode changes. This can be eliminated by pausing the input and output or by closing all streams before changing modes. The sdtaudiocontrol(1) or mixerctl(1) commands may be used to change the audio mixer's mode.

MACROS

The following macro is used to determine how large an am_control_t structure is when it points to an audio_info_t structure.

AUDIO_MIXER_CTL_STRUCT_SIZE(num_ch)

Where num_ch is the number of channels the device supports. The number of channels can be determined using the AUDIO_GET_NUM_CHS ioctl().

This macro is used when allocating an am_sample_rates_t structure.

AUDIO_MIXER_SAMP_RATES_STRUCT_SIZE(num_srs)

Where num_srs is the number of samples rates requested.

CODE EXAMPLES

The following examples illustrate how these new data structures and ioctls can be used.

Example 1

The following code demonstrates how to use the audio support and the audio mixer ioctl()s to get state information on /dev/audio.

  audio_channel_t ch;
  audio_info_t     info;
  am_control_t     *ctl;
  int               num;

err = ioctl(audio_fd, AUDIO_GET_NUM_CHS, &num);

ctl = (am_control_t *)malloc(AUDIO_MIXER_CTL_STRUCT_SIZE(num));

err = ioctl(audio_fd, AUDIO_MIXERCTL_GETINFO, ctl);

ch.info = &info;
ch.info_size = sizeof (audio_info_t);

for (i = 0; i < num; i++) {
     if (ctl->ch_open[i] != 0) {
         ch.ch_number = i;
         if (ioctl(audio_fd, AUDIO_MIXERCTL_GET_CHINFO, &ch) < 0) {
              printf("Channel # %d isn't an audio/audioctl device\n", i);

          } else {
              printf("Ch# %d, PID = %d, Type = %d\n",
                  i, ch.pid, ch.dev_type);
          }
     }
}

Example 2

The following code demonstrates how to use the AUDIO_MIXER_GET_SAMPLE_RATES ioctl to get the number of supported play sample rates. It also shows how to deal with allocating a samp_rates[] array that is too small.

#define LARGE_NUMBER 10000; 
am_sample_rates_t    *sr; 
int                   num;

for (num = 4; num < LARGE_NUMBER; num += 2) {
     sr = (am_sample_rates_t *)
          malloc(AUDIO_MIXER_SAMP_RATES_STRUCT_SIZE(num));

     sr->num_samp_rates = num;
     sr->type = AUDIO_PLAY;

     err = ioctl(audio_fd, AUDIO_MIXER_GET_SAMPLE_RATES, sr);

     if (sr->num_samp_rates <= num) {
       break;
     }
     free(sr);
}
(void) printf("Supported play sample rates:\n"); 
for (i = 0; i < sr->num_samp_rates; i++) {
     (void) printf("  %d\n", sr->samp_rates[i]);
}

Errors

An open() fails if:

EBUSY: The requested play or record access is busy and either the O_NDELAY or O_NONBLOCK flag was set in the open() request.
ENOMEM: Memory was not available to be allocated for the channel.
EINTR: The requested play or record access is busy and a signal interrupted the open() request.
EIO: There has been an error opening the device. An error message is printed on the console explaining the failure.

An ioctl() will fail if:

EBUSY: The parameter changes requested in the AUDIO_SETINFO ioctl could not be made because another process has the device open and is using a different format.
EINTR: The ioctl() was interrupted by a signal.
EINVAL: The parameter changes requested in the AUDIO_SETINFO ioctl are invalid or are not supported by the device, or the audio mixer is in compatible mode and a mixer-mode-only audio mixer ioctl was issued.
EIO: There has been an error with the ioctl(). An error message is printed on the console explaining the failure.
ENOMEM: The ioctl() failed because memory couldn't be allocated.

Files

The physical audio device names are system dependent and are rarely used by programmers. The programmer should use the generic device names listed below.

/dev/audio: symbolic link to the system's primary audio device
/dev/audioctl: symbolic link to the control device for /dev/audio
/dev/sound/0: first audio device in the system
/dev/sound/0ctl: audio control device for /dev/sound/0
/dev/sound/x: additional audio devices
/dev/sound/xctl: audio control device for /dev/sound/x

Attributes

See attributes(5) for a description of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Architecture	SPARC, x86
Availability	SUNWaudd, SUNWauddx, SUNWaudh, SUNWauda
Stability Level	Evolving

Bugs

Due to a feature of the STREAMS implementation, programs that are terminated or exit without closing the audio device may hang for a short period while audio output drains. In general, programs that produce audio output should catch the SIGINT signal and flush the output stream before exiting.

SunOS 5.10 Last Revised 31 Dec 2001