ALSA project - the C library reference: PCM Interface

ALSA project - the C library reference

Loading...
Searching...
No Matches
Topics | Files | Data Structures | Macros | Typedefs | Enumerations | Functions
PCM Interface

## Topics
| Stream Information
| Hardware Parameters
| Software Parameters
| Access Mask Functions
| Format Mask Functions
| Subformat Mask Functions
| Status Functions
| Description Functions
| Debug Functions
| Direct Access (MMAP) Functions
| Helper Functions
| Hook Extension
| Scope Plugin Extension
| Simple setup functions
| Deprecated Functions

## Files
file | pcm.c
| PCM Interface.
file | pcm_plugin.c
| PCM Interface.

## Data Structures
struct | snd_pcm_audio_tstamp_config_t
struct | snd_pcm_audio_tstamp_report_t
struct | snd_pcm_channel_area_t
union | snd_pcm_sync_id_t
struct | snd_pcm_chmap_t
struct | snd_pcm_chmap_query_t

## Macros
#define | SND_PCM_DLSYM_VERSION _dlsym_pcm_001
#define | SND_PCM_NONBLOCK
#define | SND_PCM_ASYNC
#define | SND_PCM_EINTR 0x00000080
#define | SND_PCM_ABORT 0x00008000
#define | SND_PCM_NO_AUTO_RESAMPLE 0x00010000
#define | SND_PCM_NO_AUTO_CHANNELS 0x00020000
#define | SND_PCM_NO_AUTO_FORMAT 0x00040000
#define | SND_PCM_NO_SOFTVOL 0x00080000
#define | SND_PCM_WAIT_INFINITE (-1)
#define | SND_PCM_WAIT_IO (-10001)
#define | SND_PCM_WAIT_DRAIN (-10002)
#define | SND_CHMAP_API_VERSION ((1 << 16) | (0 << 8) | 1)
#define | SND_CHMAP_POSITION_MASK 0xffff
#define | SND_CHMAP_PHASE_INVERSE (0x01 << 16)
#define | SND_CHMAP_DRIVER_SPEC (0x02 << 16)

## Typedefs
typedef struct _snd_pcm_info | snd_pcm_info_t
typedef struct _snd_pcm_hw_params | snd_pcm_hw_params_t
typedef struct _snd_pcm_sw_params | snd_pcm_sw_params_t
typedef struct _snd_pcm_status | snd_pcm_status_t
typedef struct _snd_pcm_access_mask | snd_pcm_access_mask_t
typedef struct _snd_pcm_format_mask | snd_pcm_format_mask_t
typedef struct _snd_pcm_subformat_mask | snd_pcm_subformat_mask_t
typedef unsigned long | snd_pcm_uframes_t
typedef long | snd_pcm_sframes_t
typedef struct _snd_pcm | snd_pcm_t
typedef enum _snd_pcm_type | snd_pcm_type_t
typedef struct _snd_pcm_scope | snd_pcm_scope_t

## Enumerations
enum | snd_pcm_class_t { SND_PCM_CLASS_GENERIC = 0 , SND_PCM_CLASS_MULTI , SND_PCM_CLASS_MODEM , SND_PCM_CLASS_DIGITIZER , SND_PCM_CLASS_LAST = SND_PCM_CLASS_DIGITIZER }
enum | snd_pcm_subclass_t { SND_PCM_SUBCLASS_GENERIC_MIX = 0 , SND_PCM_SUBCLASS_MULTI_MIX , SND_PCM_SUBCLASS_LAST = SND_PCM_SUBCLASS_MULTI_MIX }
enum | snd_pcm_stream_t { SND_PCM_STREAM_PLAYBACK = 0 , SND_PCM_STREAM_CAPTURE , SND_PCM_STREAM_LAST = SND_PCM_STREAM_CAPTURE }
enum | snd_pcm_access_t { SND_PCM_ACCESS_MMAP_INTERLEAVED = 0 , SND_PCM_ACCESS_MMAP_NONINTERLEAVED , SND_PCM_ACCESS_MMAP_COMPLEX , SND_PCM_ACCESS_RW_INTERLEAVED , SND_PCM_ACCESS_RW_NONINTERLEAVED , SND_PCM_ACCESS_LAST = SND_PCM_ACCESS_RW_NONINTERLEAVED }
enum | snd_pcm_format_t { SND_PCM_FORMAT_UNKNOWN = -1 , SND_PCM_FORMAT_S8 = 0 , SND_PCM_FORMAT_U8 , SND_PCM_FORMAT_S16_LE , SND_PCM_FORMAT_S16_BE , SND_PCM_FORMAT_U16_LE , SND_PCM_FORMAT_U16_BE , SND_PCM_FORMAT_S24_LE , SND_PCM_FORMAT_S24_BE , SND_PCM_FORMAT_U24_LE , SND_PCM_FORMAT_U24_BE , SND_PCM_FORMAT_S32_LE , SND_PCM_FORMAT_S32_BE , SND_PCM_FORMAT_U32_LE , SND_PCM_FORMAT_U32_BE , SND_PCM_FORMAT_FLOAT_LE , SND_PCM_FORMAT_FLOAT_BE , SND_PCM_FORMAT_FLOAT64_LE , SND_PCM_FORMAT_FLOAT64_BE , SND_PCM_FORMAT_IEC958_SUBFRAME_LE , SND_PCM_FORMAT_IEC958_SUBFRAME_BE , SND_PCM_FORMAT_MU_LAW , SND_PCM_FORMAT_A_LAW , SND_PCM_FORMAT_IMA_ADPCM , SND_PCM_FORMAT_MPEG , SND_PCM_FORMAT_GSM , SND_PCM_FORMAT_S20_LE , SND_PCM_FORMAT_S20_BE , SND_PCM_FORMAT_U20_LE , SND_PCM_FORMAT_U20_BE , SND_PCM_FORMAT_SPECIAL = 31 , SND_PCM_FORMAT_S24_3LE = 32 , SND_PCM_FORMAT_S24_3BE , SND_PCM_FORMAT_U24_3LE , SND_PCM_FORMAT_U24_3BE , SND_PCM_FORMAT_S20_3LE , SND_PCM_FORMAT_S20_3BE , SND_PCM_FORMAT_U20_3LE , SND_PCM_FORMAT_U20_3BE , SND_PCM_FORMAT_S18_3LE , SND_PCM_FORMAT_S18_3BE , SND_PCM_FORMAT_U18_3LE , SND_PCM_FORMAT_U18_3BE , SND_PCM_FORMAT_G723_24 , SND_PCM_FORMAT_G723_24_1B , SND_PCM_FORMAT_G723_40 , SND_PCM_FORMAT_G723_40_1B , SND_PCM_FORMAT_DSD_U8 , SND_PCM_FORMAT_DSD_U16_LE , SND_PCM_FORMAT_DSD_U32_LE , SND_PCM_FORMAT_DSD_U16_BE , SND_PCM_FORMAT_DSD_U32_BE , SND_PCM_FORMAT_LAST = SND_PCM_FORMAT_DSD_U32_BE , SND_PCM_FORMAT_S16 = SND_PCM_FORMAT_S16_LE , SND_PCM_FORMAT_U16 = SND_PCM_FORMAT_U16_LE , SND_PCM_FORMAT_S24 = SND_PCM_FORMAT_S24_LE , SND_PCM_FORMAT_U24 = SND_PCM_FORMAT_U24_LE , SND_PCM_FORMAT_S32 = SND_PCM_FORMAT_S32_LE , SND_PCM_FORMAT_U32 = SND_PCM_FORMAT_U32_LE , SND_PCM_FORMAT_FLOAT = SND_PCM_FORMAT_FLOAT_LE , SND_PCM_FORMAT_FLOAT64 = SND_PCM_FORMAT_FLOAT64_LE , SND_PCM_FORMAT_IEC958_SUBFRAME = SND_PCM_FORMAT_IEC958_SUBFRAME_LE , SND_PCM_FORMAT_S20 = SND_PCM_FORMAT_S20_LE , SND_PCM_FORMAT_U20 = SND_PCM_FORMAT_U20_LE }
enum | snd_pcm_subformat_t { SND_PCM_SUBFORMAT_UNKNOWN = -1 , SND_PCM_SUBFORMAT_STD = 0 , SND_PCM_SUBFORMAT_MSBITS_MAX = 1 , SND_PCM_SUBFORMAT_MSBITS_20 = 2 , SND_PCM_SUBFORMAT_MSBITS_24 = 3 , SND_PCM_SUBFORMAT_LAST = SND_PCM_SUBFORMAT_MSBITS_24 }
enum | snd_pcm_state_t { SND_PCM_STATE_OPEN = 0 , SND_PCM_STATE_SETUP , SND_PCM_STATE_PREPARED , SND_PCM_STATE_RUNNING , SND_PCM_STATE_XRUN , SND_PCM_STATE_DRAINING , SND_PCM_STATE_PAUSED , SND_PCM_STATE_SUSPENDED , SND_PCM_STATE_DISCONNECTED , SND_PCM_STATE_LAST = SND_PCM_STATE_DISCONNECTED , SND_PCM_STATE_PRIVATE1 = 1024 }
enum | snd_pcm_start_t { SND_PCM_START_DATA = 0 , SND_PCM_START_EXPLICIT , SND_PCM_START_LAST = SND_PCM_START_EXPLICIT }
enum | snd_pcm_xrun_t { SND_PCM_XRUN_NONE = 0 , SND_PCM_XRUN_STOP , SND_PCM_XRUN_LAST = SND_PCM_XRUN_STOP }
enum | snd_pcm_tstamp_t { SND_PCM_TSTAMP_NONE = 0 , SND_PCM_TSTAMP_ENABLE , SND_PCM_TSTAMP_MMAP = SND_PCM_TSTAMP_ENABLE , SND_PCM_TSTAMP_LAST = SND_PCM_TSTAMP_ENABLE }
enum | snd_pcm_tstamp_type_t { SND_PCM_TSTAMP_TYPE_GETTIMEOFDAY = 0 , SND_PCM_TSTAMP_TYPE_MONOTONIC , SND_PCM_TSTAMP_TYPE_MONOTONIC_RAW , SND_PCM_TSTAMP_TYPE_LAST = SND_PCM_TSTAMP_TYPE_MONOTONIC_RAW }
enum | snd_pcm_audio_tstamp_type_t { SND_PCM_AUDIO_TSTAMP_TYPE_COMPAT = 0 , SND_PCM_AUDIO_TSTAMP_TYPE_DEFAULT = 1 , SND_PCM_AUDIO_TSTAMP_TYPE_LINK = 2 , SND_PCM_AUDIO_TSTAMP_TYPE_LINK_ABSOLUTE = 3 , SND_PCM_AUDIO_TSTAMP_TYPE_LINK_ESTIMATED = 4 , SND_PCM_AUDIO_TSTAMP_TYPE_LINK_SYNCHRONIZED = 5 , SND_PCM_AUDIO_TSTAMP_TYPE_LAST = SND_PCM_AUDIO_TSTAMP_TYPE_LINK_SYNCHRONIZED }
enum | _snd_pcm_type { SND_PCM_TYPE_HW = 0 , SND_PCM_TYPE_HOOKS , SND_PCM_TYPE_MULTI , SND_PCM_TYPE_FILE , SND_PCM_TYPE_NULL , SND_PCM_TYPE_SHM , SND_PCM_TYPE_INET , SND_PCM_TYPE_COPY , SND_PCM_TYPE_LINEAR , SND_PCM_TYPE_ALAW , SND_PCM_TYPE_MULAW , SND_PCM_TYPE_ADPCM , SND_PCM_TYPE_RATE , SND_PCM_TYPE_ROUTE , SND_PCM_TYPE_PLUG , SND_PCM_TYPE_SHARE , SND_PCM_TYPE_METER , SND_PCM_TYPE_MIX , SND_PCM_TYPE_DROUTE , SND_PCM_TYPE_LBSERVER , SND_PCM_TYPE_LINEAR_FLOAT , SND_PCM_TYPE_LADSPA , SND_PCM_TYPE_DMIX , SND_PCM_TYPE_JACK , SND_PCM_TYPE_DSNOOP , SND_PCM_TYPE_DSHARE , SND_PCM_TYPE_IEC958 , SND_PCM_TYPE_SOFTVOL , SND_PCM_TYPE_IOPLUG , SND_PCM_TYPE_EXTPLUG , SND_PCM_TYPE_MMAP_EMUL , SND_PCM_TYPE_LAST = SND_PCM_TYPE_MMAP_EMUL }
enum | snd_pcm_chmap_type { SND_CHMAP_TYPE_NONE = 0 , SND_CHMAP_TYPE_FIXED , SND_CHMAP_TYPE_VAR , SND_CHMAP_TYPE_PAIRED , SND_CHMAP_TYPE_LAST = SND_CHMAP_TYPE_PAIRED }
enum | snd_pcm_chmap_position { SND_CHMAP_UNKNOWN = 0 , SND_CHMAP_NA , SND_CHMAP_MONO , SND_CHMAP_FL , SND_CHMAP_FR , SND_CHMAP_RL , SND_CHMAP_RR , SND_CHMAP_FC , SND_CHMAP_LFE , SND_CHMAP_SL , SND_CHMAP_SR , SND_CHMAP_RC , SND_CHMAP_FLC , SND_CHMAP_FRC , SND_CHMAP_RLC , SND_CHMAP_RRC , SND_CHMAP_FLW , SND_CHMAP_FRW , SND_CHMAP_FLH , SND_CHMAP_FCH , SND_CHMAP_FRH , SND_CHMAP_TC , SND_CHMAP_TFL , SND_CHMAP_TFR , SND_CHMAP_TFC , SND_CHMAP_TRL , SND_CHMAP_TRR , SND_CHMAP_TRC , SND_CHMAP_TFLC , SND_CHMAP_TFRC , SND_CHMAP_TSL , SND_CHMAP_TSR , SND_CHMAP_LLFE , SND_CHMAP_RLFE , SND_CHMAP_BC , SND_CHMAP_BLC , SND_CHMAP_BRC , SND_CHMAP_LAST = SND_CHMAP_BRC }

