ALSA project - the C library reference
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Modules | Files | Data Structures | Macros | Typedefs | Enumerations | Functions
PCM Interface

Modules

 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_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_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_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_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_LAST = SND_PCM_FORMAT_DSD_U16_LE, 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
}
enum  snd_pcm_subformat_t { SND_PCM_SUBFORMAT_STD = 0, SND_PCM_SUBFORMAT_LAST = SND_PCM_SUBFORMAT_STD }
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
}
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_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_tsnd_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_tsnd_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_tsnd_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

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

channel mapping API version number

#define SND_CHMAP_DRIVER_SPEC   (0x02 << 16)

bit flag indicating the non-standard channel value

#define SND_CHMAP_PHASE_INVERSE   (0x01 << 16)

bit flag indicating the channel is phase inverted

#define SND_CHMAP_POSITION_MASK   0xffff

bitmask for channel position

#define SND_PCM_ABORT   0x00008000

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

#define SND_PCM_ASYNC

Async notification (flag for open mode)

#define SND_PCM_DLSYM_VERSION   _dlsym_pcm_001

dlsym version for interface entry callback

#define SND_PCM_NO_AUTO_CHANNELS   0x00020000

Disable automatic (but not forced!) channel conversion

#define SND_PCM_NO_AUTO_FORMAT   0x00040000

Disable automatic (but not forced!) format conversion

#define SND_PCM_NO_AUTO_RESAMPLE   0x00010000

Disable automatic (but not forced!) rate resamplinig

#define SND_PCM_NO_SOFTVOL   0x00080000

Disable soft volume control

#define SND_PCM_NONBLOCK

Non blocking mode (flag for open mode)

Examples:
/test/latency.c.

Typedef Documentation

typedef struct _snd_pcm_access_mask snd_pcm_access_mask_t

PCM access types mask

typedef struct _snd_pcm_format_mask snd_pcm_format_mask_t

PCM formats mask

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.

typedef struct _snd_pcm_info snd_pcm_info_t

PCM generic info container

typedef struct _snd_pcm_scope snd_pcm_scope_t

SND_PCM_TYPE_METER scope handle

typedef long snd_pcm_sframes_t

Signed frames quantity

typedef struct _snd_pcm_status snd_pcm_status_t

PCM status container

typedef struct _snd_pcm_subformat_mask snd_pcm_subformat_mask_t

PCM subformats mask

typedef struct _snd_pcm_sw_params snd_pcm_sw_params_t

PCM software configuration container

typedef struct _snd_pcm snd_pcm_t

PCM handle

PCM type

typedef unsigned long snd_pcm_uframes_t

Unsigned frames quantity


Enumeration Type Documentation

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

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

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

channel map list type

Enumerator:
SND_CHMAP_TYPE_FIXED 

unspecified channel position

SND_CHMAP_TYPE_VAR 

fixed channel position

SND_CHMAP_TYPE_PAIRED 

freely swappable channel position

SND_CHMAP_TYPE_LAST 

pair-wise swappable channel position

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

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

PCM start mode

Enumerator:
SND_PCM_START_DATA 

Automatic start on data read/write

SND_PCM_START_EXPLICIT 

Explicit start

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

PCM stream (direction)

Enumerator:
SND_PCM_STREAM_PLAYBACK 

Playback stream

SND_PCM_STREAM_CAPTURE 

Capture stream

PCM subclass

Enumerator:
SND_PCM_SUBCLASS_GENERIC_MIX 

subdevices are mixed together

SND_PCM_SUBCLASS_MULTI_MIX 

multichannel subdevices are mixed together

PCM sample subformat

Enumerator:
SND_PCM_SUBFORMAT_STD 

Standard

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

PCM xrun mode

Enumerator:
SND_PCM_XRUN_NONE 

Xrun detection disabled

SND_PCM_XRUN_STOP 

Stop on xrun detection


Function Documentation

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:
handlerReturned handler handle
pcmPCM handle
callbackCallback function
private_dataCallback 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_pcm_t* snd_async_handler_get_pcm ( snd_async_handler_t handler)

Return PCM handle related to an async handler.

Parameters:
handlerAsync handler handle
Returns:
PCM handle
Examples:
/test/pcm.c.
snd_pcm_sframes_t snd_pcm_avail ( snd_pcm_t pcm)

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

