PCM Interface

Overview

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

Access Mask Functions

Debug Functions

Deprecated Functions

Description Functions

Direct Access (MMAP) Functions

Format Mask Functions

Hardware Parameters

Helper Functions

Hook Extension

Scope Plugin Extension

Simple setup functions

Software Parameters

Status Functions

Stream Information

Subformat Mask Functions

// 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;

// enums

enum _snd_pcm_type;
enum snd_pcm_access_t;
enum snd_pcm_chmap_position;
enum snd_pcm_chmap_type;
enum snd_pcm_class_t;
enum snd_pcm_format_t;
enum snd_pcm_start_t;
enum snd_pcm_state_t;
enum snd_pcm_stream_t;
enum snd_pcm_subclass_t;
enum snd_pcm_subformat_t;
enum snd_pcm_tstamp_t;
enum snd_pcm_tstamp_type_t;
enum snd_pcm_xrun_t;

// structs

struct snd_pcm_audio_tstamp_config_t;
struct snd_pcm_audio_tstamp_report_t;
struct snd_pcm_channel_area_t;
struct snd_pcm_chmap_query_t;
struct snd_pcm_chmap_t;

// unions

union snd_pcm_sync_id_t;

// global functions

int
snd_pcm_open(
    snd_pcm_t** pcm,
    const char* name,
    snd_pcm_stream_t stream,
    int mode
);

int
snd_pcm_open_lconf(
    snd_pcm_t** pcm,
    const char* name,
    snd_pcm_stream_t stream,
    int mode,
    snd_config_t* lconf
);

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

int
snd_pcm_close(snd_pcm_t* pcm);

const char*
snd_pcm_name(snd_pcm_t* pcm);

snd_pcm_type_t
snd_pcm_type(snd_pcm_t* pcm);

snd_pcm_stream_t
snd_pcm_stream(snd_pcm_t* pcm);

int
snd_pcm_poll_descriptors_count(snd_pcm_t* pcm);

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

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

int
snd_pcm_nonblock(
    snd_pcm_t* pcm,
    int nonblock
);

static
__inline__ int
snd_pcm_abort(snd_pcm_t* pcm);

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

snd_pcm_t*
snd_async_handler_get_pcm(snd_async_handler_t* handler);

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

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

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

int
snd_pcm_hw_free(snd_pcm_t* pcm);

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

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

int
snd_pcm_prepare(snd_pcm_t* pcm);

int
snd_pcm_reset(snd_pcm_t* pcm);

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

int
snd_pcm_start(snd_pcm_t* pcm);

int
snd_pcm_drop(snd_pcm_t* pcm);

int
snd_pcm_drain(snd_pcm_t* pcm);

int
snd_pcm_pause(
    snd_pcm_t* pcm,
    int enable
);

snd_pcm_state_t
snd_pcm_state(snd_pcm_t* pcm);

int
snd_pcm_hwsync(snd_pcm_t* pcm);

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

int
snd_pcm_resume(snd_pcm_t* pcm);

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

snd_pcm_sframes_t
snd_pcm_avail(snd_pcm_t* pcm);

snd_pcm_sframes_t
snd_pcm_avail_update(snd_pcm_t* pcm);

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

snd_pcm_sframes_t
snd_pcm_rewindable(snd_pcm_t* pcm);

snd_pcm_sframes_t
snd_pcm_rewind(
    snd_pcm_t* pcm,
    snd_pcm_uframes_t frames
);

snd_pcm_sframes_t
snd_pcm_forwardable(snd_pcm_t* pcm);

snd_pcm_sframes_t
snd_pcm_forward(
    snd_pcm_t* pcm,
    snd_pcm_uframes_t frames
);

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

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

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

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

int
snd_pcm_wait(
    snd_pcm_t* pcm,
    int timeout
);

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

int
snd_pcm_unlink(snd_pcm_t* pcm);

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

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

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

// macros

#define SND_CHMAP_API_VERSION
#define SND_CHMAP_DRIVER_SPEC
#define SND_CHMAP_PHASE_INVERSE
#define SND_CHMAP_POSITION_MASK
#define SND_PCM_ABORT
#define SND_PCM_ASYNC
#define SND_PCM_DLSYM_VERSION
#define SND_PCM_NONBLOCK
#define SND_PCM_NO_AUTO_CHANNELS
#define SND_PCM_NO_AUTO_FORMAT
#define SND_PCM_NO_AUTO_RESAMPLE
#define SND_PCM_NO_SOFTVOL

Detailed Documentation

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

Typedefs

typedef struct _snd_pcm_info snd_pcm_info_t

PCM generic info container

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_sw_params snd_pcm_sw_params_t

PCM software configuration container

typedef struct _snd_pcm_status snd_pcm_status_t

PCM status container

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_subformat_mask snd_pcm_subformat_mask_t