## Functions
int | snd_pcm_open (snd_pcm_t **pcm, const char *name, snd_pcm_stream_t stream, int mode)
| Opens a PCM.
int | snd_pcm_open_lconf (snd_pcm_t **pcm, const char *name, snd_pcm_stream_t stream, int mode, snd_config_t *lconf)
| Opens a PCM using local configuration.
int | snd_pcm_open_fallback (snd_pcm_t **pcm, snd_config_t *root, const char *name, const char *orig_name, snd_pcm_stream_t stream, int mode)
| Opens a fallback PCM.
int | snd_pcm_close (snd_pcm_t *pcm)
| close PCM handle
const char * | snd_pcm_name (snd_pcm_t *pcm)
| get identifier of PCM handle
snd_pcm_type_t | snd_pcm_type (snd_pcm_t *pcm)
| get type of PCM handle
snd_pcm_stream_t | snd_pcm_stream (snd_pcm_t *pcm)
| get stream for a PCM handle
int | snd_pcm_poll_descriptors_count (snd_pcm_t *pcm)
| get count of poll descriptors for PCM handle
int | snd_pcm_poll_descriptors (snd_pcm_t *pcm, struct pollfd *pfds, unsigned int space)
| get poll descriptors
int | snd_pcm_poll_descriptors_revents (snd_pcm_t *pcm, struct pollfd *pfds, unsigned int nfds, unsigned short *revents)
| get returned events from poll descriptors
int | snd_pcm_nonblock (snd_pcm_t *pcm, int nonblock)
| set nonblock mode
int | snd_async_add_pcm_handler (snd_async_handler_t **handler, snd_pcm_t *pcm, snd_async_callback_t callback, void *private_data)
| Add an async handler for a PCM.
snd_pcm_t * | snd_async_handler_get_pcm (snd_async_handler_t *handler)
| Return PCM handle related to an async handler.
int | snd_pcm_info (snd_pcm_t *pcm, snd_pcm_info_t *info)
| Obtain general (static) information for PCM handle.
int | snd_pcm_hw_params_current (snd_pcm_t *pcm, snd_pcm_hw_params_t *params)
| Retreive current PCM hardware configuration chosen with snd_pcm_hw_params.
int | snd_pcm_hw_params (snd_pcm_t *pcm, snd_pcm_hw_params_t *params)
| Install one PCM hardware configuration chosen from a configuration space and snd_pcm_prepare it.
int | snd_pcm_hw_free (snd_pcm_t *pcm)
| Remove PCM hardware configuration and free associated resources.
int | snd_pcm_sw_params_current (snd_pcm_t *pcm, snd_pcm_sw_params_t *params)
| Return current software configuration for a PCM.
int | snd_pcm_sw_params (snd_pcm_t *pcm, snd_pcm_sw_params_t *params)
| Install PCM software configuration defined by params.
int | snd_pcm_prepare (snd_pcm_t *pcm)
| Prepare PCM for use.
int | snd_pcm_reset (snd_pcm_t *pcm)
| Reset PCM position.
int | snd_pcm_status (snd_pcm_t *pcm, snd_pcm_status_t *status)
| Obtain status (runtime) information for PCM handle.
int | snd_pcm_start (snd_pcm_t *pcm)
| Start a PCM.
int | snd_pcm_drop (snd_pcm_t *pcm)
| Stop a PCM dropping pending frames.
int | snd_pcm_drain (snd_pcm_t *pcm)
| Stop a PCM preserving pending frames.
int | snd_pcm_pause (snd_pcm_t *pcm, int enable)
| Pause/resume PCM.
snd_pcm_state_t | snd_pcm_state (snd_pcm_t *pcm)
| Return PCM state.
int | snd_pcm_hwsync (snd_pcm_t *pcm)
| (DEPRECATED) Synchronize stream position with hardware
int | snd_pcm_delay (snd_pcm_t *pcm, snd_pcm_sframes_t *delayp)
| Obtain delay for a running PCM handle.
int | snd_pcm_resume (snd_pcm_t *pcm)
| Resume from suspend, no samples are lost.
int | snd_pcm_htimestamp (snd_pcm_t *pcm, snd_pcm_uframes_t *avail, snd_htimestamp_t *tstamp)
| Obtain last position update hi-res timestamp.
snd_pcm_sframes_t | snd_pcm_avail (snd_pcm_t *pcm)
| Return number of frames ready to be read (capture) / written (playback)
snd_pcm_sframes_t | snd_pcm_avail_update (snd_pcm_t *pcm)
| Return number of frames ready to be read (capture) / written (playback)
int | snd_pcm_avail_delay (snd_pcm_t *pcm, snd_pcm_sframes_t *availp, snd_pcm_sframes_t *delayp)
| Combine snd_pcm_avail and snd_pcm_delay functions.
snd_pcm_sframes_t | snd_pcm_rewindable (snd_pcm_t *pcm)
| Get safe count of frames which can be rewinded.
snd_pcm_sframes_t | snd_pcm_rewind (snd_pcm_t *pcm, snd_pcm_uframes_t frames)
| Move application frame position backward.
snd_pcm_sframes_t | snd_pcm_forwardable (snd_pcm_t *pcm)
| Get safe count of frames which can be forwarded.
snd_pcm_sframes_t | snd_pcm_forward (snd_pcm_t *pcm, snd_pcm_uframes_t frames)
| Move application frame position forward.
snd_pcm_sframes_t | snd_pcm_writei (snd_pcm_t *pcm, const void *buffer, snd_pcm_uframes_t size)
| Write interleaved frames to a PCM.
snd_pcm_sframes_t | snd_pcm_readi (snd_pcm_t *pcm, void *buffer, snd_pcm_uframes_t size)
| Read interleaved frames from a PCM.
snd_pcm_sframes_t | snd_pcm_writen (snd_pcm_t *pcm, void **bufs, snd_pcm_uframes_t size)
| Write non interleaved frames to a PCM.
snd_pcm_sframes_t | snd_pcm_readn (snd_pcm_t *pcm, void **bufs, snd_pcm_uframes_t size)
| Read non interleaved frames to a PCM.
int | snd_pcm_wait (snd_pcm_t *pcm, int timeout)
| Wait for a PCM to become ready.
int | snd_pcm_link (snd_pcm_t *pcm1, snd_pcm_t *pcm2)
| Link two PCMs.
int | snd_pcm_unlink (snd_pcm_t *pcm)
| Remove a PCM from a linked group.
snd_pcm_chmap_query_t ** | snd_pcm_query_chmaps (snd_pcm_t *pcm)
snd_pcm_chmap_query_t ** | snd_pcm_query_chmaps_from_hw (int card, int dev, int subdev, snd_pcm_stream_t stream)
void | snd_pcm_free_chmaps (snd_pcm_chmap_query_t **maps)
snd_pcm_chmap_t * | snd_pcm_get_chmap (snd_pcm_t *pcm)
int | snd_pcm_set_chmap (snd_pcm_t *pcm, const snd_pcm_chmap_t *map)
const char * | snd_pcm_chmap_type_name (enum snd_pcm_chmap_type val)
const char * | snd_pcm_chmap_name (enum snd_pcm_chmap_position val)
const char * | snd_pcm_chmap_long_name (enum snd_pcm_chmap_position val)
int | snd_pcm_chmap_print (const snd_pcm_chmap_t *map, size_t maxlen, char *buf)
unsigned int | snd_pcm_chmap_from_string (const char *str)
snd_pcm_chmap_t * | snd_pcm_chmap_parse_string (const char *str)
int | snd_pcm_recover (snd_pcm_t *pcm, int err, int silent)
| Recover the stream state from an error or suspend.
int | snd_pcm_set_params (snd_pcm_t *pcm, snd_pcm_format_t format, snd_pcm_access_t access, unsigned int channels, unsigned int rate, int soft_resample, unsigned int latency)
| Set the hardware and software parameters in a simple way.
int | snd_pcm_get_params (snd_pcm_t *pcm, snd_pcm_uframes_t *buffer_size, snd_pcm_uframes_t *period_size)
| Get the transfer size parameters in a simple way.

