The Advanced Linux Sound Architecture comes with a kernel API & library API. This document describes the library API and how it interfaces with the kernel API. The kernal API will probably never be documented in standalone form.
Application programmers should use the library API rather than kernel API. The Library offers 100% of the functionally of the kernel API, but add major improvements in usability, making the application code simpler and better looking. In addition, some of the some fixes/compatibility code may be placed in the library code instead of the kernel driver.
For a complete list of all variables and functions in the API you should look at the following header files:
All functions return int (or some sort of signed value). If this value is negative it represents an error code. Codes up to SND_ERROR_BEGIN (500000) represent standard system errors. Codes equal to or greather than this value represent sound library API errors. All error codes begin with the prefix SND_ERROR_.
| SND_ERROR_UNCOMPATIBLE_VERSION | 500000 |
This error is caused if the driver uses an incompatible kernel API for this interface and hence the library doesn't know how this API can be used.
This function converts an error code to a string. Its functionality is the same as the strerror function from the standard C library, but this function returns error message strings for sound error codes, as well.
The control interface gives applications various information about the currently installed sound driver in the system. The interface should be used to detect if another sound interface is present for a selected soundcard or, for example, to create a list of devices (MIXER, PCM etc) from which the user can select.
Returns the number of soundcards present in the system, if any. Otherwise it returns a negative value, which maps to an error code. This function will return 0 if no soundcards are detected.
Returns the bitmap of soundcards present in the system, if any. This function will return 0 if no soundcards are detected. The first soundcard is represented with bit 0 (0x00000001). See the documentation on installing ALSA and /etc/conf.modules configuration for information on assigning numbers to soundcards.
Returns soundcard number for appropriate soundcard name. String name can contain word identification for card (ALSA driver allows the user choose card identification using snd_id module parameter) or soundcard index (1-N) encoded into ASCII.
Creates a new handle and opens communication with the kernel sound control interface for soundcard number card (0-N). The function also checks if the protocol is compatible, so as to prevent the use of old programs with a new kernel API. Function returns zero if successful, otherwise an error code is returned.
Frees all resources allocated with control handle and closes the kernel sound control interface. This function returns zero if successful, otherwise it returns an error code.
Returns a file descriptor for the kernel sound control interface. This function is normally only used in very special cases. This function returns a negative error code if an error was encountered.
Fills the info structure with data about the sound hardware referenced by handle. This function returns zero if successful, otherwise it returns an error code.
#define SND_CTL_GCAPS_MIDI 0x0000001
/* soundcard has synthesizer */
#define SND_CTL_LCAPS_SYNTH 0x0000001
/* soundcard has RAW FM/OPL3 */
#define SND_CTL_LCAPS_RAWFM 0x0000002
/* type of card - see SND_CARD_TYPE_XXXX */
unsigned int type;
/* global capabilities - see SND_CTL_GCAPS_XXXX*/
unsigned int gcaps;
/* local capabilities ¯ see SND_CTL_LCAPS_XXXX */
unsigned int lcaps;
/* count of PCM devices (0 to N) */
unsigned int pcmdevs;
/* count of MIXER devices (0 to N)*/
unsigned int mixerdevs;
/* count of raw MIDI devices (0 to N) */
unsigned int mididevs;
/* ID of card (user selectable) */
char id[80];
/* name/info text about soundcard */
char name[80];
/* count of control switches */
unsigned int switches;
/* reserved for future use */
unsigned char reserved[124];
};
Returns the number of control switches. In this context 'switch' means universal control interface between kernel and application which allows various types of control. Function returns count if successful, otherwise it returns an error code. Return value should be zero if the soundcard doesn't have any control switches.
Returns the index for the switch with the name switch_id. This function returns switch index if successful, otherwise it returns an error code.
Fills the *data structure with data about the switch with index switchn. This function returns zero if successful, otherwise it returns an error code.
#define SND_CTL_SW_TYPE_BOOLEAN 0
/* 0 to 255 - from low to high (data8[0] member of union) */
#define SND_CTL_SW_TYPE_BYTE 1
/* 0 to 65535 - from low to high (data16[0] member of union) */
#define SND_CTL_SW_TYPE_WORD 2
/* 0 to 4294967296 ¯ from low to high (data32[0] member of union) */
#define SND_CTL_SW_TYPE_DWORD 3
/* user type - no type control */
#define SND_CTL_SW_TYPE_USER (~0)
#define SND_CTL_SW_JOYSTICK "Joystick"
#define SND_CTL_SW_JOYSTICK_ADDRESS "Joystick Address"
#define SND_CTL_SW_JOYSTICK_SPEED "Joystick Speed"
/* switch index (filled by application) */
unsigned int switchn;
/* indentification of switch (for driver) */
unsigned char name[32];
/* type of switch value - See SND_CTL_SW_TYPE_XXXX */
unsigned int type;
/* low range value */
unsigned int low;
/* high range value */
unsigned int high;
union {
unsigned int enable; /* 0 = off 1 = on */
unsigned char data8[32]; /* 8-bit data */
unsigned short data16[16]; /* 16-bit data */
unsigned int data32[8]; /* 32-bit data */
} value;
/* reserved for future use ¯ must be zero !!! */
unsigned char reserved[32];
}
Writes the *data structure with data about the switch with index switchn to kernel. This function returns zero if successful, otherwise it returns an error code.
Fills the *info structure with data about the mixer device. Returns zero if successful, otherwise it returns an error code. Details about the snd_mixer_info_t structure are in the Mixer Interface section. The argument dev specifies the device number for the appropriate soundcard. Its range is 0 to N where N is determined by struct snd_ctl_hw_info->mixerdevs - 1. It should be used to collect information about mixer devices.
Returns count of mixer switches. In this context 'switch' means universal control interface between kernel and application which allows various types control. This function returns count if successful, otherwise it returns an error code. Return value should be zero if soundcard doesn't have any mixer switches.
Returns the index for the switch with the name switch_id. This function returns switch index if successful, otherwise it returns an error code.
Fills the *data structure with data about the switch with index switchn. This function returns zero if successful, otherwise it returns an error code. Details about the snd_mixer_switch_t structure are in the Mixer Interface section.
Writes the *data structure with data about switch with index switchn to kernel. Function returns zero if successful, otherwise it returns an error code. Details about the snd_mixer_switch_t structure are in the Mixer Interface Interface section.
Fills the *info structure with data about the PCM device. Function returns zero if successful, otherwise it returns an error code. Details about the snd_pcm_info_t structure are in the Digital Audio (PCM) Interface section. The argument dev selects the device number for the sound card referenced by *handle. Its range is 0 to N where N is struct snd_ctl_hw_info->pcmdevs - 1. This function will work if the selected PCM device is busy, too. It should be used to collect information about PCM devices without exclusive lock.
Fills the *info structure with data about the PCM device and playback direction. Function returns zero if successful, otherwise it returns an error code. Details about the snd_pcm_playback_info_t structure are in the Digital Audio (PCM) Interface section. The argument dev selects the device number for the sound card referenced by *handle. Its range is 0 to N where N is struct snd_ctl_hw_info->pcmdevs - 1. This function will work if the selected PCM device is busy, too. It should be used to collect information about PCM devices without exclusive lock.
Returns count of PCM playback switches. In this context 'switch' means universal control interface between kernel and application which allows various types of control. Function returns count if successful, otherwise it returns an error code. Return value should be zero if sound card doesn't have any PCM playback switch.
Returns index for switch with name switch_id. Function returns switch index if successful, otherwise it returns an error code.
Fills the *data structure with data about switch with index switchn. Function returns zero if successful, otherwise it returns an error code. Details about the snd_pcm_switch_t structure are in the Digital Audio (PCM) Interface section.
Writes the *data structure with data about switch with index switchn to kernel. Function returns zero if successful, otherwise it returns an error code. Details about the snd_pcm_switch_t structure are in the Digital Audio (PCM) Interface section.
Fills the *info structure with data about the PCM device and record direction. Function returns zero if successful, otherwise it returns an error code. Details about the snd_pcm_record_info_t structure are in the Digital Audio (PCM) Interface section. The argument dev selects the device number for the sound card referenced by *handle. Its range is 0 to N where N is struct snd_ctl_hw_info->pcmdevs - 1. This function will work if the selected PCM device is busy, too. It should be used to collect information about PCM devices without exclusive lock.
Returns count of PCM record switches. In this context 'switch' means universal control interface between kernel and application which allows various types of control. Function returns count if successful, otherwise it returns an error code. Return value should be zero if sound card doesn't have any PCM record switch.
Returns index for switch with name switch_id. Function returns switch index if successful, otherwise it returns an error code.
Fills the *data structure with data about switch with index switchn. Function returns zero if successful, otherwise it returns an error code. Details about the snd_pcm_switch_t structure are in the Digital Audio (PCM) Interface section.
Writes the *data structure with data about switch with index switchn to kernel. Function returns zero if successful, otherwise it returns an error code. Details about the snd_pcm_switch_t structure are in the Digital Audio (PCM) Interface section.
Fills the *info structure with data about the rawmidi device. Function returns zero if successful, otherwise it returns an error code. Details about the snd_rawmidi_info_t structure are in the RawMidi Interface section. The argument dev selects the device number for the sound card referenced by *handle. Its range is 0 to N where N is struct snd_ctl_hw_info->mididevs - 1. This function will work if the selected rawmidi device is busy, too. It should be used to collect information about rawmidi devices without exclusive lock.
Fills the *info structure with data about the rawmidi device and output direction. Function returns zero if successful, otherwise it returns an error code. Details about the snd_pcm_playback_info_t structure are in the RawMidi Interface section. The argument dev selects the device number for the sound card referenced by *handle. Its range is 0 to N where N is struct snd_ctl_hw_info->mididevs - 1. This function will work if the selected rawmidi device is busy, too. It should be used to collect information about rawmidi devices without exclusive lock.
Returns count of rawmidi output switches. In this context 'switch' means universal control interface between kernel and application which allows various types of control. Function returns count if successful, otherwise it returns an error code. Return value should be zero if sound card doesn't have any control switch.
Returns index for switch with name switch_id. Function returns switch index if successful, otherwise it returns an error code. Return value should be zero if sound card doesn't have any rawmidi output switch.
Fills the *data structure with data about switch with index switchn. Function returns zero if successful, otherwise it returns an error code. Details about the snd_rawmidi_switch_t structure are in the RawMidi Interface section.
Writes the *data structure with data about switch with index switchn to kernel. Function returns zero if successful, otherwise it returns an error code. Details about the snd_rawmidi_switch_t structure are in the RawMidi Interface section.
Fills the *info structure with data about the rawmidi device and input direction. Function returns zero if successful, otherwise it returns an error code. Details about the snd_rawmidi_record_info_t structure are in the RawMidi Interface section. The argument dev selects the device number for the sound card referenced by *handle. Its range is 0 to N where N is struct snd_ctl_hw_info->pcmdevs - 1. This function will work if the selected rawmidi device is busy, too. It should be used to collect information about rawmidi devices without exclusive lock.
Returns count of rawmidi input switches. In this context 'switch' means universal control interface between kernel and application which allows various types of control. Function returns count if successful, otherwise it returns an error code. Return value should be zero if sound card doesn't have any rawmidi input switch.
Returns index for switch with name switch_id. Function returns switch index if successful, otherwise it returns an error code.
Fills the *data structure with data about switch with index switchn. Function returns zero if successful, otherwise it returns an error code. Details about the snd_rawmidi_switch_t structure are in the RawMidi Interface Interface section.
Writes the *data structure with data about switch with index switchn to kernel. Function returns zero if successful, otherwise it returns an error code. Details about the snd_rawmidi_switch_t structure are in the RawMidi Interface section.
The following example shows how all PCM devices can be detected for the first sound card (#0) in the system.
void *handle;
snd_ctl_hw_info_t info;
if ((err = snd_ctl_open(&handle, card)) < 0) {
fprintf(stderr, "open failed: %s\n", snd_strerror(err));
return;
}
if ((err = snd_ctl_hw_info(handle, &info)) < 0) {
fprintf(stderr, "hw info failed: %s\n",
snd_strerror(err));
snd_ctl_close(handle);
return;
}
printf("Installed PCM devices for card #i: %i\n",
card + 1, info.pcmdevs);
snd_ctl_close(handle);
The Mixer Interface allows applications to change the volume level of a sound card's input/output channels in both the linear range percentage range (0-100) and in decibels. It also supports features like hardware mute, input sound source, stereo signal routing etc.
Mixer devices aren't opened exclusively. This allows applications to open a device multiple times with one or more processes.
Creates new handle and opens a connection to the kernel sound mixer interface for sound card 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.
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.
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(2) synchronous multiplexer function for determining read direction. Applications should call snd_mixer_read() function if some data is waiting to be read. It is recommended that you do this, since it leaves place for this function to handle some new kernel API specifications.
Returns the count of mixer channels for appropriate mixer device, otherwise the return value is negative, and signifies an error code. Never returns zero.
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
/* type of sound card - SND_CARD_TYPE_XXXX */
unsigned int type;
/* count of mixer devices */
unsigned int channels;
/* some flags about this device (SND_MIXER_INFO_CAP_XXXX) */
unsigned int caps;
/* ID of this mixer */
unsigned char id[32];
/* name of this device */
unsigned char name[80];
/* reserved for future use */
char reserved[ 32 ];
};
Returns count of mixer switches. In this context 'switch' means universal control interface between kernel and application which allows various types of control. Function returns count if successful, otherwise it returns an error code. Return value will be zero if sound card doesn't have any mixer switch.
Returns index for switch with name switch_id. Function returns switch index if successful, otherwise it returns an error code.
Fills the *data structure with data about switch with index switchn. Function returns zero if successful, otherwise it returns an error code.
#define SND_MIXER_SW_TYPE_BOOLEAN 0
/* 0 to 255 - from low to high (data8[0] member of union) */
#define SND_MIXER_SW_TYPE_BYTE 1
/* 0 to 65535 - from low to high (data16[0] member of union) */
#define SND_MIXER_SW_TYPE_WORD 2
/* 0 to 4294967296 ¯ from low to high (data32[0] member of union) */
#define SND_MIXER_SW_TYPE_DWORD 3
/* user type - no type control */
#define SND_MIXER_SW_TYPE_USER (~0)
#define SND_MIXER_SW_LOUDNESS "Loudness" /* bass boost */
#define SND_MIXER_SW_SIM_STEREO "Simulated Stereo Enhancement"
#define SND_MIXER_SW_3D "3D Stereo Enhancement"
/* microphone gain */
#define SND_MIXER_SW_MIC_GAIN "MIC Gain"
/* microphone auto gain control */
#define SND_MIXER_SW_MIC_GAIN "MIC Auto-Gain-Control"
/* change microphone impedance */
#define SND_MIXER_SW_MIC_GAIN "Change MIC Impedance"
/* change line-in to output */
#define SND_MIXER_SW_MIC_GAIN "Line In to Output"
#define SND_MIXER_SW_IEC958OUT "IEC-958 (S/PDIF) Output"
#define SND_MIXER_SW_IEC958IN "IEC-958 (S/PDIF) Input"
/* switch index (filled by application) */
unsigned int switchn;
/* identification of switch (for driver) */
unsigned char name[32];
/* type of switch value ¯ See SND_CTL_SW_TYPE_XXXX */
unsigned int type;
/* low range value */
unsigned int low;
/* high range value */
unsigned int high;
union {
unsigned int enable; /* 0 = off 1 = on */
unsigned char data8[32]; /* 8-bit data */
unsigned short data16[16]; /* 16-bit data */
unsigned int data32[8]; /* 32-bit data */
} value;
/* reserved for future use ¯ must be zero !!! */
unsigned char reserved[32];
}
Writes the *data structure with data about switch with index switchn to kernel. Function returns zero if successful, otherwise it returns an error code.
Turns on = 1 or off = 0 (by default) exact mode. This mode allows application to set/get volume values in exact range which uses hardware. In non-exact mode range is always from percentage 0 to 100 and driver does conversion to hardware range. Function returns zero if successful, otherwise it returns an error code.
Returns the channel number (index) associated with channel_id (channel name), or returns an error code. Note: Below mixer channel IDs are subject to change and will be extended if new hardware has support for other mixer input/output channels.
#define SND_MIXER_ID_MASTER1 "Master 1"
/* digital master */
#define SND_MIXER_ID_MASTERD "Master D"
/* second digital master */
#define SND_MIXER_ID_MASTERD1 "Master D1"
#define SND_MIXER_ID_HEADPHONE "Headphone"
#define SND_MIXER_ID_MASTER_MONO "Master M"
#define SND_MIXER_ID_3D "3D Wide"
#define SND_MIXER_ID_3D_VOLUME "3D Volume"
#define SND_MIXER_ID_3D_CENTER "3D Center"
#define SND_MIXER_ID_3D_SPACE "3D Space"
#define SND_MIXER_ID_3D_DEPTH "3D Depth"
#define SND_MIXER_ID_BASS "Bass"
#define SND_MIXER_ID_TREBLE "Treble"
#define SND_MIXER_ID_FADER "Fader"
#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_DSP "DSP"
#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_VIDEO "Video"
#define SND_MIXER_ID_PHONE "Phone"
#define SND_MIXER_ID_GAIN "Record-Gain"
#define SND_MIXER_ID_MIC_GAIN "Mic-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_MONO "Mono"
#define SND_MIXER_ID_MONO1 "Mono 1"
#define SND_MIXER_ID_MONO2 "Mono 2"
#define SND_MIXER_ID_AUXA "Aux A"
#define SND_MIXER_ID_AUXB "Aux B"
#define SND_MIXER_ID_AUXC "Aux C"
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
/* mixer channel is stereo */
#define SND_MIXER_CINFO_CAP_STEREO 0x00000002
/* always set at this moment driver emulates mute */
#define SND_MIXER_CINFO_CAP_MUTE 0x00000004
/* channel supports hardware mute */
#define SND_MIXER_CINFO_CAP_HWMUTE 0x00000008
/* channel does digital (not analog) mixing */
#define SND_MIXER_CINFO_CAP_DIGITAL 0x00000010
/* external input channel */
#define SND_MIXER_CINFO_CAP_INPUT 0x00000020
/* join mute is supported only */
/* left and right channel doesn't have separate mute control */
#define SND_MIXER_CINFO_CAP_JOINMUTE 0x00000040
/* join record is supported only *
/* left and right channel doesn't have separate record control */
#define SND_MIXER_CINFO_CAP_JOINRECORD 0x00000080
/* route left input to right output is supported */
#define SND_MIXER_CINFO_CAP_LTOR_OUT 0x00000100
/* route right input to left output is supported */
#define SND_MIXER_CINFO_CAP_RTOL_OUT 0x00000200
/* route left input to right ADC is supported */
#define SND_MIXER_CINFO_CAP_LTOR_IN 0x00000400
/* route right input to left ADC is supported */
#define SND_MIXER_CINFO_CAP_RTOL_IN 0x00000800
/* output route is only switch (cannot be used separately) */
#define SND_MIXER_CINFO_CAP_SWITCH_OUT 0x00001000
/* input route is only switch (cannot be used separately) */
#define SND_MIXER_CINFO_CAP_SWITCH_IN 0x00002000
/* data can be recorded even if output path is muted */
/* (to avoid loopback) */
#define SND_MIXER_CINFO_CAP_RECORDBYMUTE 0x00004000
/* channel index (filled by application) */
unsigned int channel;
/* parent channel # or SND_MIXER_PARENT */
unsigned int parent;
/* name of this device */
unsigned char name[12];
/* some flags about this device (SND_MIXER_CINFO_XXXX) */
unsigned int caps;
/* min. value when exact mode (or always 0) */
int min;
/* max. value when exact mode (or always 100) */
int max;
/* minimum decibel value (*100) */
int min_dB;
/* maximum decibel value (*100) */
int max_dB;
/* step decibel value (*100) */
int step_dB;
/* reserved for future use */
unsigned char reserved[16];
};
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_LEFT 0x00000001
#define SND_MIXER_FLG_RECORD_RIGHT 0x00000002
#define SND_MIXER_FLG_RECORD 0x00000003
/* mute channel flags */
#define SND_MIXER_FLG_MUTE_LEFT 0x00010000
#define SND_MIXER_FLG_MUTE_RIGHT 0x00020000
#define SND_MIXER_FLG_MUTE 0x00030000
/* input to output route setup */
#define SND_MIXER_FLG_LTOR_OUT 0x00100000
#define SND_MIXER_FLG_RTOL_OUT 0x00200000
#define SND_MIXER_FLG_SWITCH_OUT 0x00300000
/* input to ADC route setup */
#define SND_MIXER_FLG_LTOR_IN 0x00400000
#define SND_MIXER_FLG_RTOL_IN 0x00800000
#define SND_MIXER_FLG_SWITCH_IN 0x00c00000
/* set volume in decibels from dB variables */
#define SND_MIXER_FLG_DECIBEL 0x40000000
/* reserved for kernel use, don't use this flag from application */
#define SND_MIXER_FLG_FORCE 0x80000000
/* channel # (filled by application) */
unsigned int channel;
/* some flags to read/write (SND_MIXER_FLG_XXXX) */
unsigned int flags;
/* min - max when exact mode (or 0 - 100) */
int left;
/* min - max when exact mode (or 0 - 100) */
int right;
/* dB * 100 */
int left_dB;
/* dB * 100 */
int right_dB;
unsigned char reserved[16];
};
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.
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.
/* should be used by application */
void *private_data;
void (*channel_was_changed)(void *private_data, int channel);
void (*switch_was_changed)(void *private_data, int switchn);
/* reserved for future use - must be NULL!!! */
void *reserved[14];
} snd_mixer_callbacks_t;
The following example shows installed mixer channels for sound card #0 and mixer device #0 in the system, and also sets the master volume (if present) to 50.
void *handle;
snd_mixer_info_t info;
snd_mixer_channel_t channel;
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);
Digital audio is the most commonly used method of representing sound inside a computer. In this method sound is stored as a sequence of samples taken from the audio signal using constant time intervals. A sample represents volume of the signal at the moment when it was measured. In uncompressed digital audio each sample require one or more bytes of storage. The number of bytes required depends on number of channels (mono, stereo) and sample format (8 or 16 bits, mu-Law, etc.). The length of this interval determines the sampling rate. Commonly used sampling rates are between 8 kHz (telephone quality) and 48 kHz (DAT tapes).
The physical devices used in digital audio are called the ADC (Analog to Digital Converter) and DAC (Digital to Analog Converter). A device containing both ADC and DAC is commonly known as a codec. The codec device used in a Sound Blaster cards is called a DSP which is somewhat misleading since DSP also stands for Digital Signal Processor (the SB DSP chip is very limited when compared to "true" DSP chips).
Sampling parameters affect the quality of sound which can be reproduced from the recorded signal. The most fundamental parameter is sampling rate which limits the highest frequency that can be stored. It is well known (Nyquist's Sampling Theorem) that the highest frequency that can be stored in a sampled signal is at most 1/2 of the sampling frequency. For example, an 8 kHz sampling rate permits the recording of a signal in which the highest frequency is less than 4 kHz. Higher frequency signals must be filtered out before feeding them to DAC.
Sample encoding limits the dynamic range of a recorded signal (difference between the faintest and the loudest signal that can be recorded). In theory the maximum dynamic range of signal is number_of_bits * 6 dB . This means that 8 bits sampling resolution gives dynamic range of 48 dB and 16 bit resolution gives 96 dB.
Quality has price. The number of bytes required to store an audio sequence depends on sampling rate, number of channels and sampling resolution. For example just 8000 bytes of memory is required to store one second of sound using 8 kHz/8 bits/mono but 48 kHz/16bit/stereo takes 192 kilobytes. A 64 kbps ISDN channel is required to transfer a 8kHz/8bit/mono audio stream in real time, and about 1.5 Mbps is required for DAT quality (48kHz/16bit/stereo). On the other hand it is possible to store just 5.46 seconds of sound in a megabyte of memory when using 48kHz/16bit/stereo sampling. With 8kHz/8bits/mono it is possible to store 131 seconds of sound using the same amount of memory. It is possible to reduce memory and communication costs by compressing the recorded signal but this is beyond the scope of this document.
Audio devices are opened exclusively for a selected direction. This doesn't allow open from more than one processes for the same audio device in the same direction, but does allow one open call to each playback direction and second open call to record direction independently. Audio devices return EBUSY error to applications when other applications have already opened the requested direction.
Low-Level layer supports these formats:
#define SND_PCM_SFMT_MU_LAW 0
/* aLaw compressed samples */
#define SND_PCM_SFMT_A_LAW 1
/* Ima-ADPM 4:1 compressed samples */
#define SND_PCM_SFMT_IMA_ADPCM 2
/* Unsigned 8-bit samples (most common 8-bit format) */
#define SND_PCM_SFMT_U8 3
/* Signed 16-bit Little Endian samples (most common 16-bit format) */
#define SND_PCM_SFMT_S16_LE 4
/* Signed 16-bit Big Endian samples */
#define SND_PCM_SFMT_S16_BE 5
/* Signed 8-bit samples */
#define SND_PCM_SFMT_S8 6
/* Unsigned 16-bit Little Endian samples */
#define SND_PCM_SFMT_U16_LE 7
/* Unsigned 16-bit Big Endian samples */
#define SND_PCM_SFMT_U16_BE 8
/* MPEG 1/2 stream */
#define SND_PCM_SFMT_MPEG 9
/* GSM stream */
#define SND_PCM_SFMT_GSM 10
#define SND_PCM_FMT_A_LAW (1 << SND_PCM_SFMT_A_LAW)
#define SND_PCM_FMT_IMA_ADPCM (1 << SND_PCM_SFMT_IMA_ADPCM)
#define SND_PCM_FMT_U8 (1 << SND_PCM_SFMT_U8)
#define SND_PCM_FMT_S16_LE (1 << SND_PCM_SFMT_S16_LE)
#define SND_PCM_FMT_S16_BE (1 << SND_PCM_SFMT_S16_BE)
#define SND_PCM_FMT_S8 (1 << SND_PCM_SFMT_S8)
#define SND_PCM_FMT_U16_LE (1 << SND_PCM_SFMT_U16_LE)
#define SND_PCM_FMT_U16_BE (1 << SND_PCM_SFMT_U16_BE)
#define SND_PCM_FMT_MPEG (1 << SND_PCM_SFMT_MPEG)
#define SND_PCM_FMT_GSM (1 << SND_PCM_SFMT_GSM)
Constants with prefix SND_PCM_FMT_ are used in info structures and constants with prefix SND_PCM_SFMT_ are used in format structures.
ALSA PCM API uses an enhanced double buffering scheme. This allows the user to implement a more comfortable buffer setup. Audio buffer is separated to small fragments. Each fragment has the same size. Application can set wakeup limits like ``I want to get recorded data when at least two fragments with size 160 bytes are filled.''. For more information you should see description of snd_pcm_*_params_t and snd_pcm_*_status_t structures and the snd_pcm_playback_status(), snd_pcm_record_status() functions, documented below.
Creates a new handle and opens a connection to the kernel sound audio interface for sound card number card (0-N) and audio device number device. Function also checks if protocol is compatible to prevent use of old programs with a new kernel API. Function returns zero if successful otherwise it returns an error code. Error code -EBUSY is returned when some process owns the selected direction.
Default format after opening is mono mu-Law at 8000Hz. This device can be used directly for playback of standard .au (Sparc) files.
The following modes should be used for the mode argument:
#define SND_PCM_OPEN_RECORD (O_RDONLY)
#define SND_PCM_OPEN_DUPLEX (O_RDWR)
Frees all resources allocated with audio handle and closes the connection to the kernel sound audio interface. Function returns zero if successful, otherwise it returns an error code.
Returns the file descriptor of the connection to the kernel sound audio interface. Function returns an error code if an error was encountered.
The file descriptor should be used for the select(2) synchronous multiplexer function for setting the read direction. Application should call snd_pcm_read() or snd_pcm_write() functions if data is waiting to be read or a write can be performed. Calling these functions is highly recommended, as it leaves a place for the API to do things like data conversions, if needed.
Sets up block (default) or non-block mode for a handle. Block mode suspends execution of a program when snd_pcm_read() or snd_pcm_write() is called for the time which is needed for the actual playback or record over of the selected limit. In non-block mode, programs aren't suspended and the above functions return immediately with the count of bytes which were read or written by the driver. When used in this way, don't try to use the entire buffer after the call, but instead process the number of bytes returned, and call the function again.
Fills the *info structure with data about the PCM device selected by *handle. Function returns zero if successful, otherwise it returns an error code.
#define SND_PCM_INFO_CODEC 0x00000001
#define SND_PCM_INFO_DSP SND_PCM_INFO_CODEC
/* this flag is reserved and should be never used */
/* It remains for compatibility with Open Sound System driver. */
#define SND_PCM_INFO_MMAP 0x00000002
/* playback direction is supported */
#define SND_PCM_INFO_PLAYBACK 0x00000100
/* record direction is supported */
#define SND_PCM_INFO_RECORD 0x00000200
#define SND_PCM_INFO_DUPLEX 0x00000400
/* rate for playback & record must be same */
#define SND_PCM_INFO_DUPLEX_LIMIT 0x00000800
/* duplex is supported only by mono (one channel) format */
#define SND_PCM_INFO_DUPLEX_MONO 0x00001000
/* sound card type */
unsigned int type;
/* see SND_PCM_INFO_XXXX */
unsigned int flags;
/* ID of this PCM device */
unsigned char id[32];
/* name of this device */
unsigned char name[80];
/* reserved for future use */
unsigned char reserved[64];
};
Fills the *info structure with data about PCM playback. Function returns zero if successful, otherwise it returns an error code.
#define SND_PCM_PINFO_8BITONLY 0x00000002
#define SND_PCM_PINFO_16BITONLY 0x00000004
/* see SND_PCM_PINFO_XXXX */
unsigned int flags;
/* supported formats */
unsigned int formats;
/* min rate (in Hz) */
unsigned int min_rate;
/* max rate (in Hz) */
unsigned int max_rate;
/* min channels - voices (probably always 1) */
unsigned int min_channels;
/* max channels - voices */
unsigned int max_channels;
/* playback buffer size in bytes */
unsigned int buffer_size;
/* min fragment size in bytes */
unsigned int min_fragment_size;
/* max fragment size in bytes */
unsigned int max_fragment_size;
/* align fragment value */
unsigned int fragment_align;
/* supported formats directly by hardware */
unsigned int hw_formats;
/* count of playback switches */
unsigned int switches;
/* reserved for future use */
unsigned char reserved[56];
};
Fills the *info structure. Returns zero if successful, otherwise it returns an error code.
#define SND_PCM_RINFO_8BITONLY 0x00000002
#define SND_PCM_RINFO_16BITONLY 0x00000004
#define SND_PCM_RINFO_OVERRANGE 0x00001000
/* see SND_PCM_RINFO_XXXX */
unsigned int flags;
/* supported formats */
unsigned int formats;
/* min rate (in Hz) */
unsigned int min_rate;
/* max rate (in Hz) */
unsigned int max_rate;
/* min channels - voices (probably always 1) */
unsigned int min_channels;
/* max channels - voices */
unsigned int max_channels;
/* playback buffer size in bytes */
unsigned int buffer_size;
/* min fragment size in bytes */
unsigned int min_fragment_size;
/* max fragment size in bytes */
unsigned int max_fragment_size;
/* align fragment value */
unsigned int fragment_align;
/* supported formats directly by hardware */
unsigned int hw_formats;
/* count of record switches */
unsigned int switches;
/* reserved for future use */
unsigned char reserved[56];
};
Returns count of PCM playback switches. In this contents switch means universal control interface between kernel and application which allows variable type control. Function returns count if successful, otherwise it returns an error code. Return value should be zero if sound card doesn't have any PCM playback switch.
Returns index for switch with name switch_id. Function returns switch index if successful, otherwise it returns an error code.
Fills the *data structure with data about switch with index switchn. Function returns zero if successful, otherwise it returns an error code.
#define SND_PCM_SW_TYPE_BOOLEAN 0
/* 0 to 255 - from low to high (data8[0] member of union) */
#define SND_PCM_SW_TYPE_BYTE 1
/* 0 to 65535 - from low to high (data16[0] member of union) */
#define SND_PCM_SW_TYPE_WORD 2
/* 0 to 4294967296 ¯ from low to high (data32[0] member of union) */
#define SND_PCM_SW_TYPE_DWORD 3
/* user type - no type control */
#define SND_PCM_SW_TYPE_USER (~0)
/* switch index (filled by application) */
unsigned int switchn;
/* identification of switch (for driver) */
unsigned char name[32];
/* type of switch value ¯ See SND_PCM_SW_TYPE_XXXX */
unsigned int type;
/* low range value */
unsigned int low;
/* high range value */
unsigned int high;
union {
unsigned int enable; /* 0 = off 1 = on */
unsigned char data8[32]; /* 8-bit data */
unsigned short data16[16]; /* 16-bit data */
unsigned int data32[8]; /* 32-bit data */
} value;
/* reserved for future use ¯ must be zero !!! */
unsigned char reserved[32];
}
Writes the *data structure with data about switch with index switchn to kernel. Function returns zero if successful, otherwise it returns an error code.
Returns count of PCM record switches. In this context 'switch' means universal control interface between kernel and application which allows various types of control. Function returns count if successful, otherwise it returns an error code. Return value should be zero if sound card doesn't have any PCM record switch.
Returns index for switch with name switch_id. Function returns switch index if successful, otherwise it returns an error code.
Fills the *data structure with data about switch with index switchn. Function returns zero if successful, otherwise it returns an error code.
Writes the *data structure with data about switch with index switchn to kernel. Function returns zero if successful, otherwise it returns an error code.
Sets up format, rate (in Hz) and number of channels for playback, in the desired direction. Function returns zero if successful, otherwise it returns an error code.
unsigned int format; /* SND_PCM_SFMT_XXXX */
unsigned int rate; /* rate in Hz */
unsigned int channels; /* channels (voices) */
unsigned char reserved[16];
};
Sets up format, rate (in Hz) and number of channels for used for recording in the specified direction. Function returns zero if successful, otherwise it returns an error code.
unsigned int format; /* SND_PCM_SFMT_XXXX */
unsigned int rate; /* rate in Hz */
unsigned int channels; /* channels (voices) */
unsigned char reserved[16];
};
Sets various parameters for playback direction. Function returns zero if successful, otherwise it returns an error code.
int fragment_size;
int fragments_max;
int fragments_room;
/* reserved for future use - must be filled with zero */
unsigned char reserved[16];
};
Function sets various parameters for the recording direction. Function returns zero if successful, otherwise it returns an error code.
int fragment_size;
int fragments_min;
/* reserved for future use - must be filled with zero */
unsigned char reserved[16];
};
Fills the *status structure. Function returns zero if successful, otherwise it returns an error code.
unsigned int rate;
int fragments;
int fragment_size;
int count;
int queue;
int underrun;
struct timeval time;
struct timeval stime;
int scount;
/* reserved for future use - must be filled with zero */
unsigned char reserved[16];
};
Fills the *status structure. Function returns zero if successful, otherwise it returns an error code.
unsigned int rate;
int fragments;
int fragment_size;
int count;
int free;
int overrun;
struct timeval time;
struct timeval stime;
int scount;
int overrange;
/* reserved for future use - must be filled with zero */
unsigned char reserved[16];
};
This function stops and drains (destroys) the playback buffers immediately. Function returns zero if successful, otherwise it returns an error code.
This function flushes the playback buffers. It blocks the program while the all the waiting samples in kernel playback buffers are processed. Function returns zero if successful, otherwise it returns an error code.
This function flushes (destroys) record buffers. Function returns zero if successful, otherwise it returns an error code.
This function pauses playback if enable is non-zero. To restore playing mode call this function with enable equal to zero. Function returns zero if successful, otherwise it returns an error code.
This function enables or disables time mode for the playback direction. Time mode is useful in synchronizing an application with other events. Function returns zero if successful, otherwise it returns an error code.
This function enables or disables time mode for record direction. Time mode is useful in synchronizing an application with other events. Function returns zero if successful, otherwise it returns an error code.
Writes samples to the device which must be in the proper format specified by the snd_pcm_playback_format function. Function returns zero or positive value if playback was successful (value represents count of bytes which were successfully written to device) or an error value if an error occurred. Function will suspend process if block mode is active.
Function reads samples from driver. Samples are in format specified by snd_pcm_record_format function. Function returns zero or positive value if record was success (value represents count of bytes which was successfully read from device) or negative error value if error occurred. Function will suspend process if block mode is active.
The following example shows how to play the first 512kB from the /tmp/test.au file with sound card #0 and PCM device #0:
void *handle;
snd_pcm_format_t format;
char *buffer;
if (!buffer) return;
if ((err = snd_pcm_open(&handle, card, device,
SND_PCM_OPEN_PLAYBACK)) < 0) {
fprintf(stderr, "open failed: %s\n", snd_strerror( err ));
return;
}
bzero(&format sizeof(format));
format.format = SND_PCM_SFMT_MU_LAW;
format.rate = 8000;
format.channels = 1;
if ((err = snd_pcm_playback_format(handle, &format)) < 0) {
fprintf(stderr, "format setup failed: %s\n",
snd_strerror( err ));
snd_pcm_close( handle );
return;
}
fd = open("/tmp/test.au", O_RDONLY);
if (fd < 0) {
perror("open file");
snd_pcm_close(handle);
return;
}
idx = 0;
count = read(fd, buffer, 512 * 1024);
if (count <= 0) {
perror("read from file");
snd_pcm_close( handle );
return;
}
close( fd );
if (!memcmp(buffer, ".snd", 4)) {
idx = (buffer[4]<<24)|(buffer[5]<<16)|
(buffer[6]<<8)|(buffer[7]);
if (idx > 128) idx = 128;
if (idx > count) idx = count;
}
size = snd_pcm_write(handle, &buffer[ idx ], count - idx);
printf("Bytes written %i from %i...\n", size, count - idx);
snd_pcm_close(handle);
free(buffer);
This interface is designed to pass data currently being played or recorded from one application to another application for other processing like a graphical equalizer sample recorder etc... The programmer should be aware that each loopback connection eats CPU time (for data copying from the process which is doing the playback or record).
Creates a new handle and opens a connection to the kernel sound audio loopback interface for sound card number card (0-N) and audio device number device. Function also checks if protocol is compatible to prevent use of old programs with a new kernel API. Function returns zero if successful otherwise it returns an error code. Error code -EBUSY is returned when another process owns the selected direction.
The following modes should be used for the mode argument:
#define SND_PCM_LB_OPEN_RECORD 1
Frees all resources allocated with audio handle and closes the connection to the kernel sound audio interface. Function returns zero if successful, otherwise it returns an error code.
Returns the file descriptor of the connection to the kernel sound audio interface. Function returns an error code if an error was encountered.
The file descriptor should be used for the select(2) synchronous multiplexer function for setting the read direction. Application should call snd_pcm_loopback_read() function if data is waiting to be read.
Sets up block (default) or non-block mode for a handle. Block mode suspends execution of a program when snd_pcm_loopback_read() is called for the time until some data arrives for file descriptor. In non-block mode, programs aren't suspended and the above function returns immediately with the count of bytes which were read by the driver. When used in this way, don't try to use the entire buffer after the call, but instead process the number of bytes returned, and call the function again.
Sets up stream mode which should be one of these values:
#define SND_PCM_LB_STREAM_MODE_PACKET 1
Mode raw (default mode) means that the stream contains only PCM samples. Packet mode is more complicated. The stream contains a header at the begining of the packet. Information like data type and data size is contain in this header.
#define SND_PCM_LB_TYPE_FORMAT 1 /* PCM format */
unsigned int size; /* block size */
unsigned int type; /* block type (SND_PCM_LB_TYPE_*) */
};
Get current format for PCM stream.
unsigned int format; /* SND_PCM_SFMT_XXXX */
unsigned int rate; /* rate in Hz */
unsigned int channels; /* number of channels (voices) */
unsigned char reserved[16];
};
This function reads samples or loopback packets from the stream. Data depends on stream mode which should be set with snd_pcm_loopback_stream_mode() function. Function returns zero or positive value if record was success (value represents count of bytes which were successfully read from device) or negative error value if error occurred. Function will suspend process if block mode is active.
RawMidi Interface is designed to write or read raw (unchanged) MIDI data over the MIDI line. MIDI stands Musical Instrument Digital Interface and more informations about this standard can be found at http://www.midi.org.
RawMidi devices are opened exclusively for a selected direction. While more than one process may not open a given MIDI device in the same direction simultaniously, seperate processes may open a single MIDI device in different directions (i.e. process one opens a MIDI device in playback direction and process two opens the same device in record direction). Audio devices (with MIDI ports) return EBUSY error to applications when other applications have already opened the requested direction.
Creates a new handle and opens a connection to the kernel sound audio interface for sound card number card (0-N) and rawmidi device number device. Function also checks if protocol is compatible to prevent use of old programs with a new kernel API. Function returns zero if successful, otherwise it returns an error code. Error code -EBUSY is returned when another process owns the selected direction.
The following modes should be used for the mode argument:
#define SND_RAWMIDI_OPEN_INPUT (O_RDONLY)
#define SND_RAWMIDI_OPEN_DUPLEX (O_RDWR)
Frees all resources allocated with audio handle and closes the connection to the kernel sound rawmidi interface. Function returns zero if successful, otherwise it returns an error code.
Returns the file descriptor of the connection to the kernel sound audio interface. Function returns an error code if an error was encountered.
The file descriptor should be used for the select(2) synchronous multiplexer function for setting the read direction. Application should call snd_rawmidi_read() or snd_rawmidi_write() functions if data is waiting to be read or a write can be performed. Calling these functions is highly recommended.
Sets up block (default) or non-block mode for a handle. Block mode suspends execution of a program when snd_rawmidi_read() or snd_rawmidi_write() is called for the time which is needed for the actual output or input over of the selected limit. In non-block mode, programs aren't suspended and the above functions return immediately with the count of bytes which were read or written by the driver. When used in this way, don't try to use the entire buffer after the call, but instead process the number of bytes returned, and call the function again.
Fills the *info structure with data about the PCM device selected by *handle. Function returns zero if successful, otherwise it returns an error code.
#define SND_RAWMIDI_INFO_OUTPUT 0x00000001
/* device is capable rawmidi input */
#define SND_RAWMIDI_INFO_INPUT 0x00000002
/* device is capable duplex mode */
#define SND_RAWMIDI_INFO_DUPLEX 0x00000004
/* sound card type */
unsigned int type;
/* see SND_RAWMIDI_INFO_XXXX */
unsigned int flags;
/* ID of this PCM device */
unsigned char id[32];
/* name of this device */
unsigned char name[80];
/* reserved for future use */
unsigned char reserved[64];
};
Fills the *info structure with data about rawmidi output. Function returns zero if successful, otherwise it returns an error code.
/* count of output switches */
unsigned int switches;
/* reserved for future use */
unsigned char reserved[64];
};
Fills the *info structure. Returns zero if successful, otherwise it returns an error code.
/* count of output switches */
unsigned int switches;
/* reserved for future use */
unsigned char reserved[64];
};
Returns count of rawmidi output switches. In this context 'switch' means universal control interface between kernel and application which allows various types of control. Function returns count if successful, otherwise it returns an error code. Return value should be zero if sound card doesn't have any rawmidi output switch.
Returns index for switch with name switch_id. Function returns switch index if successful, otherwise it returns an error code.
Fills the *data structure with data about switch with index switchn. Function returns zero if successful, otherwise it returns an error code.
#define SND_PCM_SW_TYPE_BOOLEAN 0
/* 0 to 255 - from low to high (data8[0] member of union) */
#define SND_PCM_SW_TYPE_BYTE 1
/* 0 to 65535 - from low to high (data16[0] member of union) */
#define SND_PCM_SW_TYPE_WORD 2
/* 0 to 4294967296 ¯ from low to high (data32[0] member of union) */
#define SND_PCM_SW_TYPE_DWORD 3
/* user type - no type control */
#define SND_PCM_SW_TYPE_USER (~0)
/* switch index (filled by application) */
unsigned int switchn;
/* identification of switch (for driver) */
unsigned char name[32];
/* type of switch value ¯ See SND_PCM_SW_TYPE_XXXX */
unsigned int type;
/* low range value */
unsigned int low;
/* high range value */
unsigned int high;
union {
unsigned int enable; /* 0 = off 1 = on */
unsigned char data8[32]; /* 8-bit data */
unsigned short data16[16]; /* 16-bit data */
unsigned int data32[8]; /* 32-bit data */
} value;
/* reserved for future use ¯ must be zero !!! */
unsigned char reserved[32];
}
Writes the *data structure with data about switch with index switchn to kernel. Function returns zero if successful, otherwise it returns an error code.
Returns count of rawmidi input switches. In this context 'switch' means universal control interface between kernel and application which allows various types of control. Function returns count if successful, otherwise it returns an error code. Return value should be zero if sound card doesn't have any rawmidi input switch.
Returns index for switch with name switch_id. Function returns switch index if successful, otherwise it returns an error code.
Fills the *data structure with data about switch with index switchn. Function returns zero if successful, otherwise it returns an error code.
Writes the *data structure with data about switch with index switchn to kernel. Function returns zero if successful, otherwise it returns an error code.
Sets various parameters for output direction. Function returns zero if successful, otherwise it returns an error code.
int size;
int max;
int room;
/* reserved for future use - must be filled with zero */
unsigned char reserved[16];
};
Function sets various parameters for the recording direction. Function returns zero if successful, otherwise it returns an error code.
int size;
int min;
/* reserved for future use - must be filled with zero */
unsigned char reserved[16];
};
Fills the *status structure. Function returns zero if successful, otherwise it returns an error code.
int size;
int count;
int queue;
/* reserved for future use - must be filled with zero */
unsigned char reserved[16];
};
Fills the *status structure. Function returns zero if successful, otherwise it returns an error code.
int size;
int count;
int free;
int overrun;
/* reserved for future use - must be filled with zero */
unsigned char reserved[16];
};
This function stops and drains (destroys) the output queue immediately. Function returns zero if successful, otherwise it returns an error code.
This function flushes the output queue. It blocks the program while the all the waiting bytes in kernel output queue are processed. Function returns zero if successful, otherwise it returns an error code.
This function flushes (destroys) input queue. Function returns zero if successful, otherwise it returns an error code.
Writes bytes to the output queue. Function returns zero or positive value if the write was successful (value represents count of bytes which were successfully written to the device) or an error value if error occurred. Function will suspend the process if block mode is active.
Function reads bytes from input queue. Function returns zero or positive value if the read was successful (value represents count of bytes which were successfully read from device) or negative error value if error occurred. Function will suspend the process if block mode is active.
The following example shows how to send a control sequence (such as SysEx) to a MIDI device. Sound card #0 and rawmidi device #0 are used here:
void *handle;
snd_pcm_format_t format;
char *buffer;
if (!buffer) return;
if ((err = snd_rawmidi_open(&handle, card, device,
SND_RAWMIDI_OPEN_OUTPUT)) < 0) {
fprintf(stderr, "open failed: %s\n", snd_strerror( err ));
return;
}
if ((err = snd_rawmidi_block_mode(handle 1)) < 0) {
fprintf(stderr, "block failed: %s\n", snd_strerror( err ));
snd_rawmidi_close(handle);
return;
}
fd = open("/tmp/test.sysex", O_RDONLY);
if (fd < 0) {
perror("open file");
snd_rawmidi_close(handle);
return;
}
idx = 0;
count = read(fd, buffer, 64 * 1024);
if (count <= 0) {
perror("read from file");
snd_rawmidi_close(handle);
return;
}
close(fd);
size = snd_rawmidi_write(handle, &buffer, count);
printf("Bytes written %i from %i...\n", size, count);
snd_rawmidi_close(handle);
free(buffer);