Previous Next Table of Contents

4. Mixer Interface

The Mixer Interface allows applications to change the volume level of a soundcard's input/output channels in both the linear range (0-100) and in decibels. It also supports features like hardware mute, input sound source, etc.

4.1 Low-Level Layer

Mixer devices aren't opened exclusively. This allows applications to open a device multiple times with one or more processes.

int snd_mixer_open( void **handle, int card, int device )

Creates new handle and opens a connection to the kernel sound mixer interface for soundcard number card (0-N) and mixer device number device. Also checks if protocol is compatible to prevent use of old programs with new kernel API. Function returns zero if successful, otherwise it returns an error code.

int snd_mixer_close( void *handle )

Frees all resources allocated to the mixer handle and closes its connection to the kernel sound mixer interface. Function returns zero if successful, otherwise it returns an error code.

int snd_mixer_file_descriptor( void *handle )

Returns the file descriptor for the connection to the kernel sound mixer interface. This function should be used only in very special cases. Function returns a negative error code if an error was encountered.

The file descriptor should be used for the select synchronous multiplexer function for deterimeing read direction. Applications should call snd_mixer_read function if some data is waiting to be read. It is recomended that you do this, since it leaves place for this function to handle some new kernel API specifications.

int snd_mixer_channels( void *handle )

Returns the count of mixer channels for appropriate mixer device, otherwise the return value is negative, and signifies an error code. Never returns zero.

int snd_mixer_info( void *handle, snd_mixer_info_t *info )

Fills the *info structure with information about the mixer associated with *handle. Returns zero if successful, otherwise it returns an error code.


  #define SND_MIXER_INFO_CAP_EXCL_RECORD  0x00000001

  struct snd_mixer_info {
    unsigned int type;            /* type of soundcard - SND_CARD_TYPE_XXXX */
    unsigned int channels;        /* count of mixer devices */
    unsigned int caps;            /* some flags about this device (SND_MIXER_INFO_CAP_XXXX) */
    unsigned char id[32];         /* ID of this mixer */
    unsigned char name[80];       /* name of this device */
    char reserved[ 32 ];          /* reserved for future use */
  };
  

int snd_mixer_channel( void *handle, const char *channel_id )

Returns the channel number (index) associated with channel_id (channel name), or returns an error code.


  #define SND_MIXER_ID_MASTER             "Master"
  #define SND_MIXER_ID_BASS               "Bass"
  #define SND_MIXER_ID_TREBLE             "Treble"
  #define SND_MIXER_ID_SYNTHESIZER        "Synth"
  #define SND_MIXER_ID_SYNTHESIZER1       "Synth 1"
  #define SND_MIXER_ID_FM                 "FM"
  #define SND_MIXER_ID_EFFECT             "Effect"
  #define SND_MIXER_ID_PCM                "PCM"
  #define SND_MIXER_ID_PCM1               "PCM 1"
  #define SND_MIXER_ID_LINE               "Line-In"
  #define SND_MIXER_ID_MIC                "MIC"
  #define SND_MIXER_ID_CD                 "CD"
  #define SND_MIXER_ID_GAIN               "Record-Gain"
  #define SND_MIXER_ID_IGAIN              "In-Gain"
  #define SND_MIXER_ID_OGAIN              "Out-Gain"
  #define SND_MIXER_ID_LOOPBACK           "Loopback"
  #define SND_MIXER_ID_SPEAKER            "PC Speaker"
  #define SND_MIXER_ID_AUXA               "Aux A"
  #define SND_MIXER_ID_AUXB               "Aux B"
  #define SND_MIXER_ID_AUXC               "Aux C"
  

int snd_mixer_exact_mode( void *handle, int enable )

Turns on or off (by default) exact mode. This mode allows to application set/get volume values in exact range which uses hardware. In non-exact mode is range always from 0 to 100 and conversion to hardware range does driver. Function returns zero if successful, otherwise it returns an error code.

int snd_mixer_channel_info( void *handle, int channel, snd_mixer_channel_info_t *info )