## Detailed Description

See the PCM (digital audio) interface page for more details.

## Macro Definition Documentation

## ◆ SND_CHMAP_API_VERSION

#define SND_CHMAP_API_VERSION ((1 << 16) | (0 << 8) | 1)

channel mapping API version number

## ◆ SND_CHMAP_DRIVER_SPEC

#define SND_CHMAP_DRIVER_SPEC (0x02 << 16)

bit flag indicating the non-standard channel value

## ◆ SND_CHMAP_PHASE_INVERSE

#define SND_CHMAP_PHASE_INVERSE (0x01 << 16)

bit flag indicating the channel is phase inverted

## ◆ SND_CHMAP_POSITION_MASK

#define SND_CHMAP_POSITION_MASK 0xffff

bitmask for channel position

## ◆ SND_PCM_ABORT

#define SND_PCM_ABORT 0x00008000

In an abort state (internal, not allowed for open)

## ◆ SND_PCM_ASYNC

#define SND_PCM_ASYNC

Async notification (flag for open mode)

## ◆ SND_PCM_DLSYM_VERSION

#define SND_PCM_DLSYM_VERSION _dlsym_pcm_001

dlsym version for interface entry callback

## ◆ SND_PCM_EINTR

#define SND_PCM_EINTR 0x00000080

Return EINTR instead blocking (wait operation)

## ◆ SND_PCM_NO_AUTO_CHANNELS

#define SND_PCM_NO_AUTO_CHANNELS 0x00020000

Disable automatic (but not forced!) channel conversion

## ◆ SND_PCM_NO_AUTO_FORMAT

#define SND_PCM_NO_AUTO_FORMAT 0x00040000

Disable automatic (but not forced!) format conversion

## ◆ SND_PCM_NO_AUTO_RESAMPLE

#define SND_PCM_NO_AUTO_RESAMPLE 0x00010000

Disable automatic (but not forced!) rate resamplinig

## ◆ SND_PCM_NO_SOFTVOL

#define SND_PCM_NO_SOFTVOL 0x00080000

Disable soft volume control

## ◆ SND_PCM_NONBLOCK

#define SND_PCM_NONBLOCK

Non blocking mode (flag for open mode)

Examples
  /test/latency.c.

## ◆ SND_PCM_WAIT_DRAIN

#define SND_PCM_WAIT_DRAIN (-10002)

Wait for drain in snd_pcm_wait()

## ◆ SND_PCM_WAIT_INFINITE

#define SND_PCM_WAIT_INFINITE (-1)

Infinite wait for snd_pcm_wait()

## ◆ SND_PCM_WAIT_IO

#define SND_PCM_WAIT_IO (-10001)

Wait for next i/o in snd_pcm_wait()

## Typedef Documentation

## ◆ snd_pcm_access_mask_t

typedef struct _snd_pcm_access_mask snd_pcm_access_mask_t

PCM access types mask

## ◆ snd_pcm_format_mask_t

typedef struct _snd_pcm_format_mask snd_pcm_format_mask_t

PCM formats mask

## ◆ snd_pcm_hw_params_t

typedef struct _snd_pcm_hw_params snd_pcm_hw_params_t

PCM hardware configuration space container

snd_pcm_hw_params_t is an opaque structure which contains a set of possible PCM hardware configurations. For example, a given instance might include a range of buffer sizes, a range of period sizes, and a set of several sample formats. Some subset of all possible combinations these sets may be valid, but not necessarily any combination will be valid.

When a parameter is set or restricted using a snd_pcm_hw_params_set* function, all of the other ranges will be updated to exclude as many impossible configurations as possible. Attempting to set a parameter outside of its acceptable range will result in the function failing and an error code being returned.

## ◆ snd_pcm_info_t

typedef struct _snd_pcm_info snd_pcm_info_t

PCM generic info container

## ◆ snd_pcm_scope_t

typedef struct _snd_pcm_scope snd_pcm_scope_t

SND_PCM_TYPE_METER scope handle

## ◆ snd_pcm_sframes_t

typedef long snd_pcm_sframes_t

Signed frames quantity

## ◆ snd_pcm_status_t

typedef struct _snd_pcm_status snd_pcm_status_t

PCM status container

## ◆ snd_pcm_subformat_mask_t

typedef struct _snd_pcm_subformat_mask snd_pcm_subformat_mask_t

PCM subformats mask

## ◆ snd_pcm_sw_params_t

typedef struct _snd_pcm_sw_params snd_pcm_sw_params_t

PCM software configuration container

## ◆ snd_pcm_t

typedef struct _snd_pcm snd_pcm_t

PCM handle

## ◆ snd_pcm_type_t

typedef enum _snd_pcm_type snd_pcm_type_t

PCM type

## ◆ snd_pcm_uframes_t

typedef unsigned long snd_pcm_uframes_t

Unsigned frames quantity

## Enumeration Type Documentation

## ◆ _snd_pcm_type

enum _snd_pcm_type

PCM type