Parameters:
pcmPCM 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.

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:
pcmPCM handle
availpNumber of available frames in the ring buffer
delaypTotal I/O latency in frames
Returns:
zero on success otherwise a negative error code

The avail and delay values retuned are in sync.

snd_pcm_sframes_t snd_pcm_avail_update ( snd_pcm_t pcm)

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

Parameters:
pcmPCM 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).

Examples:
/test/pcm.c.
unsigned int snd_pcm_chmap_from_string ( const char *  str)

!brief Convert from string to channel position

Parameters:
strThe string to parse
Returns:
The channel position value or -1 as an error
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:
valChannel position
Returns:
The string corresponding to the given position, or NULL
const char* snd_pcm_chmap_name ( enum snd_pcm_chmap_position  val)

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

Parameters:
valChannel position
Returns:
The string corresponding to the given position, or NULL
snd_pcm_chmap_t* snd_pcm_chmap_parse_string ( const char *  str)

!brief Convert from string to channel map

Parameters:
strThe string to parse
Returns:
The channel map

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

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:
mapThe channel map to print
maxlenThe maximal length to write (including NUL letter)
bufThe buffer to write
Returns:
The actual string length or a negative error code
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:
valChannel position
Returns:
The string corresponding to the given type, or NULL
int snd_pcm_close ( snd_pcm_t pcm)

close PCM handle

Parameters:
pcmPCM 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.
int snd_pcm_delay ( snd_pcm_t pcm,
snd_pcm_sframes_t delayp 
)

Obtain delay for a running PCM handle.

Parameters:
pcmPCM handle
delaypReturned 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.

int snd_pcm_drain ( snd_pcm_t pcm)

Stop a PCM preserving pending frames.

Parameters:
pcmPCM handle
Returns:
0 on success otherwise a negative error code
Return values:
-ESTRPIPEa 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.

Examples:
/test/latency.c.
int snd_pcm_drop ( snd_pcm_t pcm)

Stop a PCM dropping pending frames.

Parameters:
pcmPCM 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.

Examples:
/test/latency.c.
snd_pcm_sframes_t snd_pcm_forward ( snd_pcm_t pcm,
snd_pcm_uframes_t  frames 
)

Move application frame position forward.

Parameters:
pcmPCM handle
frameswanted skip in frames
Returns:
a positive number for actual skip otherwise a negative error code
Return values:
0means no action
snd_pcm_sframes_t snd_pcm_forwardable ( snd_pcm_t pcm)

Get safe count of frames which can be forwarded.

Parameters:
pcmPCM 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.

void snd_pcm_free_chmaps ( snd_pcm_chmap_query_t **  maps)

!brief Release the channel map array allocated via snd_pcm_query_chmaps

Parameters:
mapsthe array pointer to release
snd_pcm_chmap_t* snd_pcm_get_chmap ( snd_pcm_t pcm)

!brief Get the current channel map

Parameters:
pcmPCM instance
Returns:
the current channel map, or NULL if error

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

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:
pcmPCM handle
buffer_sizePCM ring buffer size in frames
period_sizePCM period size in frames
Returns:
0 on success otherwise a negative error code
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:
pcmPCM handle
availNumber of available frames when timestamp was grabbed
tstampHi-res timestamp
Returns:
0 on success otherwise a negative error code

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

int snd_pcm_hw_free ( snd_pcm_t pcm)

Remove PCM hardware configuration and free associated resources.

Parameters:
pcmPCM handle
Returns:
0 on success otherwise a negative error code
Examples:
/test/latency.c.
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:
pcmPCM handle
paramsConfiguration 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.
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:
pcmPCM handle
paramsConfiguration space definition container
Returns:
0 on success otherwise a negative error code
int snd_pcm_hwsync ( snd_pcm_t pcm)

(DEPRECATED) Synchronize stream position with hardware

Parameters:
pcmPCM 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.

int snd_pcm_info ( snd_pcm_t pcm,
snd_pcm_info_t info 
)

Obtain general (static) information for PCM handle.

Parameters:
pcmPCM handle
infoInformation container
Returns:
0 on success otherwise a negative error code
int snd_pcm_link ( snd_pcm_t pcm1,
snd_pcm_t pcm2 
)

Link two PCMs.