PCM subformats mask

typedef unsigned long snd_pcm_uframes_t

Unsigned frames quantity

typedef long snd_pcm_sframes_t

Signed frames quantity

typedef struct _snd_pcm snd_pcm_t

PCM handle

typedef enum _snd_pcm_type snd_pcm_type_t

PCM type

typedef struct _snd_pcm_scope snd_pcm_scope_t

SND_PCM_TYPE_METER scope handle

Global Functions

int
snd_pcm_open(
    snd_pcm_t** pcm,
    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

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.

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

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

int
snd_pcm_close(snd_pcm_t* pcm)

close PCM handle

Closes the specified PCM handle and frees all associated resources.

Parameters:

pcm	PCM handle

Returns:

0 on success otherwise a negative error code

const char*
snd_pcm_name(snd_pcm_t* pcm)

get identifier of PCM handle

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

Parameters:

pcm	PCM handle

Returns:

ascii identifier of PCM handle

snd_pcm_type_t
snd_pcm_type(snd_pcm_t* pcm)

get type of PCM handle

Returns the type snd_pcm_type_t of given PCM handle.

Parameters:

pcm	PCM handle

Returns:

type of PCM handle

snd_pcm_stream_t
snd_pcm_stream(snd_pcm_t* pcm)

get stream for a PCM handle

Returns the type snd_pcm_stream_t of given PCM handle.

Parameters:

pcm	PCM handle

Returns:

stream of PCM handle

int
snd_pcm_poll_descriptors_count(snd_pcm_t* pcm)

get count of poll descriptors for PCM handle

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

Parameters:

pcm	PCM handle

Returns:

count of poll descriptors

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

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

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

Parameters:

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

Returns:

count of filled 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

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 function is thread-safe when built with the proper option.

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

int
snd_pcm_nonblock(
    snd_pcm_t* pcm,
    int nonblock
)

set nonblock mode

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

Parameters:

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

Returns:

0 on success otherwise a negative error code

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.

The asynchronous callback is called when period boundary elapses.

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

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

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

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.

Parameters:

pcm	PCM handle
params	Configuration space definition container

Returns:

0 on success otherwise a negative error code

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

int
snd_pcm_sw_params_current(
    snd_pcm_t* pcm,
    snd_pcm_sw_params_t* params
)

Return current software configuration for a PCM.

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

Parameters:

pcm	PCM handle
params	Software configuration container

Returns:

0 on success otherwise a negative error code

int
snd_pcm_sw_params(
    snd_pcm_t* pcm,
    snd_pcm_sw_params_t* params
)

Install PCM software configuration defined by params.

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.

Parameters:

pcm	PCM handle
params	Configuration container

Returns:

0 on success otherwise a negative error code

int
snd_pcm_prepare(snd_pcm_t* pcm)

Prepare PCM for use.

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

Parameters:

pcm	PCM handle

Returns:

0 on success otherwise a negative error code

int
snd_pcm_reset(snd_pcm_t* pcm)

Reset PCM position.

Reduce PCM delay to 0.

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

Parameters:

pcm	PCM handle

Returns:

0 on success otherwise a negative error code

int
snd_pcm_status(
    snd_pcm_t* pcm,
    snd_pcm_status_t* status
)

Obtain status (runtime) information for PCM handle.

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

Parameters:

pcm	PCM handle
status	Status container

Returns:

0 on success otherwise a negative error code

int
snd_pcm_start(snd_pcm_t* pcm)

Start a PCM.

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

Parameters:

pcm	PCM handle

Returns:

0 on success otherwise a negative error code

int
snd_pcm_drop(snd_pcm_t* pcm)

Stop a PCM dropping pending frames.

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.

Parameters:

pcm	PCM handle

Returns:

0 on success otherwise a negative error code

int
snd_pcm_drain(snd_pcm_t* pcm)

Stop a PCM preserving pending frames.

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.

Parameters:

pcm	PCM handle
-ESTRPIPE	a suspend event occurred

Returns:

0 on success otherwise a negative error code

int
snd_pcm_pause(
    snd_pcm_t* pcm,
    int enable
)

Pause/resume PCM.

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.

Parameters:

pcm	PCM handle
enable	0 = resume, 1 = pause

Returns:

0 on success otherwise a negative error code

snd_pcm_state_t
snd_pcm_state(snd_pcm_t* pcm)

Return PCM state.

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

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

Parameters:

pcm	PCM handle

Returns:

PCM state snd_pcm_state_t of given PCM handle

int
snd_pcm_hwsync(snd_pcm_t* pcm)

(DEPRECATED) Synchronize stream position with hardware

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.

Parameters:

pcm	PCM handle

Returns:

0 on success otherwise a negative error code

int
snd_pcm_delay(
    snd_pcm_t* pcm,
    snd_pcm_sframes_t* delayp
)

Obtain delay for a running PCM handle.

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.

Parameters:

pcm	PCM handle
delayp	Returned delay in frames

Returns:

0 on success otherwise a negative error code

int
snd_pcm_resume(snd_pcm_t* pcm)

Resume from suspend, no samples are lost.

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.

Parameters:

pcm	PCM handle
-EAGAIN	resume can’t be proceed immediately (audio hardware is probably still suspended)
-ENOSYS	hardware doesn’t support this feature

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.

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

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

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

snd_pcm_sframes_t
snd_pcm_avail(snd_pcm_t* pcm)

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

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.

Parameters:

pcm	PCM handle

Returns:

a positive number of frames ready otherwise a negative error code

snd_pcm_sframes_t
snd_pcm_avail_update(snd_pcm_t* pcm)

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

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.

Parameters:

pcm	PCM handle

Returns:

a positive number of frames ready otherwise a negative error code

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.

The avail and delay values retuned are in sync.

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

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

snd_pcm_sframes_t
snd_pcm_rewindable(snd_pcm_t* pcm)

Get safe count of frames which can be rewinded.

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.

Parameters:

pcm	PCM handle

Returns:

a positive number of frames or negative error code

snd_pcm_sframes_t
snd_pcm_rewind(
    snd_pcm_t* pcm,
    snd_pcm_uframes_t frames
)

Move application frame position backward.

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

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_forwardable(snd_pcm_t* pcm)

Get safe count of frames which can be forwarded.

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.

Parameters:

pcm	PCM handle

Returns:

a positive number of frames or negative error code

snd_pcm_sframes_t
snd_pcm_forward(
    snd_pcm_t* pcm,
    snd_pcm_uframes_t frames
)

Move application frame position forward.

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

Parameters:

pcm	PCM handle
frames	wanted skip in frames
0	means no action

Returns:

a positive number for actual skip otherwise a negative error code

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.

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.

Parameters:

pcm	PCM handle
buffer	frames containing buffer
size	frames to be written
-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)