Enumerator
SND_PCM_TYPE_HW | Kernel level PCM
SND_PCM_TYPE_HOOKS | Hooked PCM
SND_PCM_TYPE_MULTI | One or more linked PCM with exclusive access to selected channels
SND_PCM_TYPE_FILE | File writing plugin
SND_PCM_TYPE_NULL | Null endpoint PCM
SND_PCM_TYPE_SHM | Shared memory client PCM
SND_PCM_TYPE_INET | INET client PCM (not yet implemented)
SND_PCM_TYPE_COPY | Copying plugin
SND_PCM_TYPE_LINEAR | Linear format conversion PCM
SND_PCM_TYPE_ALAW | A-Law format conversion PCM
SND_PCM_TYPE_MULAW | Mu-Law format conversion PCM
SND_PCM_TYPE_ADPCM | IMA-ADPCM format conversion PCM
SND_PCM_TYPE_RATE | Rate conversion PCM
SND_PCM_TYPE_ROUTE | Attenuated static route PCM
SND_PCM_TYPE_PLUG | Format adjusted PCM
SND_PCM_TYPE_SHARE | Sharing PCM
SND_PCM_TYPE_METER | Meter plugin
SND_PCM_TYPE_MIX | Mixing PCM
SND_PCM_TYPE_DROUTE | Attenuated dynamic route PCM (not yet implemented)
SND_PCM_TYPE_LBSERVER | Loopback server plugin (not yet implemented)
SND_PCM_TYPE_LINEAR_FLOAT | Linear Integer <-> Linear Float format conversion PCM
SND_PCM_TYPE_LADSPA | LADSPA integration plugin
SND_PCM_TYPE_DMIX | Direct Mixing plugin
SND_PCM_TYPE_JACK | Jack Audio Connection Kit plugin
SND_PCM_TYPE_DSNOOP | Direct Snooping plugin
SND_PCM_TYPE_DSHARE | Direct Sharing plugin
SND_PCM_TYPE_IEC958 | IEC958 subframe plugin
SND_PCM_TYPE_SOFTVOL | Soft volume plugin
SND_PCM_TYPE_IOPLUG | External I/O plugin
SND_PCM_TYPE_EXTPLUG | External filter plugin
SND_PCM_TYPE_MMAP_EMUL | Mmap-emulation plugin

## ◆ snd_pcm_access_t

enum snd_pcm_access_t

PCM access type

Enumerator
SND_PCM_ACCESS_MMAP_INTERLEAVED | mmap access with simple interleaved channels
SND_PCM_ACCESS_MMAP_NONINTERLEAVED | mmap access with simple non interleaved channels
SND_PCM_ACCESS_MMAP_COMPLEX | mmap access with complex placement
SND_PCM_ACCESS_RW_INTERLEAVED | snd_pcm_readi/snd_pcm_writei access
SND_PCM_ACCESS_RW_NONINTERLEAVED | snd_pcm_readn/snd_pcm_writen access

## ◆ snd_pcm_audio_tstamp_type_t

enum snd_pcm_audio_tstamp_type_t

PCM audio timestamp type

Enumerator
SND_PCM_AUDIO_TSTAMP_TYPE_COMPAT | first definition for backwards compatibility only, maps to wallclock/link time for HDAudio playback and DEFAULT/DMA time for everything else
SND_PCM_AUDIO_TSTAMP_TYPE_DEFAULT | DMA time, reported as per hw_ptr
SND_PCM_AUDIO_TSTAMP_TYPE_LINK | link time reported by sample or wallclock counter, reset on startup
SND_PCM_AUDIO_TSTAMP_TYPE_LINK_ABSOLUTE | link time reported by sample or wallclock counter, not reset on startup
SND_PCM_AUDIO_TSTAMP_TYPE_LINK_ESTIMATED | link time estimated indirectly
SND_PCM_AUDIO_TSTAMP_TYPE_LINK_SYNCHRONIZED | link time synchronized with system time

## ◆ snd_pcm_chmap_position

enum snd_pcm_chmap_position

channel positions

Enumerator
SND_CHMAP_UNKNOWN | unspecified
SND_CHMAP_NA | N/A, silent
SND_CHMAP_MONO | mono stream
SND_CHMAP_FL | front left
SND_CHMAP_FR | front right
SND_CHMAP_RL | rear left
SND_CHMAP_RR | rear right
SND_CHMAP_FC | front center
SND_CHMAP_LFE | LFE
SND_CHMAP_SL | side left
SND_CHMAP_SR | side right
SND_CHMAP_RC | rear center
SND_CHMAP_FLC | front left center
SND_CHMAP_FRC | front right center
SND_CHMAP_RLC | rear left center
SND_CHMAP_RRC | rear right center
SND_CHMAP_FLW | front left wide
SND_CHMAP_FRW | front right wide
SND_CHMAP_FLH | front left high
SND_CHMAP_FCH | front center high
SND_CHMAP_FRH | front right high
SND_CHMAP_TC | top center
SND_CHMAP_TFL | top front left
SND_CHMAP_TFR | top front right
SND_CHMAP_TFC | top front center
SND_CHMAP_TRL | top rear left
SND_CHMAP_TRR | top rear right
SND_CHMAP_TRC | top rear center
SND_CHMAP_TFLC | top front left center
SND_CHMAP_TFRC | top front right center
SND_CHMAP_TSL | top side left
SND_CHMAP_TSR | top side right
SND_CHMAP_LLFE | left LFE
SND_CHMAP_RLFE | right LFE
SND_CHMAP_BC | bottom center
SND_CHMAP_BLC | bottom left center
SND_CHMAP_BRC | bottom right center

## ◆ snd_pcm_chmap_type

enum snd_pcm_chmap_type

channel map list type

Enumerator
SND_CHMAP_TYPE_NONE | unspecified channel position
SND_CHMAP_TYPE_FIXED | fixed channel position
SND_CHMAP_TYPE_VAR | freely swappable channel position
SND_CHMAP_TYPE_PAIRED | pair-wise swappable channel position
SND_CHMAP_TYPE_LAST | last entry

## ◆ snd_pcm_class_t

enum snd_pcm_class_t

PCM class

Enumerator
SND_PCM_CLASS_GENERIC | standard device
SND_PCM_CLASS_MULTI | multichannel device
SND_PCM_CLASS_MODEM | software modem device
SND_PCM_CLASS_DIGITIZER | digitizer device

## ◆ snd_pcm_format_t

enum snd_pcm_format_t

PCM sample format

Enumerator
SND_PCM_FORMAT_UNKNOWN | Unknown
SND_PCM_FORMAT_S8 | Signed 8 bit
SND_PCM_FORMAT_U8 | Unsigned 8 bit
SND_PCM_FORMAT_S16_LE | Signed 16 bit Little Endian
SND_PCM_FORMAT_S16_BE | Signed 16 bit Big Endian
SND_PCM_FORMAT_U16_LE | Unsigned 16 bit Little Endian
SND_PCM_FORMAT_U16_BE | Unsigned 16 bit Big Endian
SND_PCM_FORMAT_S24_LE | Signed 24 bit Little Endian using low three bytes in 32-bit word
SND_PCM_FORMAT_S24_BE | Signed 24 bit Big Endian using low three bytes in 32-bit word
SND_PCM_FORMAT_U24_LE | Unsigned 24 bit Little Endian using low three bytes in 32-bit word
SND_PCM_FORMAT_U24_BE | Unsigned 24 bit Big Endian using low three bytes in 32-bit word
SND_PCM_FORMAT_S32_LE | Signed 32 bit Little Endian
SND_PCM_FORMAT_S32_BE | Signed 32 bit Big Endian
SND_PCM_FORMAT_U32_LE | Unsigned 32 bit Little Endian
SND_PCM_FORMAT_U32_BE | Unsigned 32 bit Big Endian
SND_PCM_FORMAT_FLOAT_LE | Float 32 bit Little Endian, Range -1.0 to 1.0
SND_PCM_FORMAT_FLOAT_BE | Float 32 bit Big Endian, Range -1.0 to 1.0
SND_PCM_FORMAT_FLOAT64_LE | Float 64 bit Little Endian, Range -1.0 to 1.0
SND_PCM_FORMAT_FLOAT64_BE | Float 64 bit Big Endian, Range -1.0 to 1.0
SND_PCM_FORMAT_IEC958_SUBFRAME_LE | IEC-958 Little Endian
SND_PCM_FORMAT_IEC958_SUBFRAME_BE | IEC-958 Big Endian
SND_PCM_FORMAT_MU_LAW | Mu-Law
SND_PCM_FORMAT_A_LAW | A-Law
SND_PCM_FORMAT_IMA_ADPCM | Ima-ADPCM
SND_PCM_FORMAT_MPEG | MPEG
SND_PCM_FORMAT_GSM | GSM
SND_PCM_FORMAT_S20_LE | Signed 20bit Little Endian in 4bytes format, LSB justified
SND_PCM_FORMAT_S20_BE | Signed 20bit Big Endian in 4bytes format, LSB justified
SND_PCM_FORMAT_U20_LE | Unsigned 20bit Little Endian in 4bytes format, LSB justified
SND_PCM_FORMAT_U20_BE | Unsigned 20bit Big Endian in 4bytes format, LSB justified
SND_PCM_FORMAT_SPECIAL | Special
SND_PCM_FORMAT_S24_3LE | Signed 24bit Little Endian in 3bytes format
SND_PCM_FORMAT_S24_3BE | Signed 24bit Big Endian in 3bytes format
SND_PCM_FORMAT_U24_3LE | Unsigned 24bit Little Endian in 3bytes format
SND_PCM_FORMAT_U24_3BE | Unsigned 24bit Big Endian in 3bytes format
SND_PCM_FORMAT_S20_3LE | Signed 20bit Little Endian in 3bytes format
SND_PCM_FORMAT_S20_3BE | Signed 20bit Big Endian in 3bytes format
SND_PCM_FORMAT_U20_3LE | Unsigned 20bit Little Endian in 3bytes format
SND_PCM_FORMAT_U20_3BE | Unsigned 20bit Big Endian in 3bytes format
SND_PCM_FORMAT_S18_3LE | Signed 18bit Little Endian in 3bytes format
SND_PCM_FORMAT_S18_3BE | Signed 18bit Big Endian in 3bytes format
SND_PCM_FORMAT_U18_3LE | Unsigned 18bit Little Endian in 3bytes format
SND_PCM_FORMAT_U18_3BE | Unsigned 18bit Big Endian in 3bytes format
SND_PCM_FORMAT_S16 | Signed 16 bit CPU endian
SND_PCM_FORMAT_U16 | Unsigned 16 bit CPU endian
SND_PCM_FORMAT_S24 | Signed 24 bit CPU endian
SND_PCM_FORMAT_U24 | Unsigned 24 bit CPU endian
SND_PCM_FORMAT_S32 | Signed 32 bit CPU endian
SND_PCM_FORMAT_U32 | Unsigned 32 bit CPU endian
SND_PCM_FORMAT_FLOAT | Float 32 bit CPU endian
SND_PCM_FORMAT_FLOAT64 | Float 64 bit CPU endian
SND_PCM_FORMAT_IEC958_SUBFRAME | IEC-958 CPU Endian
SND_PCM_FORMAT_S20 | Signed 20bit in 4bytes format, LSB justified, CPU Endian
SND_PCM_FORMAT_U20 | Unsigned 20bit in 4bytes format, LSB justified, CPU Endian