Fills the *info structure. The argument channel specifies channel (0 to N) for which is the info requested. Function returns zero if successful, otherwise it returns an error code.


  #define SND_MIXER_CINFO_CAP_RECORD      0x00000001
  #define SND_MIXER_CINFO_CAP_STEREO      0x00000002
  #define SND_MIXER_CINFO_CAP_MUTE        0x00000004
  #define SND_MIXER_CINFO_CAP_HWMUTE      0x00000008      /* channel supports hardware mute */
  #define SND_MIXER_CINFO_CAP_DIGITAL     0x00000010      /* channel does digital (not analog) mixing */
  #define SND_MIXER_CINOF_CAP_INPUT       0x00000020      /* input channel */

  struct snd_mixer_channel_info {
    unsigned int channel;         /* channel # (filled by application) */
    unsigned int parent;          /* parent channel # or SND_MIXER_PARENT */
    unsigned char name[12];       /* name of this device */
    unsigned int caps;            /* some flags about this device (SND_MIXER_CINFO_XXXX) */
    int min;                      /* min. value when exact mode (or always 0) */
    int max;                      /* max. value when exact mode (or always 100) */
    int min_dB;                   /* minimum decibel value (*100) */
    int max_dB;                   /* maximum decibel value (*100) */
    int step_dB;                  /* step decibel value (*100) */
    unsigned char reserved[16];
  };
  

int snd_mixer_channel_read( void *handle, int channel, snd_mixer_channel_t *data )

Fills the *data structure. The argument channel specifies the channel (0 to N) for which is data requested. Function returns zero if successful, otherwise it returns an error code.


  #define SND_MIXER_FLG_RECORD            0x00000001      /* channel record source flag */
  #define SND_MIXER_FLG_MUTE_LEFT         0x00010000
  #define SND_MIXER_FLG_MUTE_RIGHT        0x00020000
  #define SND_MIXER_FLG_MUTE              0x00030000
  #define SND_MIXER_FLG_DECIBEL           0x40000000
  #define SND_MIXER_FLG_FORCE             0x80000000

  struct snd_mixer_channel {
    unsigned int channel;         /* channel # (filled by application) */
    unsigned int flags;           /* some flags to read/write (SND_MIXER_FLG_XXXX) */
    int left;                     /* min - max when exact mode (or 0 - 100) */
    int right;                    /* min - max when exact mode (or 0 - 100) */
    int left_dB;                  /* dB * 100 */
    int right_dB;                 /* dB * 100 */
    unsigned char reserved[16];
  };
  

SND_MIXER_FLG_RECORD

Record source flag.

SND_MIXER_FLG_DECIBEL

If this bit is set, driver set volume from dB variables left_dB and right_dB.

SND_MIXER_FLG_FORCE

Force set - this bit shouldn't be used from user space. Reserved for kernel.

int snd_mixer_channel_write( void *handle, int channel, snd_mixer_channel_t *data )

Writes the *data structure to kernel. The channel argument specifies the channel (0 to N) for which is data is to be applied. Function returns zero if successful, otherwise it returns an error code. This functions is the opposite of snd_mixer_channel_read.

int snd_mixer_special_read( void *handle, snd_mixer_special_t *special )

Not documented...

int snd_mixer_special_write( void *handle, snd_mixer_special_t *special )

Not documented...

int snd_mixer_read( void *handle, snd_mixer_callbacks_t *callbacks )

This function reads and parses data from driver. Parsed actions are returned back to the application using the callbacks structure. Applications should not parse data from the driver in standard cases. This function returns immediately after all data is read from driver. Does not block process.


  typedef struct snd_mixer_callbacks {
    void *private_data;           /* should be used by application */
    void (*channel_was_changed)( void *private_data, int channel );
    void *reserved[15];           /* reserved for future use - must be NULL!!! */
  } snd_mixer_callbacks_t;
  

4.2 Examples

The following example shows installed mixer channels for soundcard #0 and mixer device #0 in the system, and also sets the master volume (if present) to 50.


int card = 0, device = 0, err;
void *handle;
snd_mixer_info_t info;
snd_mixer_channel_t channel;

if ( (err = snd_mixer_open( &handle, card, device )) < 0 ) {
  fprintf( stderr, "open failed: %s\n", snd_strerror( err ) );
  return;
}
if ( (err = snd_mixer_info( handle, &info )) < 0 ) {
  fprintf( stderr, "info failed: %s\n", snd_strerror( err ) );
  snd_mixer_close( handle );
  return;
}
printf( "Installed MIXER channels for card #i and device %i: %i\n",
                                        card + 1, device, info.channels );
master = snd_mixer_channel( handle, SND_MIXER_ID_MASTER );
if ( master >= 0 ) {
  if ( (err = snd_mixer_read( handle, master, &channel )) < 0 ) {
    fprintf( stderr, "master read failed: %s\n", snd_strerror( err ) );
    snd_mixer_close( handle );
    return;
  }
  channel -> left = channel -> right = 50;
  if ( (err = snd_mixer_write( handle, master, &channel )) < 0 ) {
    fprintf( stderr, "master write failed: %s\n", snd_strerror( err ) );
    snd_mixer_close( handle );
    return;
  }
}
snd_mixer_close( handle );


Previous Next Table of Contents