libtinyalsa-pcm − PCM Interface
− All macros, structures and functions that make up the PCM interface.
struct
pcm
A PCM handle.
struct pcm_config
Encapsulates the hardware and software parameters of a PCM.
struct pcm_plugin_ops
Operations that are required to be registered by the plugin.
struct pcm_plugin_min_max
Minimum and maximum values for hardware parameter
constraints.
struct pcm_plugin_hw_constraints
Encapsulate the hardware parameter constraints.
#define
PCM_OUT 0x00000000
A flag that specifies that the PCM is an output.
#define PCM_IN 0x10000000
Specifies that the PCM is an input.
#define PCM_MMAP 0x00000001
Specifies that the PCM will use mmap read and write methods.
#define PCM_NOIRQ 0x00000002
Specifies no interrupt requests.
#define PCM_NORESTART 0x00000004
When set, calls to pcm_write for a playback stream
will not attempt to restart the stream in the case of an
underflow, but will return -EPIPE instead.
#define PCM_MONOTONIC 0x00000008
Specifies monotonic timestamps.
#define PCM_NONBLOCK 0x00000010
If used with pcm_open and pcm_params_get, it
will not cause the function to block if the PCM is not
available.
#define PCM_STATE_OPEN 0x00
Means a PCM is opened.
#define PCM_STATE_SETUP 0x01
Means a PCM HW_PARAMS is set.
#define PCM_STATE_PREPARED 0x02
Means a PCM is prepared.
#define PCM_STATE_RUNNING 0x03
For inputs, this means the PCM is recording audio samples.
#define PCM_STATE_SUSPENDED 0x07
Means a PCM is suspended.
#define PCM_STATE_DISCONNECTED 0x08
Means a PCM has been disconnected.
enum
pcm_format { PCM_FORMAT_INVALID = -1,
PCM_FORMAT_S16_LE = 0, PCM_FORMAT_S32_LE,
PCM_FORMAT_S8, PCM_FORMAT_S24_LE,
PCM_FORMAT_S24_3LE, PCM_FORMAT_S16_BE,
PCM_FORMAT_S24_BE, PCM_FORMAT_S24_3BE,
PCM_FORMAT_S32_BE, PCM_FORMAT_MAX }
Audio sample format of a PCM.
enum pcm_param { PCM_PARAM_ACCESS,
PCM_PARAM_FORMAT, PCM_PARAM_SUBFORMAT,
PCM_PARAM_SAMPLE_BITS, PCM_PARAM_FRAME_BITS,
PCM_PARAM_CHANNELS, PCM_PARAM_RATE,
PCM_PARAM_PERIOD_TIME, PCM_PARAM_PERIOD_SIZE,
PCM_PARAM_PERIOD_BYTES, PCM_PARAM_PERIODS,
PCM_PARAM_BUFFER_TIME, PCM_PARAM_BUFFER_SIZE,
PCM_PARAM_BUFFER_BYTES, PCM_PARAM_TICK_TIME }
Enumeration of a PCM’s hardware parameters.
unsigned int
pcm_get_buffer_size (const struct pcm
*pcm)
Gets the buffer size of the PCM.
unsigned int pcm_get_channels (const struct
pcm *pcm)
Gets the channel count of the PCM.
const struct pcm_config * pcm_get_config
(const struct pcm *pcm)
Gets the PCM configuration.
unsigned int pcm_get_rate (const struct pcm
*pcm)
Gets the rate of the PCM.
enum pcm_format pcm_get_format (const struct
pcm *pcm)
Gets the format of the PCM.
int pcm_get_file_descriptor (const struct pcm
*pcm)
Gets the file descriptor of the PCM.
const char * pcm_get_error (const struct pcm
*pcm)
Gets the error message for the last error that occured.
int pcm_set_config (struct pcm *pcm,
const struct pcm_config *config)
Sets the PCM configuration.
unsigned int pcm_format_to_bits (enum
pcm_format format)
Determines the number of bits occupied by a
pcm_format.
unsigned int pcm_bytes_to_frames (const struct
pcm *pcm, unsigned int bytes)
Determines how many frames of a PCM can fit into a number of
bytes.
unsigned int pcm_frames_to_bytes (const struct
pcm *pcm, unsigned int frames)
Determines how many bytes are occupied by a number of frames
of a PCM.
struct pcm_params * pcm_params_get (unsigned int
card, unsigned int device, unsigned int flags)
Gets the hardware parameters of a PCM, without created a PCM
handle.
void pcm_params_free (struct pcm_params *pcm_params)
Frees the hardware parameters returned by
pcm_params_get.
const struct pcm_mask * pcm_params_get_mask
(const struct pcm_params *pcm_params, enum pcm_param
param)
Gets a mask from a PCM’s hardware parameters.
int pcm_close (struct pcm *pcm)
Closes a PCM returned by pcm_open.
struct pcm * pcm_open_by_name (const char
*name, unsigned int flags, const struct pcm_config
*config)
Opens a PCM by it’s name.
struct pcm * pcm_open (unsigned int card,
unsigned int device, unsigned int flags, const struct
pcm_config *config)
Opens a PCM.
int pcm_is_ready (const struct pcm
*pcm)
Checks if a PCM file has been opened without error.
int pcm_link (struct pcm *pcm1, struct
pcm *pcm2)
Links two PCMs.
int pcm_unlink (struct pcm *pcm)
Unlinks a PCM.
int pcm_prepare (struct pcm *pcm)
Prepares a PCM, if it has not been prepared already.
int pcm_start (struct pcm *pcm)
Starts a PCM.
int pcm_stop (struct pcm *pcm)
Stops a PCM.
int pcm_wait (struct pcm *pcm, int
timeout)
Waits for frames to be available for read or write
operations.
int pcm_writei (struct pcm *pcm, const
void *data, unsigned int frame_count)
Writes audio samples to PCM.
int pcm_readi (struct pcm *pcm, void
*data, unsigned int frame_count)
Reads audio samples from PCM.
int pcm_write (struct pcm *pcm, const
void *data, unsigned int count)
Writes audio samples to PCM.
int pcm_read (struct pcm *pcm, void
*data, unsigned int count)
Reads audio samples from PCM.
long pcm_get_delay (struct pcm *pcm)
Gets the delay of the PCM, in terms of frames.
All macros, structures and functions that make up the PCM interface.
Specifies that the PCM is an input. May not be bitwise AND’d with PCM_OUT. Used in pcm_open.
Specifies that the PCM will use mmap read and write methods. Used in pcm_open.
Specifies monotonic timestamps. Used in pcm_open.
Specifies no interrupt requests. May only be bitwise AND’d with PCM_MMAP. Used in pcm_open.
If used with pcm_open and pcm_params_get, it will not cause the function to block if the PCM is not available. It will also cause the functions pcm_readi and pcm_writei to exit if they would cause the caller to wait.
When set, calls to pcm_write for a playback stream will not attempt to restart the stream in the case of an underflow, but will return -EPIPE instead. After the first -EPIPE error, the stream is considered to be stopped, and a second call to pcm_write will attempt to restart the stream. Used in pcm_open.
A flag that specifies that the PCM is an output. May not be bitwise AND’d with PCM_IN. Used in pcm_open.
For inputs, this means the PCM is recording audio samples. For outputs, this means the PCM is playing audio samples.
Audio sample format of a PCM. The first letter specifiers whether the sample is signed or unsigned. The letter ’S’ means signed. The letter ’U’ means unsigned. The following number is the amount of bits that the sample occupies in memory. Following the underscore, specifiers whether the sample is big endian or little endian. The letters ’LE’ mean little endian. The letters ’BE’ mean big endian. This enumeration is used in the pcm_config structure.
Enumerator
PCM_FORMAT_S16_LE
Signed 16-bit, little endian.
PCM_FORMAT_S32_LE
Signed, 32-bit, little endian.
PCM_FORMAT_S8
Signed, 8-bit.
PCM_FORMAT_S24_LE
Signed, 24-bit (32-bit in memory), little endian.
PCM_FORMAT_S24_3LE
Signed, 24-bit, little endian.
PCM_FORMAT_S16_BE
Signed, 16-bit, big endian.
PCM_FORMAT_S24_BE
Signed, 24-bit (32-bit in memory), big endian.
PCM_FORMAT_S24_3BE
Signed, 24-bit, big endian.
PCM_FORMAT_S32_BE
Signed, 32-bit, big endian.
PCM_FORMAT_MAX
Max of the enumeration list, not an actual format.
Enumeration of a PCM’s hardware parameters. Each of these parameters is either a mask or an interval.
Enumerator
PCM_PARAM_ACCESS
A mask that represents the type of read or write method available (e.g. interleaved, mmap).
PCM_PARAM_FORMAT
A mask that represents the pcm_format available (e.g. PCM_FORMAT_S32_LE)
PCM_PARAM_SUBFORMAT
A mask that represents the subformat available.
PCM_PARAM_SAMPLE_BITS
An interval representing the range of sample bits available (e.g. 8 to 32)
PCM_PARAM_FRAME_BITS
An interval representing the range of frame bits available (e.g. 8 to 64)
PCM_PARAM_CHANNELS
An interval representing the range of channels available (e.g. 1 to 2)
PCM_PARAM_RATE
An interval representing the range of rates available (e.g. 44100 to 192000)
PCM_PARAM_PERIOD_SIZE
The number of frames in a period.
PCM_PARAM_PERIOD_BYTES
The number of bytes in a period.
PCM_PARAM_PERIODS
The number of periods for a PCM.
Determines how many frames of a PCM can fit into a number of bytes.
Parameters
pcm A PCM handle.
bytes The number of bytes.
Returns
The number of frames that may fit into bytes
Closes a PCM returned by pcm_open.
Parameters
pcm A PCM returned by pcm_open. May not be NULL.
Returns
Always returns zero.
Determines the number of bits occupied by a pcm_format.
Parameters
format A PCM format.
Returns
The number of bits associated with format
Determines how many bytes are occupied by a number of frames of a PCM.
Parameters
pcm A PCM handle.
frames The number of frames of a PCM.
Returns
The bytes occupied by frames.
Gets the buffer size of the PCM.
Parameters
pcm A PCM handle.
Returns
The buffer size of the PCM.
Gets the channel count of the PCM.
Parameters
pcm A PCM handle.
Returns
The channel count of the PCM.
Gets the PCM configuration.
Parameters
pcm A PCM handle.
Returns
The PCM configuration. This function only returns NULL if pcm is NULL.
Gets the delay of the PCM, in terms of frames.
Parameters
pcm A PCM handle.
Returns
On success, the delay of the PCM. On failure, a negative number.
Gets the error message for the last error that occured. If no error occured and this function is called, the results are undefined.
Parameters
pcm A PCM handle.
Returns
The error message of the last error that occured.
Gets the file descriptor of the PCM. Useful for extending functionality of the PCM when needed.
Parameters
pcm A PCM handle.
Returns
The file descriptor of the PCM.
Gets the format of the PCM.
Parameters
pcm A PCM handle.
Returns
The format of the PCM.
Gets the rate of the PCM. The rate is given in frames per second.
Parameters
pcm A PCM handle.
Returns
The rate of the PCM.
Checks if a PCM file has been opened without error.
Parameters
pcm A PCM handle. May be NULL.
Returns
If a PCM’s file descriptor is not valid or the pointer is NULL, it returns zero. Otherwise, the function returns one.
Links two PCMs. After this function is called, the two PCMs will prepare, start and stop in sync (at the same time). If an error occurs, the error message will be written to pcm1.
Parameters
pcm1 A PCM handle.
pcm2 Another PCM handle.
Returns
On success, zero; on failure, a negative number.
Opens a PCM.
Parameters
card The card that the
pcm belongs to. The default card is zero.
device The device that the pcm belongs to. The default
device is zero.
flags Specify characteristics and functionality about
the pcm. May be a bitwise AND of the following:
|
• |
PCM_IN |
|||
|
• |
PCM_OUT |
|||
|
• |
PCM_MMAP |
|||
|
• |
PCM_NOIRQ |
|||
|
• |
PCM_MONOTONIC |
config The hardware and software parameters to open the PCM with.
Returns
A PCM structure. If an error occurs, the pointer of bad_pcm is returned. Otherwise, it returns the pointer of PCM object. Client code should check that the PCM opened properly by calling pcm_is_ready. If pcm_is_ready returns false, check pcm_get_error for more information.
Opens a PCM by it’s name.
Parameters
name The name of the
PCM. The name is given in the format:
hw:card,device
flags Specify characteristics and functionality about
the pcm. May be a bitwise AND of the following:
|
• |
PCM_IN |
|||
|
• |
PCM_OUT |
|||
|
• |
PCM_MMAP |
|||
|
• |
PCM_NOIRQ |
|||
|
• |
PCM_MONOTONIC |
config The hardware and software parameters to open the PCM with.
Returns
A PCM structure. If an error occurs, the pointer of bad_pcm is returned. Otherwise, it returns the pointer of PCM object. Client code should check that the PCM opened properly by calling pcm_is_ready. If pcm_is_ready returns false, check pcm_get_error for more information.
Frees the hardware parameters returned by pcm_params_get.
Parameters
pcm_params Hardware parameters of a PCM. May be NULL.
Gets the hardware parameters of a PCM, without created a PCM handle.
Parameters
card The card of the
PCM. The default card is zero.
device The device of the PCM. The default device is
zero.
flags Specifies whether the PCM is an input or output.
May be one of the following:
|
• |
PCM_IN |
|||
|
• |
PCM_OUT |
Returns
On success, the hardware parameters of the PCM; on failure, NULL.
Gets a mask from a PCM’s hardware parameters.
Parameters
pcm_params A PCM’s
hardware parameters.
param The parameter to get.
Returns
If pcm_params is NULL or param is not a mask, NULL is returned. Otherwise, the mask associated with param is returned.
Prepares a PCM, if it has not been prepared already.
Parameters
pcm A PCM handle.
Returns
On success, zero; on failure, a negative number.
Reads audio samples from PCM. If the PCM has not been started, it is started in this function. This function is only valid for PCMs opened with the PCM_IN flag. This function is not valid for PCMs opened with the PCM_MMAP flag.
Parameters
pcm A PCM handle.
data The audio sample array
count The number of bytes occupied by the sample
array.
Returns
On success, this function returns zero; otherwise, a negative number.
Deprecated
Reads audio samples from PCM. If the PCM has not been started, it is started in this function. This function is only valid for PCMs opened with the PCM_IN flag.
Parameters
pcm A PCM handle.
data The audio sample array
frame_count The number of frames occupied by the sample
array. This value should not be greater than
TINYALSA_FRAMES_MAX or INT_MAX.
Returns
On success, this function returns the number of frames written; otherwise, a negative number.
Sets the PCM configuration.
Parameters
pcm A PCM handle.
config The configuration to use for the PCM. This
parameter may be NULL, in which case the default
configuration is used.
Returns
Zero on success, a negative errno value on failure.
Starts a PCM.
Parameters
pcm A PCM handle.
Returns
On success, zero; on failure, a negative number.
Stops a PCM.
Parameters
pcm A PCM handle.
Returns
On success, zero; on failure, a negative number.
Unlinks a PCM.
See also
pcm_link
Parameters
pcm A PCM handle.
Returns
On success, zero; on failure, a negative number.
Waits for frames to be available for read or write operations.
Parameters
pcm A PCM handle.
timeout The maximum amount of time to wait for, in terms
of milliseconds.
Returns
If frames became available, one is returned. If a timeout occured, zero is returned. If an error occured, a negative number is returned.
Writes audio samples to PCM. If the PCM has not been started, it is started in this function. This function is only valid for PCMs opened with the PCM_OUT flag. This function is not valid for PCMs opened with the PCM_MMAP flag.
Parameters
pcm A PCM handle.
data The audio sample array
count The number of bytes occupied by the sample
array.
Returns
On success, this function returns zero; otherwise, a negative number.
Deprecated
Writes audio samples to PCM. If the PCM has not been started, it is started in this function. This function is only valid for PCMs opened with the PCM_OUT flag.
Parameters
pcm A PCM handle.
data The audio sample array
frame_count The number of frames occupied by the sample
array. This value should not be greater than
TINYALSA_FRAMES_MAX or INT_MAX.
Returns
On success, this function returns the number of frames written; otherwise, a negative number.
Generated automatically by Doxygen for TinyALSA from the source code.