## ◆ snd_pcm_start_t

enum snd_pcm_start_t

PCM start mode

Enumerator
SND_PCM_START_DATA | Automatic start on data read/write
SND_PCM_START_EXPLICIT | Explicit start

## ◆ snd_pcm_state_t

enum snd_pcm_state_t

PCM state

Enumerator
SND_PCM_STATE_OPEN | Open
SND_PCM_STATE_SETUP | Setup installed
SND_PCM_STATE_PREPARED | Ready to start
SND_PCM_STATE_RUNNING | Running
SND_PCM_STATE_XRUN | Stopped: underrun (playback) or overrun (capture) detected
SND_PCM_STATE_DRAINING | Draining: running (playback) or stopped (capture)
SND_PCM_STATE_PAUSED | Paused
SND_PCM_STATE_SUSPENDED | Hardware is suspended
SND_PCM_STATE_DISCONNECTED | Hardware is disconnected
SND_PCM_STATE_PRIVATE1 | Private - used internally in the library - do not use

## ◆ snd_pcm_stream_t

enum snd_pcm_stream_t

PCM stream (direction)

Enumerator
SND_PCM_STREAM_PLAYBACK | Playback stream
SND_PCM_STREAM_CAPTURE | Capture stream

## ◆ snd_pcm_subclass_t

enum snd_pcm_subclass_t

PCM subclass

Enumerator
SND_PCM_SUBCLASS_GENERIC_MIX | subdevices are mixed together
SND_PCM_SUBCLASS_MULTI_MIX | multichannel subdevices are mixed together

## ◆ snd_pcm_subformat_t

enum snd_pcm_subformat_t

PCM sample subformat

Enumerator
SND_PCM_SUBFORMAT_UNKNOWN | Unknown
SND_PCM_SUBFORMAT_STD | Standard
SND_PCM_SUBFORMAT_MSBITS_MAX | Maximum bits based on PCM format
SND_PCM_SUBFORMAT_MSBITS_20 | 20 most significant bits
SND_PCM_SUBFORMAT_MSBITS_24 | 24 most significant bits

## ◆ snd_pcm_tstamp_t

enum snd_pcm_tstamp_t

PCM timestamp mode

Enumerator
SND_PCM_TSTAMP_NONE | No timestamp
SND_PCM_TSTAMP_ENABLE | Update timestamp at every hardware position update
SND_PCM_TSTAMP_MMAP | Equivalent with SND_PCM_TSTAMP_ENABLE, just for compatibility with older versions

## ◆ snd_pcm_tstamp_type_t

enum snd_pcm_tstamp_type_t

PCM timestamp type

Enumerator
SND_PCM_TSTAMP_TYPE_GETTIMEOFDAY | gettimeofday equivalent
SND_PCM_TSTAMP_TYPE_MONOTONIC | posix_clock_monotonic equivalent
SND_PCM_TSTAMP_TYPE_MONOTONIC_RAW | monotonic_raw (no NTP)

## ◆ snd_pcm_xrun_t

enum snd_pcm_xrun_t

PCM xrun mode

Enumerator
SND_PCM_XRUN_NONE | Xrun detection disabled
SND_PCM_XRUN_STOP | Stop on xrun detection

## Function Documentation

## ◆ snd_async_add_pcm_handler()

int snd_async_add_pcm_handler | ( | snd_async_handler_t ** | handler,
|  | snd_pcm_t * | pcm,
|  | snd_async_callback_t | callback,
|  | void * | private_data )

Add an async handler for a PCM.

Parameters

  handler | Returned handler handle
  pcm | PCM handle
  callback | Callback function
  private_data | Callback private data

Returns
  0 otherwise a negative error code on failure

The asynchronous callback is called when period boundary elapses.

Examples
  /test/pcm.c.

## ◆ snd_async_handler_get_pcm()

snd_pcm_t * snd_async_handler_get_pcm | ( | snd_async_handler_t * | handler | ) |

Return PCM handle related to an async handler.

Parameters

  handler | Async handler handle

Returns
  PCM handle

Examples
  /test/pcm.c.

## ◆ snd_pcm_avail()

snd_pcm_sframes_t snd_pcm_avail | ( | snd_pcm_t * | pcm | ) |

Return number of frames ready to be read (capture) / written (playback)

Parameters

  pcm | PCM handle

Returns
  a positive number of frames ready otherwise a negative error code

On capture does all the actions needed to transport to application level all the ready frames across underlying layers.

The position is synced with hardware (driver) position in the sound ring buffer in this functions.

The function is thread-safe when built with the proper option.

Examples
  /test/latency.c.

## ◆ snd_pcm_avail_delay()

int snd_pcm_avail_delay | ( | snd_pcm_t * | pcm,
|  | snd_pcm_sframes_t * | availp,
|  | snd_pcm_sframes_t * | delayp )

Combine snd_pcm_avail and snd_pcm_delay functions.

Parameters

  pcm | PCM handle
  availp | Number of available frames in the ring buffer
  delayp | Total I/O latency in frames

Returns
  zero on success otherwise a negative error code

The avail and delay values retuned are in sync.

The function is thread-safe when built with the proper option.

## ◆ snd_pcm_avail_update()

snd_pcm_sframes_t snd_pcm_avail_update | ( | snd_pcm_t * | pcm | ) |

Return number of frames ready to be read (capture) / written (playback)

Parameters

  pcm | PCM handle

Returns
  a positive number of frames ready otherwise a negative error code

On capture does all the actions needed to transport to application level all the ready frames across underlying layers.

The position is not synced with hardware (driver) position in the sound ring buffer in this function. This function is a light version of snd_pcm_avail() .

Using this function is ideal after poll() or select() when audio file descriptor made the event and when application expects just period timing.

Also this function might be called after snd_pcm_delay() or snd_pcm_hwsync() functions to move private ring buffer pointers in alsa-lib (the internal plugin chain).

The function is thread-safe when built with the proper option.

Examples
  /test/pcm.c.

## ◆ snd_pcm_chmap_from_string()

unsigned int snd_pcm_chmap_from_string | ( | const char * | str | ) |

!brief Convert from string to channel position

Parameters

  str | The string to parse

Returns
  The channel position value or -1 as an error

## ◆ snd_pcm_chmap_long_name()

const char * snd_pcm_chmap_long_name | ( | enum snd_pcm_chmap_position | val | ) |

!brief Get a longer name string for a standard channel map position

Parameters

  val | Channel position

Returns
  The string corresponding to the given position, or NULL

## ◆ snd_pcm_chmap_name()

const char * snd_pcm_chmap_name | ( | enum snd_pcm_chmap_position | val | ) |

!brief Get a name string for a standard channel map position

Parameters

  val | Channel position

Returns
  The string corresponding to the given position, or NULL

## ◆ snd_pcm_chmap_parse_string()

snd_pcm_chmap_t * snd_pcm_chmap_parse_string | ( | const char * | str | ) |

!brief Convert from string to channel map

Parameters

  str | The string to parse

Returns
  The channel map

Note: the caller is requested to release the returned value via free()