Parameters:
pcm1first PCM handle
pcm2first PCM handle
Returns:
0 on success otherwise a negative error code

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

Examples:
/test/latency.c.
const char* snd_pcm_name ( snd_pcm_t pcm)

get identifier of PCM handle

Parameters:
pcmPCM 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().

int snd_pcm_nonblock ( snd_pcm_t pcm,
int  nonblock 
)

set nonblock mode

Parameters:
pcmPCM handle
nonblock0 = block, 1 = nonblock mode, 2 = abort
Returns:
0 on success otherwise a negative error code
Examples:
/test/latency.c.
int snd_pcm_open ( snd_pcm_t **  pcmp,
const char *  name,
snd_pcm_stream_t  stream,
int  mode 
)

Opens a PCM.

Parameters:
pcmpReturned PCM handle
nameASCII identifier of the PCM handle
streamWanted stream
modeOpen 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.
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:
pcmpReturned PCM handle
rootConfiguration root
nameASCII identifier of the PCM handle
orig_nameThe original ASCII name
streamWanted stream
modeOpen mode (see SND_PCM_NONBLOCK, SND_PCM_ASYNC)
Returns:
0 on success otherwise a negative error code
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:
pcmpReturned PCM handle
nameASCII identifier of the PCM handle
streamWanted stream
modeOpen mode (see SND_PCM_NONBLOCK, SND_PCM_ASYNC)
lconfLocal configuration
Returns:
0 on success otherwise a negative error code
int snd_pcm_pause ( snd_pcm_t pcm,
int  enable 
)

Pause/resume PCM.

Parameters:
pcmPCM handle
enable0 = 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.

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

get poll descriptors

Parameters:
pcmPCM handle
pfdsarray of poll descriptors
spacespace 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() .

Examples:
/test/pcm.c.
int snd_pcm_poll_descriptors_count ( snd_pcm_t pcm)

get count of poll descriptors for PCM handle

Parameters:
pcmPCM handle
Returns:
count of poll descriptors
Examples:
/test/pcm.c.
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:
pcmPCM handle
pfdsarray of poll descriptors
nfdscount of poll descriptors
reventspointer 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.

Examples:
/test/pcm.c.
int snd_pcm_prepare ( snd_pcm_t pcm)

Prepare PCM for use.

Parameters:
pcmPCM handle
Returns:
0 on success otherwise a negative error code
Examples:
/test/latency.c, and /test/pcm.c.
snd_pcm_chmap_query_t** snd_pcm_query_chmaps ( snd_pcm_t pcm)

!brief Query the available channel maps

Parameters:
pcmPCM 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.

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

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:
cardthe card number
devthe PCM device number
subdevthe PCM substream index
streamthe 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_sframes_t snd_pcm_readi ( snd_pcm_t pcm,
void *  buffer,
snd_pcm_uframes_t  size 
)

Read interleaved frames from a PCM.

Parameters:
pcmPCM handle
bufferframes containing buffer
sizeframes to be read
Returns:
a positive number of frames actually read otherwise a negative error code
Return values:
-EBADFDPCM is not in the right state (SND_PCM_STATE_PREPARED or SND_PCM_STATE_RUNNING)
-EPIPEan overrun occurred
-ESTRPIPEa 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.

Examples:
/test/latency.c.
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:
pcmPCM handle
bufsframes containing buffers (one for each channel)
sizeframes to be read
Returns:
a positive number of frames actually read otherwise a negative error code
Return values:
-EBADFDPCM is not in the right state (SND_PCM_STATE_PREPARED or SND_PCM_STATE_RUNNING)
-EPIPEan overrun occurred
-ESTRPIPEa 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.

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

Recover the stream state from an error or suspend.

Parameters:
pcmPCM handle
errerror number
silentdo 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.
int snd_pcm_reset ( snd_pcm_t pcm)

Reset PCM position.

Parameters:
pcmPCM handle
Returns:
0 on success otherwise a negative error code

Reduce PCM delay to 0.

int snd_pcm_resume ( snd_pcm_t pcm)

Resume from suspend, no samples are lost.

Parameters:
pcmPCM handle
Returns:
0 on success otherwise a negative error code
Return values:
-EAGAINresume can't be proceed immediately (audio hardware is probably still suspended)
-ENOSYShardware 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.

