Files | |
| file | pcm.c |
| PCM Interface. | |
| file | pcm_plugin.c |
| PCM Interface. | |
Data Structures | |
| struct | snd_pcm_audio_tstamp_config_t |
| struct | snd_pcm_audio_tstamp_report_t |
| struct | snd_pcm_channel_area_t |
| union | snd_pcm_sync_id_t |
| struct | snd_pcm_chmap_t |
| struct | snd_pcm_chmap_query_t |
Macros | |
| #define | SND_PCM_DLSYM_VERSION _dlsym_pcm_001 |
| #define | SND_PCM_NONBLOCK |
| #define | SND_PCM_ASYNC |
| #define | SND_PCM_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 |
Functions | |
| int | snd_pcm_open (snd_pcm_t **pcm, const char *name, snd_pcm_stream_t stream, int mode) |
| Opens a PCM. More... | |
| 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. More... | |
| 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. More... | |
| int | snd_pcm_close (snd_pcm_t *pcm) |
| close PCM handle More... | |
| const char * | snd_pcm_name (snd_pcm_t *pcm) |
| get identifier of PCM handle More... | |
| snd_pcm_type_t | snd_pcm_type (snd_pcm_t *pcm) |
| get type of PCM handle More... | |
| snd_pcm_stream_t | snd_pcm_stream (snd_pcm_t *pcm) |
| get stream for a PCM handle More... | |
| int | snd_pcm_poll_descriptors_count (snd_pcm_t *pcm) |
| get count of poll descriptors for PCM handle More... | |
| int | snd_pcm_poll_descriptors (snd_pcm_t *pcm, struct pollfd *pfds, unsigned int space) |
| get poll descriptors More... | |
| 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 More... | |
| int | snd_pcm_nonblock (snd_pcm_t *pcm, int nonblock) |
| set nonblock mode More... | |
| 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. More... | |
| snd_pcm_t * | snd_async_handler_get_pcm (snd_async_handler_t *handler) |
| Return PCM handle related to an async handler. More... | |
| int | snd_pcm_info (snd_pcm_t *pcm, snd_pcm_info_t *info) |
| Obtain general (static) information for PCM handle. More... | |
| 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. More... | |
| 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. More... | |
| int | snd_pcm_hw_free (snd_pcm_t *pcm) |
| Remove PCM hardware configuration and free associated resources. More... | |
| int | snd_pcm_sw_params_current (snd_pcm_t *pcm, snd_pcm_sw_params_t *params) |
| Return current software configuration for a PCM. More... | |
| int | snd_pcm_sw_params (snd_pcm_t *pcm, snd_pcm_sw_params_t *params) |
| Install PCM software configuration defined by params. More... | |
| int | snd_pcm_prepare (snd_pcm_t *pcm) |
| Prepare PCM for use. More... | |
| int | snd_pcm_reset (snd_pcm_t *pcm) |
| Reset PCM position. More... | |
| int | snd_pcm_status (snd_pcm_t *pcm, snd_pcm_status_t *status) |
| Obtain status (runtime) information for PCM handle. More... | |
| int | snd_pcm_start (snd_pcm_t *pcm) |
| Start a PCM. More... | |
| int | snd_pcm_drop (snd_pcm_t *pcm) |
| Stop a PCM dropping pending frames. More... | |
| int | snd_pcm_drain (snd_pcm_t *pcm) |
| Stop a PCM preserving pending frames. More... | |
| int | snd_pcm_pause (snd_pcm_t *pcm, int enable) |
| Pause/resume PCM. More... | |
| snd_pcm_state_t | snd_pcm_state (snd_pcm_t *pcm) |
| Return PCM state. More... | |
| int | snd_pcm_hwsync (snd_pcm_t *pcm) |
| (DEPRECATED) Synchronize stream position with hardware More... | |
| int | snd_pcm_delay (snd_pcm_t *pcm, snd_pcm_sframes_t *delayp) |
| Obtain delay for a running PCM handle. More... | |
| int | snd_pcm_resume (snd_pcm_t *pcm) |
| Resume from suspend, no samples are lost. More... | |
| int | snd_pcm_htimestamp (snd_pcm_t *pcm, snd_pcm_uframes_t *avail, snd_htimestamp_t *tstamp) |
| Obtain last position update hi-res timestamp. More... | |
| snd_pcm_sframes_t | snd_pcm_avail (snd_pcm_t *pcm) |
| Return number of frames ready to be read (capture) / written (playback) More... | |
| snd_pcm_sframes_t | snd_pcm_avail_update (snd_pcm_t *pcm) |
| Return number of frames ready to be read (capture) / written (playback) More... | |
| 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. More... | |
| snd_pcm_sframes_t | snd_pcm_rewindable (snd_pcm_t *pcm) |
| Get safe count of frames which can be rewinded. More... | |
| snd_pcm_sframes_t | snd_pcm_rewind (snd_pcm_t *pcm, snd_pcm_uframes_t frames) |
| Move application frame position backward. More... | |
| snd_pcm_sframes_t | snd_pcm_forwardable (snd_pcm_t *pcm) |
| Get safe count of frames which can be forwarded. More... | |
| snd_pcm_sframes_t | snd_pcm_forward (snd_pcm_t *pcm, snd_pcm_uframes_t frames) |
| Move application frame position forward. More... | |
| 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. More... | |
| snd_pcm_sframes_t | snd_pcm_readi (snd_pcm_t *pcm, void *buffer, snd_pcm_uframes_t size) |
| Read interleaved frames from a PCM. More... | |
| 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. More... | |
| 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. More... | |
| int | snd_pcm_wait (snd_pcm_t *pcm, int timeout) |
| Wait for a PCM to become ready. More... | |
| int | snd_pcm_link (snd_pcm_t *pcm1, snd_pcm_t *pcm2) |
| Link two PCMs. More... | |
| int | snd_pcm_unlink (snd_pcm_t *pcm) |
| Remove a PCM from a linked group. More... | |
| snd_pcm_chmap_query_t ** | snd_pcm_query_chmaps (snd_pcm_t *pcm) |
| snd_pcm_chmap_query_t ** | snd_pcm_query_chmaps_from_hw (int card, int dev, int subdev, snd_pcm_stream_t stream) |
| void | snd_pcm_free_chmaps (snd_pcm_chmap_query_t **maps) |
| snd_pcm_chmap_t * | snd_pcm_get_chmap (snd_pcm_t *pcm) |
| int | snd_pcm_set_chmap (snd_pcm_t *pcm, const snd_pcm_chmap_t *map) |
| const char * | snd_pcm_chmap_type_name (enum snd_pcm_chmap_type val) |
| const char * | snd_pcm_chmap_name (enum snd_pcm_chmap_position val) |
| const char * | snd_pcm_chmap_long_name (enum snd_pcm_chmap_position val) |
| int | snd_pcm_chmap_print (const snd_pcm_chmap_t *map, size_t maxlen, char *buf) |
| unsigned int | snd_pcm_chmap_from_string (const char *str) |
| snd_pcm_chmap_t * | snd_pcm_chmap_parse_string (const char *str) |
| int | snd_pcm_recover (snd_pcm_t *pcm, int err, int silent) |
| Recover the stream state from an error or suspend. More... | |
| 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. More... | |
| 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. More... | |
Detailed Description
See the PCM (digital audio) interface page for more details.
Macro Definition Documentation
◆ SND_CHMAP_API_VERSION
| #define SND_CHMAP_API_VERSION ((1 << 16) | (0 << 8) | 1) |
channel mapping API version number
◆ SND_CHMAP_DRIVER_SPEC
| #define SND_CHMAP_DRIVER_SPEC (0x02 << 16) |
bit flag indicating the non-standard channel value
◆ SND_CHMAP_PHASE_INVERSE
| #define SND_CHMAP_PHASE_INVERSE (0x01 << 16) |
bit flag indicating the channel is phase inverted
◆ SND_CHMAP_POSITION_MASK
| #define SND_CHMAP_POSITION_MASK 0xffff |
bitmask for channel position
◆ SND_PCM_ABORT
| #define SND_PCM_ABORT 0x00008000 |
In an abort state (internal, not allowed for open)
◆ SND_PCM_ASYNC
| #define SND_PCM_ASYNC |
Async notification (flag for open mode)
◆ SND_PCM_DLSYM_VERSION
| #define SND_PCM_DLSYM_VERSION _dlsym_pcm_001 |
dlsym version for interface entry callback
◆ SND_PCM_NO_AUTO_CHANNELS
| #define SND_PCM_NO_AUTO_CHANNELS 0x00020000 |
Disable automatic (but not forced!) channel conversion
◆ SND_PCM_NO_AUTO_FORMAT
| #define SND_PCM_NO_AUTO_FORMAT 0x00040000 |
Disable automatic (but not forced!) format conversion
◆ SND_PCM_NO_AUTO_RESAMPLE
| #define SND_PCM_NO_AUTO_RESAMPLE 0x00010000 |
Disable automatic (but not forced!) rate resamplinig
◆ SND_PCM_NO_SOFTVOL
| #define SND_PCM_NO_SOFTVOL 0x00080000 |
Disable soft volume control
◆ SND_PCM_NONBLOCK
| #define SND_PCM_NONBLOCK |
Non blocking mode (flag for open mode)
- Examples
- /test/latency.c.
Typedef Documentation
◆ snd_pcm_access_mask_t
| typedef struct _snd_pcm_access_mask snd_pcm_access_mask_t |
PCM access types mask
◆ snd_pcm_format_mask_t
| typedef struct _snd_pcm_format_mask snd_pcm_format_mask_t |
PCM formats mask
◆ snd_pcm_hw_params_t
| typedef struct _snd_pcm_hw_params snd_pcm_hw_params_t |
PCM hardware configuration space container
snd_pcm_hw_params_t is an opaque structure which contains a set of possible PCM hardware configurations. For example, a given instance might include a range of buffer sizes, a range of period sizes, and a set of several sample formats. Some subset of all possible combinations these sets may be valid, but not necessarily any combination will be valid.
When a parameter is set or restricted using a snd_pcm_hw_params_set* function, all of the other ranges will be updated to exclude as many impossible configurations as possible. Attempting to set a parameter outside of its acceptable range will result in the function failing and an error code being returned.
◆ snd_pcm_info_t
| typedef struct _snd_pcm_info snd_pcm_info_t |
PCM generic info container
◆ snd_pcm_scope_t
| typedef struct _snd_pcm_scope snd_pcm_scope_t |
SND_PCM_TYPE_METER scope handle
◆ snd_pcm_sframes_t
| typedef long snd_pcm_sframes_t |
Signed frames quantity
◆ snd_pcm_status_t
| typedef struct _snd_pcm_status snd_pcm_status_t |
PCM status container
◆ snd_pcm_subformat_mask_t
| typedef struct _snd_pcm_subformat_mask snd_pcm_subformat_mask_t |
PCM subformats mask
◆ snd_pcm_sw_params_t
| typedef struct _snd_pcm_sw_params snd_pcm_sw_params_t |
PCM software configuration container
◆ snd_pcm_t
| typedef struct _snd_pcm snd_pcm_t |
PCM handle
◆ snd_pcm_type_t
| typedef enum _snd_pcm_type snd_pcm_type_t |
PCM type
◆ snd_pcm_uframes_t
| typedef unsigned long snd_pcm_uframes_t |
Unsigned frames quantity
Enumeration Type Documentation
◆ _snd_pcm_type
| enum _snd_pcm_type |
PCM type
◆ snd_pcm_access_t
| enum snd_pcm_access_t |
PCM access type
◆ snd_pcm_audio_tstamp_type_t
◆ snd_pcm_chmap_position
channel positions
◆ snd_pcm_chmap_type
| enum snd_pcm_chmap_type |
◆ snd_pcm_class_t
| enum snd_pcm_class_t |
◆ snd_pcm_format_t
| enum snd_pcm_format_t |
PCM sample format
◆ snd_pcm_start_t
| enum snd_pcm_start_t |
◆ snd_pcm_state_t
| enum snd_pcm_state_t |
PCM state
◆ snd_pcm_stream_t
| enum snd_pcm_stream_t |
◆ snd_pcm_subclass_t
| enum snd_pcm_subclass_t |
◆ snd_pcm_subformat_t
| enum snd_pcm_subformat_t |
◆ snd_pcm_tstamp_t
| enum snd_pcm_tstamp_t |
PCM timestamp mode
| Enumerator | |
|---|---|
| SND_PCM_TSTAMP_NONE | No timestamp |
| SND_PCM_TSTAMP_ENABLE | Update timestamp at every hardware position update |
| SND_PCM_TSTAMP_MMAP | Equivalent with SND_PCM_TSTAMP_ENABLE, just for compatibility with older versions |
◆ snd_pcm_tstamp_type_t
◆ snd_pcm_xrun_t
| enum snd_pcm_xrun_t |
Function Documentation
◆ snd_async_add_pcm_handler()
| int snd_async_add_pcm_handler | ( | snd_async_handler_t ** | handler, |
| snd_pcm_t * | pcm, | ||
| snd_async_callback_t | callback, | ||
| void * | private_data | ||
| ) |
Add an async handler for a PCM.
- Parameters
-
handler Returned handler handle pcm PCM handle callback Callback function private_data Callback private data
- Returns
- 0 otherwise a negative error code on failure
The asynchronous callback is called when period boundary elapses.
- Examples
- /test/pcm.c.
◆ snd_async_handler_get_pcm()
| snd_pcm_t * snd_async_handler_get_pcm | ( | snd_async_handler_t * | handler | ) |
Return PCM handle related to an async handler.
- Parameters
-
handler Async handler handle
- Returns
- PCM handle
- Examples
- /test/pcm.c.
◆ snd_pcm_avail()
| snd_pcm_sframes_t snd_pcm_avail | ( | snd_pcm_t * | pcm | ) |
Return number of frames ready to be read (capture) / written (playback)
- Parameters
-
pcm PCM handle
- Returns
- a positive number of frames ready otherwise a negative error code
On capture does all the actions needed to transport to application level all the ready frames across underlying layers.
The position is synced with hardware (driver) position in the sound ring buffer in this functions.
The function is thread-safe when built with the proper option.
◆ snd_pcm_avail_delay()
| int snd_pcm_avail_delay | ( | snd_pcm_t * | pcm, |
| snd_pcm_sframes_t * | availp, | ||
| snd_pcm_sframes_t * | delayp | ||
| ) |
Combine snd_pcm_avail and snd_pcm_delay functions.
- Parameters
-
pcm PCM handle availp Number of available frames in the ring buffer delayp Total I/O latency in frames
- Returns
- zero on success otherwise a negative error code
The avail and delay values retuned are in sync.
The function is thread-safe when built with the proper option.
◆ snd_pcm_avail_update()
| snd_pcm_sframes_t snd_pcm_avail_update | ( | snd_pcm_t * | pcm | ) |
Return number of frames ready to be read (capture) / written (playback)
- Parameters
-
pcm PCM handle
- Returns
- a positive number of frames ready otherwise a negative error code
On capture does all the actions needed to transport to application level all the ready frames across underlying layers.
The position is not synced with hardware (driver) position in the sound ring buffer in this function. This function is a light version of snd_pcm_avail() .
Using this function is ideal after poll() or select() when audio file descriptor made the event and when application expects just period timing.
Also this function might be called after snd_pcm_delay() or snd_pcm_hwsync() functions to move private ring buffer pointers in alsa-lib (the internal plugin chain).
The function is thread-safe when built with the proper option.
- Examples
- /test/pcm.c.
◆ snd_pcm_chmap_from_string()
| unsigned int snd_pcm_chmap_from_string | ( | const char * | str | ) |
!brief Convert from string to channel position
- Parameters
-
str The string to parse
- Returns
- The channel position value or -1 as an error
◆ snd_pcm_chmap_long_name()
| const char * snd_pcm_chmap_long_name | ( | enum snd_pcm_chmap_position | val | ) |
!brief Get a longer name string for a standard channel map position
- Parameters
-
val Channel position
- Returns
- The string corresponding to the given position, or NULL
◆ snd_pcm_chmap_name()
| const char * snd_pcm_chmap_name | ( | enum snd_pcm_chmap_position | val | ) |
!brief Get a name string for a standard channel map position
- Parameters
-
val Channel position
- Returns
- The string corresponding to the given position, or NULL
◆ snd_pcm_chmap_parse_string()
| snd_pcm_chmap_t * snd_pcm_chmap_parse_string | ( | const char * | str | ) |
!brief Convert from string to channel map
- Parameters
-
str The string to parse
- Returns
- The channel map
Note: the caller is requested to release the returned value via free()
◆ snd_pcm_chmap_print()
| int snd_pcm_chmap_print | ( | const snd_pcm_chmap_t * | map, |
| size_t | maxlen, | ||
| char * | buf | ||
| ) |
!brief Print the channels in chmap on the buffer
- Parameters
-
map The channel map to print maxlen The maximal length to write (including NUL letter) buf The buffer to write
- Returns
- The actual string length or a negative error code
◆ snd_pcm_chmap_type_name()
| const char * snd_pcm_chmap_type_name | ( | enum snd_pcm_chmap_type | val | ) |
!brief Get a name string for a channel map type as query results
- Parameters
-
val Channel position
- Returns
- The string corresponding to the given type, or NULL
◆ snd_pcm_close()
| int snd_pcm_close | ( | snd_pcm_t * | pcm | ) |
close PCM handle
- Parameters
-
pcm PCM handle
- Returns
- 0 on success otherwise a negative error code
Closes the specified PCM handle and frees all associated resources.
- Examples
- /test/latency.c, /test/pcm.c, and /test/pcm_min.c.
◆ snd_pcm_delay()
| int snd_pcm_delay | ( | snd_pcm_t * | pcm, |
| snd_pcm_sframes_t * | delayp | ||
| ) |
Obtain delay for a running PCM handle.
- Parameters
-
pcm PCM handle delayp Returned delay in frames
- Returns
- 0 on success otherwise a negative error code
For playback the delay is defined as the time that a frame that is written to the PCM stream shortly after this call will take to be actually audible. It is as such the overall latency from the write call to the final DAC.
For capture the delay is defined as the time that a frame that was digitized by the audio device takes until it can be read from the PCM stream shortly after this call returns. It is as such the overall latency from the initial ADC to the read call.
Please note that hence in case of a playback underrun this value will not necessarily got down to 0.
If the application is interested in the fill level of the playback buffer of the device, it should use snd_pcm_avail*() functions. The value returned by that call is not directly related to the delay, since the latter might include some additional, fixed latencies the former does not.
Note this function does not update the actual r/w pointer for applications. The function snd_pcm_avail_update() have to be called before any begin+commit operation.
The function is thread-safe when built with the proper option.
◆ snd_pcm_drain()
| int snd_pcm_drain | ( | snd_pcm_t * | pcm | ) |
Stop a PCM preserving pending frames.
- Parameters
-
pcm PCM handle
- Returns
- 0 on success otherwise a negative error code
- Return values
-
-ESTRPIPE a suspend event occurred
For playback wait for all pending frames to be played and then stop the PCM. For capture stop PCM permitting to retrieve residual frames.
For stopping the PCM stream immediately, use ::snd_pcm_drop() instead.
The function is thread-safe when built with the proper option.
- Examples
- /test/latency.c, and /test/pcm_min.c.
◆ snd_pcm_drop()
| int snd_pcm_drop | ( | snd_pcm_t * | pcm | ) |
Stop a PCM dropping pending frames.
- Parameters
-
pcm PCM handle
- Returns
- 0 on success otherwise a negative error code
This function stops the PCM immediately. The pending samples on the buffer are ignored.
For processing all pending samples, use ::snd_pcm_drain() instead.
The function is thread-safe when built with the proper option.
- Examples
- /test/latency.c.
◆ snd_pcm_forward()
| snd_pcm_sframes_t snd_pcm_forward | ( | snd_pcm_t * | pcm, |
| snd_pcm_uframes_t | frames | ||
| ) |
Move application frame position forward.
- Parameters
-
pcm PCM handle frames wanted skip in frames
- Returns
- a positive number for actual skip otherwise a negative error code
- Return values
-
0 means no action
The function is thread-safe when built with the proper option.
◆ snd_pcm_forwardable()
| snd_pcm_sframes_t snd_pcm_forwardable | ( | snd_pcm_t * | pcm | ) |
Get safe count of frames which can be forwarded.
- Parameters
-
pcm PCM handle
- Returns
- a positive number of frames or negative error code
Note: The snd_pcm_forward() can accept bigger value than returned by this function. But it is not guaranteed that output stream will be consistent with bigger value.
The function is thread-safe when built with the proper option.
◆ snd_pcm_free_chmaps()
| void snd_pcm_free_chmaps | ( | snd_pcm_chmap_query_t ** | maps | ) |
!brief Release the channel map array allocated via snd_pcm_query_chmaps
- Parameters
-
maps the array pointer to release
◆ snd_pcm_get_chmap()
| snd_pcm_chmap_t * snd_pcm_get_chmap | ( | snd_pcm_t * | pcm | ) |
!brief Get the current channel map
- Parameters
-
pcm PCM instance
- Returns
- the current channel map, or NULL if error
Note: the caller is requested to release the returned value via free()
◆ snd_pcm_get_params()
| int snd_pcm_get_params | ( | snd_pcm_t * | pcm, |
| snd_pcm_uframes_t * | buffer_size, | ||
| snd_pcm_uframes_t * | period_size | ||
| ) |
Get the transfer size parameters in a simple way.
- Parameters
-
pcm PCM handle buffer_size PCM ring buffer size in frames period_size PCM period size in frames
- Returns
- 0 on success otherwise a negative error code
◆ snd_pcm_htimestamp()
| int snd_pcm_htimestamp | ( | snd_pcm_t * | pcm, |
| snd_pcm_uframes_t * | avail, | ||
| snd_htimestamp_t * | tstamp | ||
| ) |
Obtain last position update hi-res timestamp.
- Parameters
-
pcm PCM handle avail Number of available frames when timestamp was grabbed tstamp Hi-res timestamp
- Returns
- 0 on success otherwise a negative error code
Note this function does not update the actual r/w pointer for applications.
The function is thread-safe when built with the proper option.
◆ snd_pcm_hw_free()
| int snd_pcm_hw_free | ( | snd_pcm_t * | pcm | ) |
Remove PCM hardware configuration and free associated resources.
- Parameters
-
pcm PCM handle
- Returns
- 0 on success otherwise a negative error code
- Examples
- /test/latency.c.
◆ snd_pcm_hw_params()
| int snd_pcm_hw_params | ( | snd_pcm_t * | pcm, |
| snd_pcm_hw_params_t * | params | ||
| ) |
Install one PCM hardware configuration chosen from a configuration space and snd_pcm_prepare it.
- Parameters
-
pcm PCM handle params Configuration space definition container
- Returns
- 0 on success otherwise a negative error code
The configuration is chosen fixing single parameters in this order: first access, first format, first subformat, min channels, min rate, min period time, max buffer size, min tick time. If no mutually compatible set of parameters can be chosen, a negative error code will be returned.
After this call, snd_pcm_prepare() is called automatically and the stream is brought to SND_PCM_STATE_PREPARED state.
The hardware parameters cannot be changed when the stream is running (active). The software parameters can be changed at any time.
The configuration space will be updated to reflect the chosen parameters.
- Examples
- /test/latency.c, and /test/pcm.c.
◆ snd_pcm_hw_params_current()
| int snd_pcm_hw_params_current | ( | snd_pcm_t * | pcm, |
| snd_pcm_hw_params_t * | params | ||
| ) |
Retreive current PCM hardware configuration chosen with snd_pcm_hw_params.
- Parameters
-
pcm PCM handle params Configuration space definition container
- Returns
- 0 on success otherwise a negative error code
◆ snd_pcm_hwsync()
| int snd_pcm_hwsync | ( | snd_pcm_t * | pcm | ) |
(DEPRECATED) Synchronize stream position with hardware
- Parameters
-
pcm PCM handle
- Returns
- 0 on success otherwise a negative error code
Note this function does not update the actual r/w pointer for applications. The function snd_pcm_avail_update() have to be called before any mmap begin+commit operation.
The function is thread-safe when built with the proper option.
This function is deprecated. Use snd_pcm_avail_update() instead.
◆ snd_pcm_info()
| int snd_pcm_info | ( | snd_pcm_t * | pcm, |
| snd_pcm_info_t * | info | ||
| ) |
Obtain general (static) information for PCM handle.
- Parameters
-
pcm PCM handle info Information container
- Returns
- 0 on success otherwise a negative error code
◆ snd_pcm_link()
Link two PCMs.
- Parameters
-
pcm1 first PCM handle pcm2 first PCM handle
- Returns
- 0 on success otherwise a negative error code
The two PCMs will start/stop/prepare in sync.
- Examples
- /test/latency.c.
◆ snd_pcm_name()
| const char * snd_pcm_name | ( | snd_pcm_t * | pcm | ) |
get identifier of PCM handle
- Parameters
-
pcm PCM handle
- Returns
- ascii identifier of PCM handle
Returns the ASCII identifier of given PCM handle. It's the same identifier specified in snd_pcm_open().
◆ snd_pcm_nonblock()
| int snd_pcm_nonblock | ( | snd_pcm_t * | pcm, |
| int | nonblock | ||
| ) |
set nonblock mode
- Parameters
-
pcm PCM handle nonblock 0 = block, 1 = nonblock mode, 2 = abort
- Returns
- 0 on success otherwise a negative error code
The function is thread-safe when built with the proper option.
- Examples
- /test/latency.c.
◆ snd_pcm_open()
| int snd_pcm_open | ( | snd_pcm_t ** | pcmp, |
| const char * | name, | ||
| snd_pcm_stream_t | stream, | ||
| int | mode | ||
| ) |
Opens a PCM.
- Parameters
-
pcmp Returned PCM handle name ASCII identifier of the PCM handle stream Wanted stream mode Open mode (see SND_PCM_NONBLOCK, SND_PCM_ASYNC)
- Returns
- 0 on success otherwise a negative error code
- Examples
- /test/latency.c, /test/pcm.c, and /test/pcm_min.c.
◆ snd_pcm_open_fallback()
| int snd_pcm_open_fallback | ( | snd_pcm_t ** | pcmp, |
| snd_config_t * | root, | ||
| const char * | name, | ||
| const char * | orig_name, | ||
| snd_pcm_stream_t | stream, | ||
| int | mode | ||
| ) |
Opens a fallback PCM.
- Parameters
-
pcmp Returned PCM handle root Configuration root name ASCII identifier of the PCM handle orig_name The original ASCII name stream Wanted stream mode Open mode (see SND_PCM_NONBLOCK, SND_PCM_ASYNC)
- Returns
- 0 on success otherwise a negative error code
◆ snd_pcm_open_lconf()
| int snd_pcm_open_lconf | ( | snd_pcm_t ** | pcmp, |
| const char * | name, | ||
| snd_pcm_stream_t | stream, | ||
| int | mode, | ||
| snd_config_t * | lconf | ||
| ) |
Opens a PCM using local configuration.
- Parameters
-
pcmp Returned PCM handle name ASCII identifier of the PCM handle stream Wanted stream mode Open mode (see SND_PCM_NONBLOCK, SND_PCM_ASYNC) lconf Local configuration
- Returns
- 0 on success otherwise a negative error code
◆ snd_pcm_pause()
| int snd_pcm_pause | ( | snd_pcm_t * | pcm, |
| int | enable | ||
| ) |
Pause/resume PCM.
- Parameters
-
pcm PCM handle enable 0 = resume, 1 = pause
- Returns
- 0 on success otherwise a negative error code
Note that this function works only on the hardware which supports pause feature. You can check it via ::snd_pcm_hw_params_can_pause() function.
The function is thread-safe when built with the proper option.
◆ snd_pcm_poll_descriptors()
| int snd_pcm_poll_descriptors | ( | snd_pcm_t * | pcm, |
| struct pollfd * | pfds, | ||
| unsigned int | space | ||
| ) |
get poll descriptors
- Parameters
-
pcm PCM handle pfds array of poll descriptors space space in the poll descriptor array
- Returns
- count of filled descriptors
This function fills the given poll descriptor structs for the specified PCM handle. The poll desctiptor array should have the size returned by ::snd_pcm_poll_descriptors_count() function.
The result is intended for direct use with the poll() syscall.
For reading the returned events of poll descriptor after poll() system call, use ::snd_pcm_poll_descriptors_revents() function. The field values in pollfd structs may be bogus regarding the stream direction from the application perspective (POLLIN might not imply read direction and POLLOUT might not imply write), but the ::snd_pcm_poll_descriptors_revents() function does the right "demangling".
You can use output from this function as arguments for the select() syscall, too. Do not forget to translate POLLIN and POLLOUT events to corresponding FD_SET arrays and demangle events using ::snd_pcm_poll_descriptors_revents() .
The function is thread-safe when built with the proper option.
- Examples
- /test/pcm.c.
◆ snd_pcm_poll_descriptors_count()
| int snd_pcm_poll_descriptors_count | ( | snd_pcm_t * | pcm | ) |
get count of poll descriptors for PCM handle
- Parameters
-
pcm PCM handle
- Returns
- count of poll descriptors
The function is thread-safe when built with the proper option.
- Examples
- /test/pcm.c.
◆ snd_pcm_poll_descriptors_revents()
| int snd_pcm_poll_descriptors_revents | ( | snd_pcm_t * | pcm, |
| struct pollfd * | pfds, | ||
| unsigned int | nfds, | ||
| unsigned short * | revents | ||
| ) |
get returned events from poll descriptors
- Parameters
-
pcm PCM handle pfds array of poll descriptors nfds count of poll descriptors revents pointer to the returned (single) event
- Returns
- zero if success, otherwise a negative error code
This function does "demangling" of the revents mask returned from the poll() syscall to correct semantics (POLLIN = read, POLLOUT = write).
Note: The null event also exists. Even if poll() or select() syscall returned that some events are waiting, this function might return empty set of events. In this case, application should do next event waiting using poll() or select().
Note: Even if multiple poll descriptors are used (i.e. pfds > 1), this function returns only a single event.
The function is thread-safe when built with the proper option.
- Examples
- /test/pcm.c.
◆ snd_pcm_prepare()
| int snd_pcm_prepare | ( | snd_pcm_t * | pcm | ) |
Prepare PCM for use.
- Parameters
-
pcm PCM handle
- Returns
- 0 on success otherwise a negative error code
The function is thread-safe when built with the proper option.
- Examples
- /test/latency.c, and /test/pcm.c.
◆ snd_pcm_query_chmaps()
| snd_pcm_chmap_query_t ** snd_pcm_query_chmaps | ( | snd_pcm_t * | pcm | ) |
!brief Query the available channel maps
- Parameters
-
pcm PCM handle to query
- Returns
- the NULL-terminated array of integer pointers, each of which contains the channel map. A channel map is represented by an integer array, beginning with the channel map type, followed by the number of channels, and the position of each channel. Return NULL in case of an error.
Note: the caller is requested to release the returned value via snd_pcm_free_chmaps().
◆ snd_pcm_query_chmaps_from_hw()
| snd_pcm_chmap_query_t ** snd_pcm_query_chmaps_from_hw | ( | int | card, |
| int | dev, | ||
| int | subdev, | ||
| snd_pcm_stream_t | stream | ||
| ) |
!brief Query the available channel maps
- Parameters
-
card the card number dev the PCM device number subdev the PCM substream index stream the direction of PCM stream
- Returns
- the NULL-terminated array of integer pointers, or NULL at error.
This function works like snd_pcm_query_chmaps() but it takes the card, device, substream and stream numbers instead of the already opened snd_pcm_t instance, so that you can query available channel maps of a PCM before actually opening it.
As the parameters stand, the query is performed only to the hw PCM devices, not the abstracted PCM object in alsa-lib.
◆ snd_pcm_readi()
| snd_pcm_sframes_t snd_pcm_readi | ( | snd_pcm_t * | pcm, |
| void * | buffer, | ||
| snd_pcm_uframes_t | size | ||
| ) |
Read interleaved frames from a PCM.
- Parameters
-
pcm PCM handle buffer frames containing buffer size frames to be read
- Returns
- a positive number of frames actually read otherwise a negative error code
- Return values
-
-EBADFD PCM is not in the right state (SND_PCM_STATE_PREPARED or SND_PCM_STATE_RUNNING) -EPIPE an overrun occurred -ESTRPIPE a suspend event occurred (stream is suspended and waiting for an application recovery)
If the blocking behaviour was selected and it is running, then routine waits until all requested frames are filled. The returned number of frames can be less only if a signal or underrun occurred.
If the non-blocking behaviour is selected, then routine doesn't wait at all.
The function is thread-safe when built with the proper option.
- Examples
- /test/latency.c.
◆ snd_pcm_readn()
| snd_pcm_sframes_t snd_pcm_readn | ( | snd_pcm_t * | pcm, |
| void ** | bufs, | ||
| snd_pcm_uframes_t | size | ||
| ) |
Read non interleaved frames to a PCM.
- Parameters
-
pcm PCM handle bufs frames containing buffers (one for each channel) size frames to be read
- Returns
- a positive number of frames actually read otherwise a negative error code
- Return values
-
-EBADFD PCM is not in the right state (SND_PCM_STATE_PREPARED or SND_PCM_STATE_RUNNING) -EPIPE an overrun occurred -ESTRPIPE a suspend event occurred (stream is suspended and waiting for an application recovery)
If the blocking behaviour was selected and it is running, then routine waits until all requested frames are filled. The returned number of frames can be less only if a signal or underrun occurred.
If the non-blocking behaviour is selected, then routine doesn't wait at all.
The function is thread-safe when built with the proper option.
◆ snd_pcm_recover()
| int snd_pcm_recover | ( | snd_pcm_t * | pcm, |
| int | err, | ||
| int | silent | ||
| ) |
Recover the stream state from an error or suspend.
- Parameters
-
pcm PCM handle err error number silent do not print error reason
- Returns
- 0 when error code was handled successfuly, otherwise a negative error code
This a high-level helper function building on other functions.
This functions handles -EINTR (interrupted system call), -EPIPE (overrun or underrun) and -ESTRPIPE (stream is suspended) error codes trying to prepare given stream for next I/O.
Note that this function returs the original error code when it is not handled inside this function (for example -EAGAIN is returned back).
- Examples
- /test/pcm_min.c.
◆ snd_pcm_reset()
| int snd_pcm_reset | ( | snd_pcm_t * | pcm | ) |
Reset PCM position.
- Parameters
-
pcm PCM handle
- Returns
- 0 on success otherwise a negative error code
Reduce PCM delay to 0.
The function is thread-safe when built with the proper option.
◆ snd_pcm_resume()
| int snd_pcm_resume | ( | snd_pcm_t * | pcm | ) |
Resume from suspend, no samples are lost.
- Parameters
-
pcm PCM handle
- Returns
- 0 on success otherwise a negative error code
- Return values
-
-EAGAIN resume can't be proceed immediately (audio hardware is probably still suspended) -ENOSYS hardware doesn't support this feature
This function can be used when the stream is in the suspend state to do the fine resume from this state. Not all hardware supports this feature, when an -ENOSYS error is returned, use the ::snd_pcm_prepare() function to recovery.
The function is thread-safe when built with the proper option.
- Examples
- /test/pcm.c.
◆ snd_pcm_rewind()
| snd_pcm_sframes_t snd_pcm_rewind | ( | snd_pcm_t * | pcm, |
| snd_pcm_uframes_t | frames | ||
| ) |
Move application frame position backward.
- Parameters
-
pcm PCM handle frames wanted displacement in frames
- Returns
- a positive number for actual displacement otherwise a negative error code
The function is thread-safe when built with the proper option.
◆ snd_pcm_rewindable()
| snd_pcm_sframes_t snd_pcm_rewindable | ( | snd_pcm_t * | pcm | ) |
Get safe count of frames which can be rewinded.
- Parameters
-
pcm PCM handle
- Returns
- a positive number of frames or negative error code
Note: The snd_pcm_rewind() can accept bigger value than returned by this function. But it is not guaranteed that output stream will be consistent with bigger value.
The function is thread-safe when built with the proper option.
◆ snd_pcm_set_chmap()
| int snd_pcm_set_chmap | ( | snd_pcm_t * | pcm, |
| const snd_pcm_chmap_t * | map | ||
| ) |
!brief Configure the current channel map
- Parameters
-
pcm PCM instance map the channel map to write
- Returns
- zero if succeeded, or a negative error code
◆ snd_pcm_set_params()
| int snd_pcm_set_params | ( | snd_pcm_t * | pcm, |
| snd_pcm_format_t | format, | ||
| snd_pcm_access_t | access, | ||
| unsigned int | channels, | ||
| unsigned int | rate, | ||
| int | soft_resample, | ||
| unsigned int | latency | ||
| ) |
Set the hardware and software parameters in a simple way.
- Parameters
-
pcm PCM handle format required PCM format access required PCM access channels required PCM channels rate required sample rate in Hz soft_resample 0 = disallow alsa-lib resample stream, 1 = allow resampling latency required overall latency in us
- Returns
- 0 on success otherwise a negative error code
- Examples
- /test/pcm_min.c.
◆ snd_pcm_start()
| int snd_pcm_start | ( | snd_pcm_t * | pcm | ) |
Start a PCM.
- Parameters
-
pcm PCM handle
- Returns
- 0 on success otherwise a negative error code
The function is thread-safe when built with the proper option.
- Examples
- /test/latency.c, and /test/pcm.c.
◆ snd_pcm_state()
| snd_pcm_state_t snd_pcm_state | ( | snd_pcm_t * | pcm | ) |
Return PCM state.
- Parameters
-
pcm PCM handle
- Returns
- PCM state snd_pcm_state_t of given PCM handle
This is a faster way to obtain only the PCM state without calling ::snd_pcm_status().
Note that this function always returns one of the snd_pcm_state_t enum variants. It will never return a negative error code.
The function is thread-safe when built with the proper option.
- Examples
- /test/pcm.c.
◆ snd_pcm_status()
| int snd_pcm_status | ( | snd_pcm_t * | pcm, |
| snd_pcm_status_t * | status | ||
| ) |
Obtain status (runtime) information for PCM handle.
- Parameters
-
pcm PCM handle status Status container
- Returns
- 0 on success otherwise a negative error code
The function is thread-safe when built with the proper option.
- Examples
- /test/latency.c.
◆ snd_pcm_stream()
| snd_pcm_stream_t snd_pcm_stream | ( | snd_pcm_t * | pcm | ) |
get stream for a PCM handle
- Parameters
-
pcm PCM handle
- Returns
- stream of PCM handle
Returns the type snd_pcm_stream_t of given PCM handle.
◆ snd_pcm_sw_params()
| int snd_pcm_sw_params | ( | snd_pcm_t * | pcm, |
| snd_pcm_sw_params_t * | params | ||
| ) |
Install PCM software configuration defined by params.
- Parameters
-
pcm PCM handle params Configuration container
- Returns
- 0 on success otherwise a negative error code
The software parameters can be changed at any time. The hardware parameters cannot be changed when the stream is running (active).
The function is thread-safe when built with the proper option.
- Examples
- /test/latency.c, and /test/pcm.c.
◆ snd_pcm_sw_params_current()
| int snd_pcm_sw_params_current | ( | snd_pcm_t * | pcm, |
| snd_pcm_sw_params_t * | params | ||
| ) |
Return current software configuration for a PCM.
- Parameters
-
pcm PCM handle params Software configuration container
- Returns
- 0 on success otherwise a negative error code
The function is thread-safe when built with the proper option.
- Examples
- /test/latency.c, and /test/pcm.c.
◆ snd_pcm_type()
| snd_pcm_type_t snd_pcm_type | ( | snd_pcm_t * | pcm | ) |
get type of PCM handle
- Parameters
-
pcm PCM handle
- Returns
- type of PCM handle
Returns the type snd_pcm_type_t of given PCM handle.
◆ snd_pcm_unlink()
| int snd_pcm_unlink | ( | snd_pcm_t * | pcm | ) |
Remove a PCM from a linked group.
- Parameters
-
pcm PCM handle
- Returns
- 0 on success otherwise a negative error code
- Examples
- /test/latency.c.
◆ snd_pcm_wait()
| int snd_pcm_wait | ( | snd_pcm_t * | pcm, |
| int | timeout | ||
| ) |
Wait for a PCM to become ready.
- Parameters
-
pcm PCM handle timeout maximum time in milliseconds to wait, a 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
The function is thread-safe when built with the proper option.
- Examples
- /test/latency.c, and /test/pcm.c.
◆ snd_pcm_writei()
| snd_pcm_sframes_t snd_pcm_writei | ( | snd_pcm_t * | pcm, |
| const void * | buffer, | ||
| snd_pcm_uframes_t | size | ||
| ) |
Write interleaved frames to a PCM.
- Parameters
-
pcm PCM handle buffer frames containing buffer size frames to be written
- Returns
- a positive number of frames actually written otherwise a negative error code
- Return values
-
-EBADFD PCM is not in the right state (SND_PCM_STATE_PREPARED or SND_PCM_STATE_RUNNING) -EPIPE an underrun occurred -ESTRPIPE a suspend event occurred (stream is suspended and waiting for an application recovery)
If the blocking behaviour is selected and it is running, then routine waits until all requested frames are played or put to the playback ring buffer. The returned number of frames can be less only if a signal or underrun occurred.
If the non-blocking behaviour is selected, then routine doesn't wait at all.
The function is thread-safe when built with the proper option.
- Examples
- /test/latency.c, /test/pcm.c, and /test/pcm_min.c.
◆ snd_pcm_writen()
| snd_pcm_sframes_t snd_pcm_writen | ( | snd_pcm_t * | pcm, |
| void ** | bufs, | ||
| snd_pcm_uframes_t | size | ||
| ) |
Write non interleaved frames to a PCM.
- Parameters
-
pcm PCM handle bufs frames containing buffers (one for each channel) size frames to be written
- Returns
- a positive number of frames actually written otherwise a negative error code
- Return values
-
-EBADFD PCM is not in the right state (SND_PCM_STATE_PREPARED or SND_PCM_STATE_RUNNING) -EPIPE an underrun occurred -ESTRPIPE a suspend event occurred (stream is suspended and waiting for an application recovery)
If the blocking behaviour is selected and it is running, then routine waits until all requested frames are played or put to the playback ring buffer. The returned number of frames can be less only if a signal or underrun occurred.
If the non-blocking behaviour is selected, then routine doesn't wait at all.
The function is thread-safe when built with the proper option.