## ◆ snd_pcm_chmap_print()

int snd_pcm_chmap_print | ( | const snd_pcm_chmap_t * | map,
|  | size_t | maxlen,
|  | char * | buf )

!brief Print the channels in chmap on the buffer

Parameters

  map | The channel map to print
  maxlen | The maximal length to write (including NUL letter)
  buf | The buffer to write

Returns
  The actual string length or a negative error code

## ◆ snd_pcm_chmap_type_name()

const char * snd_pcm_chmap_type_name | ( | enum snd_pcm_chmap_type | val | ) |

!brief Get a name string for a channel map type as query results

Parameters

  val | Channel position

Returns
  The string corresponding to the given type, or NULL

## ◆ snd_pcm_close()

int snd_pcm_close | ( | snd_pcm_t * | pcm | ) |

close PCM handle

Parameters

  pcm | PCM handle

Returns
  0 on success otherwise a negative error code

Closes the specified PCM handle and frees all associated resources.

Examples
  /test/latency.c, /test/pcm.c, and /test/pcm_min.c.

## ◆ snd_pcm_delay()

int snd_pcm_delay | ( | snd_pcm_t * | pcm,
|  | snd_pcm_sframes_t * | delayp )

Obtain delay for a running PCM handle.

Parameters

  pcm | PCM handle
  delayp | Returned delay in frames

Returns
  0 on success otherwise a negative error code

For playback the delay is defined as the time that a frame that is written to the PCM stream shortly after this call will take to be actually audible. It is as such the overall latency from the write call to the final DAC.

For capture the delay is defined as the time that a frame that was digitized by the audio device takes until it can be read from the PCM stream shortly after this call returns. It is as such the overall latency from the initial ADC to the read call.

Please note that hence in case of a playback underrun this value will not necessarily got down to 0.

If the application is interested in the fill level of the playback buffer of the device, it should use snd_pcm_avail*() functions. The value returned by that call is not directly related to the delay, since the latter might include some additional, fixed latencies the former does not.

Note this function does not update the actual r/w pointer for applications. The function snd_pcm_avail_update() have to be called before any begin+commit operation.

The function is thread-safe when built with the proper option.

## ◆ snd_pcm_drain()

int snd_pcm_drain | ( | snd_pcm_t * | pcm | ) |

Stop a PCM preserving pending frames.

Parameters

  pcm | PCM handle

Returns
  0 on success otherwise a negative error code

Return values

  -ESTRPIPE | a suspend event occurred

For playback wait for all pending frames to be played and then stop the PCM. For capture stop PCM permitting to retrieve residual frames.

For stopping the PCM stream immediately, use ::snd_pcm_drop() instead.

The function is thread-safe when built with the proper option.

Examples
  /test/latency.c, and /test/pcm_min.c.

## ◆ snd_pcm_drop()

int snd_pcm_drop | ( | snd_pcm_t * | pcm | ) |

Stop a PCM dropping pending frames.

Parameters

  pcm | PCM handle

Returns
  0 on success otherwise a negative error code

This function stops the PCM immediately. The pending samples on the buffer are ignored.

For processing all pending samples, use ::snd_pcm_drain() instead.

The function is thread-safe when built with the proper option.

Examples
  /test/latency.c.

## ◆ snd_pcm_forward()

snd_pcm_sframes_t snd_pcm_forward | ( | snd_pcm_t * | pcm,
|  | snd_pcm_uframes_t | frames )

Move application frame position forward.

Parameters

  pcm | PCM handle
  frames | wanted skip in frames

Returns
  a positive number for actual skip otherwise a negative error code

Return values

  0 | means no action

The function is thread-safe when built with the proper option.

## ◆ snd_pcm_forwardable()

snd_pcm_sframes_t snd_pcm_forwardable | ( | snd_pcm_t * | pcm | ) |

Get safe count of frames which can be forwarded.

Parameters

  pcm | PCM handle

Returns
  a positive number of frames or negative error code

Note: The snd_pcm_forward() can accept bigger value than returned by this function. But it is not guaranteed that output stream will be consistent with bigger value.

The function is thread-safe when built with the proper option.

## ◆ snd_pcm_free_chmaps()

void snd_pcm_free_chmaps | ( | snd_pcm_chmap_query_t ** | maps | ) |

!brief Release the channel map array allocated via snd_pcm_query_chmaps

Parameters

  maps | the array pointer to release

## ◆ snd_pcm_get_chmap()

snd_pcm_chmap_t * snd_pcm_get_chmap | ( | snd_pcm_t * | pcm | ) |

!brief Get the current channel map

Parameters

  pcm | PCM instance

Returns
  the current channel map, or NULL if error

Note: the caller is requested to release the returned value via free()

## ◆ snd_pcm_get_params()

int snd_pcm_get_params | ( | snd_pcm_t * | pcm,
|  | snd_pcm_uframes_t * | buffer_size,
|  | snd_pcm_uframes_t * | period_size )

Get the transfer size parameters in a simple way.

Parameters

  pcm | PCM handle
  buffer_size | PCM ring buffer size in frames
  period_size | PCM period size in frames

Returns
  0 on success otherwise a negative error code

## ◆ snd_pcm_htimestamp()

int snd_pcm_htimestamp | ( | snd_pcm_t * | pcm,
|  | snd_pcm_uframes_t * | avail,
|  | snd_htimestamp_t * | tstamp )

Obtain last position update hi-res timestamp.

Parameters

  pcm | PCM handle
  avail | Number of available frames when timestamp was grabbed
  tstamp | Hi-res timestamp

Returns
  0 on success otherwise a negative error code

Note this function does not update the actual r/w pointer for applications.

The function is thread-safe when built with the proper option.

## ◆ snd_pcm_hw_free()

int snd_pcm_hw_free | ( | snd_pcm_t * | pcm | ) |

Remove PCM hardware configuration and free associated resources.

Parameters

  pcm | PCM handle

Returns
  0 on success otherwise a negative error code

The function will also report success if no configuration is set.

Examples
  /test/latency.c.

## ◆ snd_pcm_hw_params()

int snd_pcm_hw_params | ( | snd_pcm_t * | pcm,
|  | snd_pcm_hw_params_t * | params )

Install one PCM hardware configuration chosen from a configuration space and snd_pcm_prepare it.

Parameters

  pcm | PCM handle
  params | Configuration space definition container

Returns
  0 on success otherwise a negative error code

The configuration is chosen fixing single parameters in this order: first access, first format, first subformat, min channels, min rate, min period time, max buffer size, min tick time. If no mutually compatible set of parameters can be chosen, a negative error code will be returned.

After this call, snd_pcm_prepare() is called automatically and the stream is brought to `SND_PCM_STATE_PREPARED` state.

The hardware parameters cannot be changed when the stream is running (active). The software parameters can be changed at any time.

The configuration space will be updated to reflect the chosen parameters.

Examples
  /test/latency.c, and /test/pcm.c.

## ◆ snd_pcm_hw_params_current()

int snd_pcm_hw_params_current | ( | snd_pcm_t * | pcm,
|  | snd_pcm_hw_params_t * | params )

Retreive current PCM hardware configuration chosen with snd_pcm_hw_params.

Parameters

  pcm | PCM handle
  params | Configuration space definition container

Returns
  0 on success otherwise a negative error code

Return values

  -EBADFD | no hardware configuration is set

## ◆ snd_pcm_hwsync()

int snd_pcm_hwsync | ( | snd_pcm_t * | pcm | ) |

(DEPRECATED) Synchronize stream position with hardware

Parameters

  pcm | PCM handle

Returns
  0 on success otherwise a negative error code

Note this function does not update the actual r/w pointer for applications. The function snd_pcm_avail_update() have to be called before any mmap begin+commit operation.

The function is thread-safe when built with the proper option.

This function is deprecated. Use snd_pcm_avail_update() instead.

## ◆ snd_pcm_info()

int snd_pcm_info | ( | snd_pcm_t * | pcm,
|  | snd_pcm_info_t * | info )

Obtain general (static) information for PCM handle.

Parameters

  pcm | PCM handle
  info | Information container

Returns
  0 on success otherwise a negative error code

## ◆ snd_pcm_link()

int snd_pcm_link | ( | snd_pcm_t * | pcm1,
|  | snd_pcm_t * | pcm2 )

Link two PCMs.

Parameters

  pcm1 | first PCM handle
  pcm2 | first PCM handle

Returns
  0 on success otherwise a negative error code

The two PCMs will start/stop/prepare in sync.

Examples
  /test/latency.c.

## ◆ snd_pcm_name()

const char * snd_pcm_name | ( | snd_pcm_t * | pcm | ) |

get identifier of PCM handle

Parameters

  pcm | PCM handle

Returns
  ascii identifier of PCM handle

Returns the ASCII identifier of given PCM handle. It's the same identifier specified in snd_pcm_open().

## ◆ snd_pcm_nonblock()

int snd_pcm_nonblock | ( | snd_pcm_t * | pcm,
|  | int | nonblock )

set nonblock mode

Parameters

  pcm | PCM handle
  nonblock | 0 = block, 1 = nonblock mode, 2 = abort