Examples:
/test/pcm.c.
snd_pcm_sframes_t snd_pcm_rewind ( snd_pcm_t pcm,
snd_pcm_uframes_t  frames 
)

Move application frame position backward.

Parameters:
pcmPCM handle
frameswanted displacement in frames
Returns:
a positive number for actual displacement otherwise a negative error code
snd_pcm_sframes_t snd_pcm_rewindable ( snd_pcm_t pcm)

Get safe count of frames which can be rewinded.

Parameters:
pcmPCM 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.

int snd_pcm_set_chmap ( snd_pcm_t pcm,
const snd_pcm_chmap_t map 
)

!brief Configure the current channel map

Parameters:
pcmPCM instance
mapthe channel map to write
Returns:
zero if succeeded, or a negative error code
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:
pcmPCM handle
formatrequired PCM format
accessrequired PCM access
channelsrequired PCM channels
raterequired sample rate in Hz
soft_resample0 = disallow alsa-lib resample stream, 1 = allow resampling
latencyrequired overall latency in us
Returns:
0 on success otherwise a negative error code
Examples:
/test/pcm_min.c.
int snd_pcm_start ( snd_pcm_t pcm)

Start a PCM.

Parameters:
pcmPCM handle
Returns:
0 on success otherwise a negative error code
Examples:
/test/latency.c, and /test/pcm.c.
snd_pcm_state_t snd_pcm_state ( snd_pcm_t pcm)

Return PCM state.

Parameters:
pcmPCM 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().

Examples:
/test/pcm.c.
int snd_pcm_status ( snd_pcm_t pcm,
snd_pcm_status_t status 
)

Obtain status (runtime) information for PCM handle.

Parameters:
pcmPCM handle
statusStatus container
Returns:
0 on success otherwise a negative error code
Examples:
/test/latency.c.
snd_pcm_stream_t snd_pcm_stream ( snd_pcm_t pcm)

get stream for a PCM handle

Parameters:
pcmPCM handle
Returns:
stream of PCM handle

Returns the type snd_pcm_stream_t of given PCM handle.

int snd_pcm_sw_params ( snd_pcm_t pcm,
snd_pcm_sw_params_t params 
)

Install PCM software configuration defined by params.

Parameters:
pcmPCM handle
paramsConfiguration 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).

Examples:
/test/latency.c, and /test/pcm.c.
int snd_pcm_sw_params_current ( snd_pcm_t pcm,
snd_pcm_sw_params_t params 
)

Return current software configuration for a PCM.

Parameters:
pcmPCM handle
paramsSoftware configuration container
Returns:
0 on success otherwise a negative error code
Examples:
/test/latency.c, and /test/pcm.c.
snd_pcm_type_t snd_pcm_type ( snd_pcm_t pcm)

get type of PCM handle

Parameters:
pcmPCM handle
Returns:
type of PCM handle

Returns the type snd_pcm_type_t of given PCM handle.

int snd_pcm_unlink ( snd_pcm_t pcm)

Remove a PCM from a linked group.

Parameters:
pcmPCM handle
Returns:
0 on success otherwise a negative error code
Examples:
/test/latency.c.
int snd_pcm_wait ( snd_pcm_t pcm,
int  timeout 
)

Wait for a PCM to become ready.

Parameters:
pcmPCM handle
timeoutmaximum time in milliseconds to wait, a negative value means infinity
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:
0timeout occurred
1PCM stream is ready for I/O
Examples:
/test/latency.c, and /test/pcm.c.
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:
pcmPCM handle
bufferframes containing buffer
sizeframes to be written
Returns:
a positive number of frames actually written otherwise a negative error code
Return values:
-EBADFDPCM is not in the right state (SND_PCM_STATE_PREPARED or SND_PCM_STATE_RUNNING)
-EPIPEan underrun occurred
-ESTRPIPEa 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.

Examples:
/test/latency.c, /test/pcm.c, and /test/pcm_min.c.
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:
pcmPCM handle
bufsframes containing buffers (one for each channel)
sizeframes to be written
Returns:
a positive number of frames actually written otherwise a negative error code
Return values:
-EBADFDPCM is not in the right state (SND_PCM_STATE_PREPARED or SND_PCM_STATE_RUNNING)
-EPIPEan underrun occurred
-ESTRPIPEa 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.