mixer - audio mixer audio personality module interface


     #include <sys/mixer.h>


     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  pro-
     vide   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   tradi-
     tional 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 chang-
     ing  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.


     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  filter-

     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, con-
     verting 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. Applica-
     tions 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  u-Law  (as  in the Greek letter mu) . (As  defined in

     In mixer mode, the audio mixer supports formats in the  fol-
     lowing precisions:

    |      Encoding      |      Precision     |       Channels     |
    | Signed Linear PCM  | 16-bit             |  Mono or Stereo    |
    | Signed Linear PCM  | 8-bit              |  Mono or Stereo    |
    | u-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 preci-
     sions,  the AUDIO_SETINFO ioctl(2) call fails.

     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) chan-
     nel 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 can-
     not support a different number of play and record  channels,
     the AUDIO_SETINFO ioctl(2) call fails.


     The device /dev/audio is a  device  driver  that  dispatches
     audio requests to the appropriate underlying audio personal-
     ity 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 confi-
     guration 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

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

        o  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.

        o  if neither the O_NDELAY nor the O_NONBLOCK  flags  are
           set,  then open() hangs until a channel becomes avail-
           able 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 u-Law data. If the  audio
     device  does not support this configuration,  it informs the
     audio mixer of the initial  configuration.   Audio  applica-
     tions  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

  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

     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 struc-
     ture.  (See  audio(7)). 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 u-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 initializa-

  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 dev-
     ice  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 con-
     siderably 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

     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  pro-
     cess  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 u-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 asyn-
     chronous  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  applica-
     tions 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.


          The audio control device name is constructed by append-
          ing  the  letters  "ctl"  to the path name of the audio

  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:

        o  AUDIO_SETINFO,                 AUDIO_MIXERCTL_SETINFO,
           ioctl () has altered the device state.

        o  Input overflow or output underflow has occurred.

        o  End-of-file record (zero-length buffer) has been  pro-
           cessed on output.

        o  open() or close() of /dev/audio has altered the device

        o  An external event (such as  speakerbox's  volume  con-
           trol) has altered the device state.


     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
     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  struc-
     ture          and          the         related         macro

  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 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 compa-
     tibility 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,
     ioctl()s are valid only in mixer mode. Using them in  compa-
     tible mode returns an EINVAL error.

           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.

           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 pro-
           cess has more than one play or record stream open.

           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 sam-
           ple 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

           This command gets device and  channel  state  informa-
           tion.  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  ele-
           ments  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 infor-

           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 pro-
           grams the audio device.) The ch_open array is not used
           when setting the audio device and may be set to a size
           of one.

           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 informa-
           tion,  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 chan-
           nel   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.

           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 struc-
           ture.  When   the  ioctl() returns, the pid field con-
           tains the process ID of the process that has the chan-
           nel  open,  and dev_type contains the type of the dev-
           ice. If pid is 0 (zero), the  channel is not open.

           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.

           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 clos-
           ing all streams  before  changing  modes.  The  sdtau-
           diocontrol(1)  or  mixerctl(1) commands may be used to
           change the audio mixer's mode.


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


     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


     Where num_srs  is the number of samples rates requested.


     The following examples illustrate how these new data  struc-
     tures 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

       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 device0, i);

               } else {
                   printf("Ch# %d, PID = %d, Type = %d0,
                       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 sup-
     ported 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 *)

          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) {
     (void) printf("Supported play sample rates:0);
     for (i = 0; i < sr->num_samp_rates; i++) {
          (void) printf("  %d0, sr->samp_rates[i]);


     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()

           Memory was not available to be allocated for the chan-

     EINTR The requested play or record access is busy and a sig-
           nal interrupted the open() request.

     EIO   There has been an error opening the device.  An  error
           message  is  printed  on  the  console  explaining the

     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.

           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

           The ioctl() failed because memory  couldn't  be  allo-


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

           symbolic link to the system's primary audio device

           symbolic link to the control device for  /dev/audio

           first audio device in the system

           audio control device for  /dev/sound/0

           additional audio devices

           audio control device for /dev/sound/x


     See attributes(5) for a description of the following  attri-

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


     mixerctl(1),    sdtaudiocontrol(1),   close(2),    fcntl(2),
     ioctl(2),   open(2),   poll(2),  read(2),  write(2),  attri-
     butes(5),    audiocs(7D),     audioens(7D),     audiots(7D),
     usb_ac(7D), audio(7I), audio_support(7I), streamio(7I)


     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.

Man(1) output converted with man2html