Returns
  0 on success otherwise a negative error code

The function is thread-safe when built with the proper option.

Examples
  /test/latency.c.

## ◆ snd_pcm_open()

int snd_pcm_open | ( | snd_pcm_t ** | pcmp,
|  | const char * | name,
|  | snd_pcm_stream_t | stream,
|  | int | mode )

Opens a PCM.

Parameters

  pcmp | Returned PCM handle
  name | ASCII identifier of the PCM handle
  stream | Wanted stream
  mode | Open mode (see SND_PCM_NONBLOCK, SND_PCM_ASYNC)

Returns
  0 on success otherwise a negative error code

Examples
  /test/latency.c, /test/pcm.c, and /test/pcm_min.c.

## ◆ snd_pcm_open_fallback()

int snd_pcm_open_fallback | ( | snd_pcm_t ** | pcmp,
|  | snd_config_t * | root,
|  | const char * | name,
|  | const char * | orig_name,
|  | snd_pcm_stream_t | stream,
|  | int | mode )

Opens a fallback PCM.

Parameters

  pcmp | Returned PCM handle
  root | Configuration root
  name | ASCII identifier of the PCM handle
  orig_name | The original ASCII name
  stream | Wanted stream
  mode | Open mode (see SND_PCM_NONBLOCK, SND_PCM_ASYNC)

Returns
  0 on success otherwise a negative error code

## ◆ snd_pcm_open_lconf()

int snd_pcm_open_lconf | ( | snd_pcm_t ** | pcmp,
|  | const char * | name,
|  | snd_pcm_stream_t | stream,
|  | int | mode,
|  | snd_config_t * | lconf )

Opens a PCM using local configuration.

Parameters

  pcmp | Returned PCM handle
  name | ASCII identifier of the PCM handle
  stream | Wanted stream
  mode | Open mode (see SND_PCM_NONBLOCK, SND_PCM_ASYNC)
  lconf | Local configuration

Returns
  0 on success otherwise a negative error code

## ◆ snd_pcm_pause()

int snd_pcm_pause | ( | snd_pcm_t * | pcm,
|  | int | enable )

Pause/resume PCM.

Parameters

  pcm | PCM handle
  enable | 0 = resume, 1 = pause

Returns
  0 on success otherwise a negative error code

Note that this function works only on the hardware which supports pause feature. You can check it via ::snd_pcm_hw_params_can_pause() function.

The function is thread-safe when built with the proper option.

## ◆ snd_pcm_poll_descriptors()

int snd_pcm_poll_descriptors | ( | snd_pcm_t * | pcm,
|  | struct pollfd * | pfds,
|  | unsigned int | space )

get poll descriptors

Parameters

  pcm | PCM handle
  pfds | array of poll descriptors
  space | space in the poll descriptor array

Returns
  count of filled descriptors

This function fills the given poll descriptor structs for the specified PCM handle. The poll desctiptor array should have the size returned by ::snd_pcm_poll_descriptors_count() function.

The result is intended for direct use with the poll() syscall.

For reading the returned events of poll descriptor after poll() system call, use ::snd_pcm_poll_descriptors_revents() function. The field values in pollfd structs may be bogus regarding the stream direction from the application perspective (POLLIN might not imply read direction and POLLOUT might not imply write), but the ::snd_pcm_poll_descriptors_revents() function does the right "demangling".

You can use output from this function as arguments for the select() syscall, too. Do not forget to translate POLLIN and POLLOUT events to corresponding FD_SET arrays and demangle events using ::snd_pcm_poll_descriptors_revents() .

It is guaranteed that for the given PCM handle, the output poll descriptor structs (and their count) will not change after hardware and software parameters setup. Thus it is valid to call the function once when all parameters are set and reuse its output for the lifetime of the stream parameters.

The function is thread-safe when built with the proper option.

Examples
  /test/pcm.c.

## ◆ snd_pcm_poll_descriptors_count()

int snd_pcm_poll_descriptors_count | ( | snd_pcm_t * | pcm | ) |

get count of poll descriptors for PCM handle

Parameters

  pcm | PCM handle

Returns
  count of poll descriptors

The function is thread-safe when built with the proper option.

Examples
  /test/pcm.c.

## ◆ snd_pcm_poll_descriptors_revents()

int snd_pcm_poll_descriptors_revents | ( | snd_pcm_t * | pcm,
|  | struct pollfd * | pfds,
|  | unsigned int | nfds,
|  | unsigned short * | revents )

get returned events from poll descriptors

Parameters

  pcm | PCM handle
  pfds | array of poll descriptors
  nfds | count of poll descriptors
  revents | pointer to the returned (single) event

Returns
  zero if success, otherwise a negative error code

This function does "demangling" of the revents mask returned from the poll() syscall to correct semantics (POLLIN = read, POLLOUT = write).

Note: The null event also exists. Even if poll() or select() syscall returned that some events are waiting, this function might return empty set of events. In this case, application should do next event waiting using poll() or select().

Note: Even if multiple poll descriptors are used (i.e. pfds > 1), this function returns only a single event.

The passed in count of poll descriptors must be equal to ::snd_pcm_poll_descriptors_count() and the passed in array must match the array returned by ::snd_pcm_poll_descriptors() (in its full length and original order) with the revent fields updated according to the poll() result. This function will not modify the file descriptor or event field of any element of the given poll descriptor array.

The function is thread-safe when built with the proper option.

Examples
  /test/pcm.c.

## ◆ snd_pcm_prepare()

int snd_pcm_prepare | ( | snd_pcm_t * | pcm | ) |

Prepare PCM for use.

Parameters

  pcm | PCM handle

Returns
  0 on success otherwise a negative error code

The function is thread-safe when built with the proper option.

Examples
  /test/latency.c, and /test/pcm.c.

## ◆ snd_pcm_query_chmaps()

snd_pcm_chmap_query_t ** snd_pcm_query_chmaps | ( | snd_pcm_t * | pcm | ) |

!brief Query the available channel maps

Parameters

  pcm | PCM handle to query

Returns
  the NULL-terminated array of integer pointers, each of which contains the channel map. A channel map is represented by an integer array, beginning with the channel map type, followed by the number of channels, and the position of each channel. Return NULL in case of an error.

Note: the caller is requested to release the returned value via snd_pcm_free_chmaps().

## ◆ snd_pcm_query_chmaps_from_hw()

snd_pcm_chmap_query_t ** snd_pcm_query_chmaps_from_hw | ( | int | card,
|  | int | dev,
|  | int | subdev,
|  | snd_pcm_stream_t | stream )

!brief Query the available channel maps

Parameters

  card | the card number
  dev | the PCM device number
  subdev | the PCM substream index
  stream | the direction of PCM stream

Returns
  the NULL-terminated array of integer pointers, or NULL at error.

This function works like snd_pcm_query_chmaps() but it takes the card, device, substream and stream numbers instead of the already opened snd_pcm_t instance, so that you can query available channel maps of a PCM before actually opening it.

As the parameters stand, the query is performed only to the hw PCM devices, not the abstracted PCM object in alsa-lib.

## ◆ snd_pcm_readi()

snd_pcm_sframes_t snd_pcm_readi | ( | snd_pcm_t * | pcm,
|  | void * | buffer,
|  | snd_pcm_uframes_t | size )

Read interleaved frames from a PCM.

Parameters

  pcm | PCM handle
  buffer | frames containing buffer
  size | frames to be read

Returns
  a positive number of frames actually read otherwise a negative error code

Return values

  -EBADFD | PCM is not in the right state (SND_PCM_STATE_PREPARED or SND_PCM_STATE_RUNNING)
  -EPIPE | an overrun occurred
  -ESTRPIPE | a suspend event occurred (stream is suspended and waiting for an application recovery)

If the blocking behaviour was selected and it is running, then routine waits until all requested frames are filled. The returned number of frames can be less only if a signal or underrun occurred.

If the non-blocking behaviour is selected, then routine doesn't wait at all.

The function is thread-safe when built with the proper option.

Examples
  /test/latency.c.

## ◆ snd_pcm_readn()

snd_pcm_sframes_t snd_pcm_readn | ( | snd_pcm_t * | pcm,
|  | void ** | bufs,
|  | snd_pcm_uframes_t | size )

Read non interleaved frames to a PCM.

Parameters

  pcm | PCM handle
  bufs | frames containing buffers (one for each channel)
  size | frames to be read

Returns
  a positive number of frames actually read otherwise a negative error code

Return values

  -EBADFD | PCM is not in the right state (SND_PCM_STATE_PREPARED or SND_PCM_STATE_RUNNING)
  -EPIPE | an overrun occurred
  -ESTRPIPE | a suspend event occurred (stream is suspended and waiting for an application recovery)

If the blocking behaviour was selected and it is running, then routine waits until all requested frames are filled. The returned number of frames can be less only if a signal or underrun occurred.

If the non-blocking behaviour is selected, then routine doesn't wait at all.

The function is thread-safe when built with the proper option.

## ◆ snd_pcm_recover()

int snd_pcm_recover | ( | snd_pcm_t * | pcm,
|  | int | err,
|  | int | silent )

Recover the stream state from an error or suspend.

