PCM Interface

Data Structures
struct	snd_pcm_channel_area_t
union	snd_pcm_sync_id_t
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.
Defines
#define	SND_PCM_DLSYM_VERSION   _dlsym_pcm_001
#define	SND_PCM_NONBLOCK
#define	SND_PCM_ASYNC
#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
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_LAST = SND_PCM_FORMAT_U18_3BE,   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 }
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_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.
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.

---

Define Documentation

#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

Examples:

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

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

Examples:

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

typedef struct _snd_pcm_status snd_pcm_status_t

PCM status container

Examples:

/test/latency.c.

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

Examples:

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

typedef struct _snd_pcm snd_pcm_t

PCM handle

Examples:

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

typedef enum _snd_pcm_type snd_pcm_type_t

PCM type

typedef unsigned long snd_pcm_uframes_t

Unsigned frames quantity

Examples:

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

---

Enumeration Type Documentation

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

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

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

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

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

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

enum snd_pcm_stream_t

PCM stream (direction)

Enumerator:

SND_PCM_STREAM_PLAYBACK	Playback stream
SND_PCM_STREAM_CAPTURE	Capture stream

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

enum snd_pcm_subformat_t

PCM sample subformat

Enumerator:

SND_PCM_SUBFORMAT_STD

Standard

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

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

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

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.

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).

Examples:

/test/pcm.c.

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.

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.

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.

Examples:

/test/latency.c.

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.

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:

	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

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.

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

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.

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

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:

	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

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.

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:

	pcm	PCM handle
	params	Configuration 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:

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.

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

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.

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().

int snd_pcm_nonblock	(	snd_pcm_t *	pcm,
		int	nonblock
	)

set nonblock mode

Parameters:

	pcm	PCM handle
	nonblock	0 = block, 1 = nonblock mode

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:

	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.

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

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.

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() .

Examples:

/test/pcm.c.

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

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:

	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.

Examples:

/test/pcm.c.

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

Examples:

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

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.

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:

	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.

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.

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.

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.

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:

	pcm	PCM handle
	frames	wanted 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:

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.

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.

int snd_pcm_start

(

snd_pcm_t *

pcm

)

Start a PCM.

Parameters:

pcm

PCM 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:

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().

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:

	pcm	PCM handle
	status	Status 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:

pcm

PCM 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:

	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).

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:

	pcm	PCM handle
	params	Software 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:

pcm

PCM 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:

pcm

PCM 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:

	pcm	PCM handle
	timeout	maximum 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:

	0	timeout occurred
	1	PCM 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:

	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.

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:

	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.