IV. PCM direct access

Audio devices are opened exclusively for a selected direction. This does not 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.

The driver supports these sample formats:

FormatDescription
SND_PCM_SFMT_S8Signed 8-bit sample.
SND_PCM_SFMT_U8Unsigned 8-bit sample.
SND_PCM_SFMT_S16_LESigned little endian 16-bit sample.
SND_PCM_SFMT_S16_BESigned big endian 16-bit sample.
SND_PCM_SFMT_U16_LEUnsigned little endian 16-bit sample.
SND_PCM_SFMT_U16_BEUnsigned big endian 16-bit sample.
SND_PCM_SFMT_S24_LESigned little endian 24-bit sample (in 32-bit word).
SND_PCM_SFMT_S24_BESigned big endian 24-bit sample (in 32-bit word).
SND_PCM_SFMT_U24_LEUnsigned little endian 24-bit sample (in 32-bit word).
SND_PCM_SFMT_U24_BEUnsigned big endian 24-bit sample (in 32-bit word).
SND_PCM_SFMT_S32_LESigned little endian 32-bit sample.
SND_PCM_SFMT_S32_BESigned big endian 32-bit sample.
SND_PCM_SFMT_U32_LEUnsigned little endian 32-bit sample.
SND_PCM_SFMT_U32_BEUnsigned big endian 32-bit sample.
SND_PCM_SFMT_FLOAT_LELittle endian float in 32-bit word (IEE-754).
SND_PCM_SFMT_FLOAT_BEBig endian float in 32-bit word (IEE-754).
SND_PCM_SFMT_FLOAT64_LELittle endian float in 64-bit word (IEE-754).
SND_PCM_SFMT_FLOAT64_BEBig endian float in 64-bit word (IEE-754).
SND_PCM_SFMT_MU_LAWMu-law compression (one byte per sample).
SND_PCM_SFMT_A_LAWA-law compression (one byte per sample).
SND_PCM_SFMT_IMA_ADPCMIma ADPCM compression (four bits per sample).
SND_PCM_SFMT_MPEGMPEG compression.
SND_PCM_SFMT_GSMGSM compression.
SND_PCM_SFMT_SPECIALHardware dependent sample format.

Constants with prefix SND_PCM_FMT_ are used in info structures (bitmaps) and constants with prefix SND_PCM_SFMT_ are used in format structures.

24-bit linear samples are using three low bytes from the 32-bit word. When hardware uses 24-bit format in 32-bit linear samples (the low byte is ignored), then the sample format is 32-bit, and the msbits_per_sample member from the snd_pcm_channel_setup_t structure shows count of most significant bits being used (24 in this case). The other formats (for example 20-bit linear sample stored in the 32-bit linear sample) may follow this example as well.

ALSA PCM API uses two operating modes - block and stream. The block mode 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 captured data when at least two fragments with size 160 bytes are filled.''. For more information you should see description of snd_pcm_channel_params_t and snd_pcm_channel_status_t structures and the snd_pcm_channel_setup function, documented below.

The stream mode may be used for real-time audio applications. The driver allows to transfer data with the sample resolution. The process using the audio device in this mode is never blocked. Only one parameter for buffering is required - queue size. There are no other boundaries like fragments. The driver directly operates with the hardware ring buffer in this mode.

The ALSA drivers does not offer the data conversions on the fly at all. If you want to write an application which is able to run on most hardware, use the PCM plugin layer.

The driver manages various states. The PCM calls, available at some time, depend heavy on the current state.

StateDescription
SND_PCM_STATUS_NOTREADYThe driver is not prepared for any operation. After successful snd_pcm_channel_params call the state will be changed to SND_PCM_STATUS_READY.
SND_PCM_STATUS_READYThe driver is ready for operation. The audio buffer may be mmaped only at this moment, but the samples can not be still transferred. After successful snd_pcm_channel_prepare call the state will be changed to SND_PCM_STATUS_PREPARED.
SND_PCM_STATUS_PREPAREDThe driver is prepared for operation. The samples may be transferred at this moment.
SND_PCM_STATUS_RUNNINGThe driver manages running stream. The samples may be transferred at this moment.
SND_PCM_STATUS_UNDERRUNThe playback direction is in underrun state. It means that the driver did not get the data in right time. Only snd_pcm_playback_prepare call or snd_pcm_playback_flush call or snd_pcm_playback_drain call may change this state.
SND_PCM_STATUS_OVERRUNThe capture direction is in overrun state. It means that hardware have not received the data in right time. Only snd_pcm_capture_prepare call or snd_pcm_capture_flush call may change this state.
SND_PCM_STATUS_PAUSEThe playback is paused.

Table of Contents
PCM structures — references to all PCM structures
snd_pcm_open — open a PCM device
snd_pcm_open_subdevice — open a PCM subdevice
snd_pcm_close — close a PCM handle
snd_pcm_file_descriptor — obtain PCM file descriptor
snd_pcm_nonblock_mode — set or reset the block behaviour
snd_pcm_info — obtain general information about the PCM device
snd_pcm_channel_info — obtain information about the PCM direction
snd_pcm_channel_params — set PCM communication parameters
snd_pcm_channel_setup — obtain current PCM setup
snd_pcm_channel_status — obtain current PCM run-time status
snd_pcm_channel_prepare — prepare the selected direction
snd_pcm_channel_go — start selected direction
snd_pcm_sync_go — start the group of PCM channels
snd_pcm_playback_drain — drain playback queue
snd_pcm_channel_flush — flush buffers
snd_pcm_playback_pause — pause the playback direction
snd_pcm_transfer_size — determine size of transfer block
snd_pcm_write — transfer PCM stream to playback subdevice
snd_pcm_read — transfer PCM stream from capture subdevice
snd_pcm_writev — send PCM stream to playback (using I/O vector)
snd_pcm_readv — transfer PCM stream from capture (using I/O vector)
snd_pcm_mmap — mmap the hardware buffers to the user space
snd_pcm_munmap — unmap the hardware buffers to the user space
snd_pcm_format_signed — checking for signed format
snd_pcm_format_unsigned — checking for unsigned format
snd_pcm_format_linear — checking for linear format
snd_pcm_format_little_endian — checking for little endian format
snd_pcm_format_big_endian — checking for big endian format
snd_pcm_format_width — obtain sample width in bits
snd_pcm_build_linear_format — build linear format
snd_pcm_format_size — convert size in samples to bytes
snd_pcm_get_format_name — obtain a name of format