Parameters

  pcm | PCM handle
  err | error number
  silent | do not print error reason

Returns
  0 when error code was handled successfuly, otherwise a negative error code

This a high-level helper function building on other functions.

This functions handles -EINTR (interrupted system call), -EPIPE (overrun or underrun) and -ESTRPIPE (stream is suspended) error codes trying to prepare given stream for next I/O.

Note that this function returs the original error code when it is not handled inside this function (for example -EAGAIN is returned back).

Examples
  /test/pcm_min.c.

## ◆ snd_pcm_reset()

int snd_pcm_reset | ( | snd_pcm_t * | pcm | ) |

Reset PCM position.

Parameters

  pcm | PCM handle

Returns
  0 on success otherwise a negative error code

Reduce PCM delay to 0.

The function is thread-safe when built with the proper option.

## ◆ snd_pcm_resume()

int snd_pcm_resume | ( | snd_pcm_t * | pcm | ) |

Resume from suspend, no samples are lost.

Parameters

  pcm | PCM handle

Returns
  0 on success otherwise a negative error code

Return values

  -EAGAIN | resume can't be proceed immediately (audio hardware is probably still suspended)
  -ENOSYS | hardware doesn't support this feature

This function can be used when the stream is in the suspend state to do the fine resume from this state. Not all hardware supports this feature, when an -ENOSYS error is returned, use the ::snd_pcm_prepare() function to recovery.

The function is thread-safe when built with the proper option.

Examples
  /test/pcm.c.

## ◆ snd_pcm_rewind()

snd_pcm_sframes_t snd_pcm_rewind | ( | snd_pcm_t * | pcm,
|  | snd_pcm_uframes_t | frames )

Move application frame position backward.

Parameters

  pcm | PCM handle
  frames | wanted displacement in frames

Returns
  a positive number for actual displacement otherwise a negative error code

The function is thread-safe when built with the proper option.

## ◆ snd_pcm_rewindable()

snd_pcm_sframes_t snd_pcm_rewindable | ( | snd_pcm_t * | pcm | ) |

Get safe count of frames which can be rewinded.

Parameters

  pcm | PCM handle

Returns
  a positive number of frames or negative error code

Note: The snd_pcm_rewind() can accept bigger value than returned by this function. But it is not guaranteed that output stream will be consistent with bigger value.

The function is thread-safe when built with the proper option.

## ◆ snd_pcm_set_chmap()

int snd_pcm_set_chmap | ( | snd_pcm_t * | pcm,
|  | const snd_pcm_chmap_t * | map )

!brief Configure the current channel map

Parameters

  pcm | PCM instance
  map | the channel map to write

Returns
  zero if succeeded, or a negative error code

## ◆ snd_pcm_set_params()

int snd_pcm_set_params | ( | snd_pcm_t * | pcm,
|  | snd_pcm_format_t | format,
|  | snd_pcm_access_t | access,
|  | unsigned int | channels,
|  | unsigned int | rate,
|  | int | soft_resample,
|  | unsigned int | latency )

Set the hardware and software parameters in a simple way.

Parameters

  pcm | PCM handle
  format | required PCM format
  access | required PCM access
  channels | required PCM channels
  rate | required sample rate in Hz
  soft_resample | 0 = disallow alsa-lib resample stream, 1 = allow resampling
  latency | required overall latency in us

Returns
  0 on success otherwise a negative error code

Examples
  /test/pcm_min.c.

## ◆ snd_pcm_start()

int snd_pcm_start | ( | snd_pcm_t * | pcm | ) |

Start a PCM.

Parameters

  pcm | PCM handle

Returns
  0 on success otherwise a negative error code

The function is thread-safe when built with the proper option.

Examples
  /test/latency.c, and /test/pcm.c.

## ◆ snd_pcm_state()

snd_pcm_state_t snd_pcm_state | ( | snd_pcm_t * | pcm | ) |

Return PCM state.

Parameters

  pcm | PCM handle

Returns
  PCM state snd_pcm_state_t of given PCM handle

This is a faster way to obtain only the PCM state without calling ::snd_pcm_status().

Note that this function always returns one of the snd_pcm_state_t enum variants. It will never return a negative error code.

The function is thread-safe when built with the proper option.

Examples
  /test/pcm.c.

## ◆ snd_pcm_status()

int snd_pcm_status | ( | snd_pcm_t * | pcm,
|  | snd_pcm_status_t * | status )

Obtain status (runtime) information for PCM handle.

Parameters

  pcm | PCM handle
  status | Status container

Returns
  0 on success otherwise a negative error code

The function is thread-safe when built with the proper option.

Examples
  /test/latency.c.

## ◆ snd_pcm_stream()

snd_pcm_stream_t snd_pcm_stream | ( | snd_pcm_t * | pcm | ) |

get stream for a PCM handle

Parameters

  pcm | PCM handle

Returns
  stream of PCM handle

Returns the type snd_pcm_stream_t of given PCM handle.

## ◆ snd_pcm_sw_params()

int snd_pcm_sw_params | ( | snd_pcm_t * | pcm,
|  | snd_pcm_sw_params_t * | params )

Install PCM software configuration defined by params.

Parameters

  pcm | PCM handle
  params | Configuration container

Returns
  0 on success otherwise a negative error code

The software parameters can be changed at any time. The hardware parameters cannot be changed when the stream is running (active).

The function is thread-safe when built with the proper option.

Examples
  /test/latency.c, and /test/pcm.c.

## ◆ snd_pcm_sw_params_current()

int snd_pcm_sw_params_current | ( | snd_pcm_t * | pcm,
|  | snd_pcm_sw_params_t * | params )

Return current software configuration for a PCM.

Parameters

  pcm | PCM handle
  params | Software configuration container

Returns
  0 on success otherwise a negative error code

The function is thread-safe when built with the proper option.

Examples
  /test/latency.c, and /test/pcm.c.

## ◆ snd_pcm_type()

snd_pcm_type_t snd_pcm_type | ( | snd_pcm_t * | pcm | ) |

get type of PCM handle

Parameters

  pcm | PCM handle

Returns
  type of PCM handle

Returns the type snd_pcm_type_t of given PCM handle.

## ◆ snd_pcm_unlink()

int snd_pcm_unlink | ( | snd_pcm_t * | pcm | ) |

Remove a PCM from a linked group.

Parameters

  pcm | PCM handle

Returns
  0 on success otherwise a negative error code

Examples
  /test/latency.c.

## ◆ snd_pcm_wait()

int snd_pcm_wait | ( | snd_pcm_t * | pcm,
|  | int | timeout )

Wait for a PCM to become ready.

Parameters

  pcm | PCM handle
  timeout | maximum time in milliseconds to wait, a -1 value means infinity (SND_PCM_WAIT_INFINITE), see also SND_PCM_WAIT_IO and SND_PCM_WAIT_DRAIN

Returns
  a positive value on success otherwise a negative error code (-EPIPE for the xrun and -ESTRPIPE for the suspended status, others for general errors)

Return values

  0 | timeout occurred
  1 | PCM stream is ready for I/O

The function is thread-safe when built with the proper option.

Examples
  /test/latency.c, and /test/pcm.c.

## ◆ snd_pcm_writei()

snd_pcm_sframes_t snd_pcm_writei | ( | snd_pcm_t * | pcm,
|  | const void * | buffer,
|  | snd_pcm_uframes_t | size )

Write interleaved frames to a PCM.

Parameters

  pcm | PCM handle
  buffer | frames containing buffer
  size | frames to be written

Returns
  a positive number of frames actually written otherwise a negative error code

Return values

  -EBADFD | PCM is not in the right state (SND_PCM_STATE_PREPARED or SND_PCM_STATE_RUNNING)
  -EPIPE | an underrun occurred
  -ESTRPIPE | a suspend event occurred (stream is suspended and waiting for an application recovery)

If the blocking behaviour is selected and it is running, then routine waits until all requested frames are played or put to the playback ring buffer. The returned number of frames can be less only if a signal or underrun occurred.

If the non-blocking behaviour is selected, then routine doesn't wait at all.

The function is thread-safe when built with the proper option.

Examples
  /test/latency.c, /test/pcm.c, and /test/pcm_min.c.

## ◆ snd_pcm_writen()

snd_pcm_sframes_t snd_pcm_writen | ( | snd_pcm_t * | pcm,
|  | void ** | bufs,
|  | snd_pcm_uframes_t | size )

Write non interleaved frames to a PCM.

Parameters

  pcm | PCM handle
  bufs | frames containing buffers (one for each channel)
  size | frames to be written

Returns
  a positive number of frames actually written otherwise a negative error code

Return values

  -EBADFD | PCM is not in the right state (SND_PCM_STATE_PREPARED or SND_PCM_STATE_RUNNING)
  -EPIPE | an underrun occurred
  -ESTRPIPE | a suspend event occurred (stream is suspended and waiting for an application recovery)

If the blocking behaviour is selected and it is running, then routine waits until all requested frames are played or put to the playback ring buffer. The returned number of frames can be less only if a signal or underrun occurred.

If the non-blocking behaviour is selected, then routine doesn't wait at all.

The function is thread-safe when built with the proper option.