libtinyalsa-pcm(3)

📦 version 2.0.0, in alpine 3.24

✨ libtinyalsa-pcm(3) — PCM Interface ✨

Library Functions Manual · the libtinyalsa-pcm page, bestie 💖

🌸 NAME

libtinyalsa-pcm — PCM Interface

  • All macros, structures and functions that make up the PCM interface.

🦋 SYNOPSIS

💖 Data Structures

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

🎀 Macros

  • #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. 💀

🌈 Enumerations

enum pcm_format — Audio sample format of a PCM.

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 }

enum pcm_param — Enumeration of a PCM's hardware parameters.

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 }

🫶 Functions

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

🔥 Detailed Description

All macros, structures and functions that make up the PCM interface. That's the whole vibe, bestie. 💖

💅 Macro Definition Documentation

  • #define PCM_IN 0x10000000 — Specifies that the PCM is an input. May not be bitwise AND'd with PCM_OUT. Used in pcm_open. 🫶
  • #define PCM_MMAP 0x00000001 — Specifies that the PCM will use mmap read and write methods. Used in pcm_open.
  • #define PCM_MONOTONIC 0x00000008 — Specifies monotonic timestamps. Used in pcm_open.
  • #define PCM_NOIRQ 0x00000002 — Specifies no interrupt requests. May only be bitwise AND'd with PCM_MMAP. Used in pcm_open.
  • #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. It will also cause the functions pcm_readi and pcm_writei to exit if they would cause the caller to wait. 💅
  • #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. 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. 😭
  • #define PCM_OUT 0x00000000 — A flag that specifies that the PCM is an output. May not be bitwise AND'd with PCM_IN. Used in pcm_open. 🎀
  • #define PCM_STATE_RUNNING 0x03 — For inputs, this means the PCM is recording audio samples. For outputs, this means the PCM is playing audio samples. 🎶

🧚 Enumeration Type Documentation

🌟 enum pcm_format

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

🦋 enum pcm_param

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.

💖 Function Documentation 💖

pcm_bytes_to_frames

unsigned int pcm_bytes_to_frames (const struct pcm * pcm, unsigned int bytes)

Bestie, this is the “how many frames fit in this many bytes?” math moment. It 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.

pcm_close

int pcm_close (struct pcm * pcm)

Closes a PCM returned by pcm_open.

Parameters:

  • pcm — a PCM returned by pcm_open. May not be NULL.

Returns: always returns zero. Slay, no drama.

pcm_format_to_bits

unsigned int pcm_format_to_bits (enum pcm_format format)

Determines the number of bits occupied by a pcm_format.

Parameters:

  • format — a PCM format.

Returns: the number of bits associated with format.

pcm_frames_to_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. Byte math era 🔥

Parameters:

  • pcm — a PCM handle.
  • frames — the number of frames of a PCM.

Returns: the bytes occupied by frames.

pcm_get_buffer_size

unsigned int pcm_get_buffer_size (const struct pcm * pcm)

Gets the buffer size of the PCM.

Parameters:

  • pcm — a PCM handle.

Returns: the buffer size of the PCM.

pcm_get_channels

unsigned int pcm_get_channels (const struct pcm * pcm)

Gets the channel count of the PCM.

Parameters:

  • pcm — a PCM handle.

Returns: the channel count of the PCM.

pcm_get_config

const struct pcm_config * pcm_get_config (const struct pcm * pcm)

Gets the PCM configuration.

Parameters:

  • pcm — a PCM handle.

Returns: the PCM configuration. This function only returns NULL if pcm is NULL. iykyk 🫶

pcm_get_delay

long pcm_get_delay (struct pcm * pcm)

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.

pcm_get_error

const char * pcm_get_error (const struct pcm * pcm)

Gets the error message for the last error that occured. ⚠️ Heads up: 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.

pcm_get_file_descriptor

int pcm_get_file_descriptor (const struct pcm * pcm)

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.

pcm_get_format

enum pcm_format pcm_get_format (const struct pcm * pcm)

Gets the format of the PCM.

Parameters:

  • pcm — a PCM handle.

Returns: the format of the PCM.

pcm_get_rate

unsigned int pcm_get_rate (const struct pcm * 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.

pcm_is_ready

int pcm_is_ready (const struct pcm * 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. vibe check passed ✅

int pcm_link (struct pcm * pcm1, struct pcm * pcm2)

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.

pcm_open

struct pcm * pcm_open (unsigned int card, unsigned int device, unsigned int flags, const struct pcm_config * config)

Opens a PCM. main character moment ✨

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.

pcm_open_by_name

struct pcm * pcm_open_by_name (const char * name, unsigned int flags, const struct pcm_config * config)

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.

pcm_params_free

void pcm_params_free (struct pcm_params * pcm_params)

Frees the hardware parameters returned by pcm_params_get.

Parameters:

  • pcm_params — hardware parameters of a PCM. May be NULL.

pcm_params_get

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. no handle needed, we’re just peeking 👀

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.

pcm_params_get_mask

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.

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.

pcm_prepare

int pcm_prepare (struct pcm * pcm)

Prepares a PCM, if it has not been prepared already.

Parameters:

  • pcm — a PCM handle.

Returns: on success, zero; on failure, a negative number.

pcm_read

int pcm_read (struct pcm * pcm, void * data, unsigned int count)

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 — yes bestie, it’s deprecated.

pcm_readi

int pcm_readi (struct pcm * pcm, void * data, unsigned int frame_count)

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.

pcm_set_config

int pcm_set_config (struct pcm * pcm, const struct pcm_config * config)

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.

pcm_start

int pcm_start (struct pcm * pcm)

Starts a PCM. go go go 🏁

Parameters:

  • pcm — a PCM handle.

Returns: on success, zero; on failure, a negative number.

pcm_stop

int pcm_stop (struct pcm * pcm)

Stops a PCM.

Parameters:

  • pcm — a PCM handle.

Returns: on success, zero; on failure, a negative number.

int pcm_unlink (struct pcm * pcm)

Unlinks a PCM.

See also: pcm_link

Parameters:

  • pcm — a PCM handle.

Returns: on success, zero; on failure, a negative number.

pcm_wait

int pcm_wait (struct pcm * pcm, int timeout)

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.

pcm_write

int pcm_write (struct pcm * pcm, const void * data, unsigned int count)

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 — another deprecated icon, bestie.

pcm_writei

int pcm_writei (struct pcm * pcm, const void * data, unsigned int frame_count)

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.

👑 Author 👑

Generated automatically by Doxygen for TinyALSA from the source code.

That’s the whole function roster, bestie! 💖 This page is from TinyALSA, version 1.1.0, manual page libtinyalsa-pcm(3) — and the footer didn’t give us a date, so I’m not making one up. 🫶✨

📦 where this page comes from