Returns:

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

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

Read interleaved frames from a PCM.

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.

Parameters:

pcm	PCM handle
buffer	frames containing buffer
size	frames to be read
-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)

Returns:

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

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.

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.

Parameters:

pcm	PCM handle
bufs	frames containing buffers (one for each channel)
size	frames to be written
-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)

Returns:

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

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.

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.

Parameters:

pcm	PCM handle
bufs	frames containing buffers (one for each channel)
size	frames to be read
-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)

Returns:

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

int
snd_pcm_wait(
    snd_pcm_t* pcm,
    int timeout
)

Wait for a PCM to become ready.

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

Parameters:

pcm	PCM handle
timeout	maximum time in milliseconds to wait, a negative value means infinity
0	timeout occurred
1	PCM stream is ready for I/O

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)

int
snd_pcm_link(
    snd_pcm_t* pcm1,
    snd_pcm_t* pcm2
)

Link two PCMs.

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

Parameters:

pcm1	first PCM handle
pcm2	first PCM handle

Returns:

0 on success otherwise a negative error code

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

snd_pcm_chmap_query_t**
snd_pcm_query_chmaps(snd_pcm_t* pcm)

!brief Query the available channel maps Note: the caller is requested to release the returned value via snd_pcm_free_chmaps().

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.

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

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.

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_chmap_t*
snd_pcm_get_chmap(snd_pcm_t* pcm)

!brief Get the current channel map Note: the caller is requested to release the returned value via free()

Parameters:

pcm	PCM instance

Returns:

the current channel map, or NULL if error

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

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

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

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

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

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_t*
snd_pcm_chmap_parse_string(const char* str)

!brief Convert from string to channel map Note: the caller is requested to release the returned value via free()

Parameters:

str	The string to parse

Returns:

The channel map

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

Recover the stream state from an error or suspend.

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

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

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

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

Macros

#define SND_CHMAP_API_VERSION

channel mapping API version number

#define SND_CHMAP_DRIVER_SPEC

bit flag indicating the non-standard channel value

#define SND_CHMAP_PHASE_INVERSE

bit flag indicating the channel is phase inverted

#define SND_CHMAP_POSITION_MASK

bitmask for channel position

#define SND_PCM_ABORT

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 version for interface entry callback

#define SND_PCM_NONBLOCK

Non blocking mode (flag for open mode)

#define SND_PCM_NO_AUTO_CHANNELS

Disable automatic (but not forced!) channel conversion

#define SND_PCM_NO_AUTO_FORMAT

Disable automatic (but not forced!) format conversion

#define SND_PCM_NO_AUTO_RESAMPLE

Disable automatic (but not forced!) rate resamplinig

#define SND_PCM_NO_SOFTVOL

Disable soft volume control