PulseAudio 16.1

Data Structures | Macros | Typedefs | Enumerations | Functions
format.h File Reference

Utility functions for handling a stream or sink format. More...

Go to the source code of this file.

## Data Structures
struct | pa_format_info
| Represents the format of data provided in a stream or processed by a sink. More...

## Macros
#define | PA_FORMAT_INFO_SNPRINT_MAX 256
| Maximum required string length for pa_format_info_snprint(). More...

## Typedefs
typedef enum pa_encoding | pa_encoding_t
| Represents the type of encoding used in a stream or accepted by a sink. More...
typedef struct pa_format_info | pa_format_info
| Represents the format of data provided in a stream or processed by a sink. More...
typedef enum pa_prop_type_t | pa_prop_type_t
| Represents the type of value type of a property on a pa_format_info. More...

## Enumerations
enum | pa_encoding { PA_ENCODING_ANY , PA_ENCODING_PCM , PA_ENCODING_AC3_IEC61937 , PA_ENCODING_EAC3_IEC61937 , PA_ENCODING_MPEG_IEC61937 , PA_ENCODING_DTS_IEC61937 , PA_ENCODING_MPEG2_AAC_IEC61937 , PA_ENCODING_TRUEHD_IEC61937 , PA_ENCODING_DTSHD_IEC61937 , PA_ENCODING_MAX , PA_ENCODING_INVALID = -1 }
| Represents the type of encoding used in a stream or accepted by a sink. More...
enum | pa_prop_type_t { PA_PROP_TYPE_INT , PA_PROP_TYPE_INT_RANGE , PA_PROP_TYPE_INT_ARRAY , PA_PROP_TYPE_STRING , PA_PROP_TYPE_STRING_ARRAY , PA_PROP_TYPE_INVALID = -1 }
| Represents the type of value type of a property on a pa_format_info. More...

## Functions
const char * | pa_encoding_to_string (pa_encoding_t e) PA_GCC_CONST
| Returns a printable string representing the given encoding type. More...
pa_encoding_t | pa_encoding_from_string (const char *encoding)
| Converts a string of the form returned by pa_encoding_to_string() back to a pa_encoding_t. More...
pa_format_info * | pa_format_info_new (void)
| Allocates a new pa_format_info structure. More...
pa_format_info * | pa_format_info_copy (const pa_format_info *src)
| Returns a new pa_format_info struct and representing the same format as src. More...
void | pa_format_info_free (pa_format_info *f)
| Frees a pa_format_info structure. More...
int | pa_format_info_valid (const pa_format_info *f)
| Returns non-zero when the format info structure is valid. More...
int | pa_format_info_is_pcm (const pa_format_info *f)
| Returns non-zero when the format info structure represents a PCM (i.e. uncompressed data) format. More...
int | pa_format_info_is_compatible (const pa_format_info *first, const pa_format_info *second)
| Returns non-zero if the format represented by first is a subset of the format represented by second. More...
char * | pa_format_info_snprint (char *s, size_t l, const pa_format_info *f)
| Make a human-readable string representing the given format. More...
pa_format_info * | pa_format_info_from_string (const char *str)
| Parse a human-readable string of the form generated by pa_format_info_snprint() into a pa_format_info structure. More...
pa_format_info * | pa_format_info_from_sample_spec (const pa_sample_spec *ss, const pa_channel_map *map)
| Utility function to take a pa_sample_spec and generate the corresponding pa_format_info. More...
int | pa_format_info_to_sample_spec (const pa_format_info *f, pa_sample_spec *ss, pa_channel_map *map)
| Utility function to generate a pa_sample_spec and pa_channel_map corresponding to a given pa_format_info. More...
pa_prop_type_t | pa_format_info_get_prop_type (const pa_format_info *f, const char *key)
| Gets the type of property key in a given pa_format_info. More...
int | pa_format_info_get_prop_int (const pa_format_info *f, const char *key, int *v)
| Gets an integer property from the given format info. More...
int | pa_format_info_get_prop_int_range (const pa_format_info *f, const char *key, int *min, int *max)
| Gets an integer range property from the given format info. More...
int | pa_format_info_get_prop_int_array (const pa_format_info *f, const char *key, int **values, int *n_values)
| Gets an integer array property from the given format info. More...
int | pa_format_info_get_prop_string (const pa_format_info *f, const char *key, char **v)
| Gets a string property from the given format info. More...
int | pa_format_info_get_prop_string_array (const pa_format_info *f, const char *key, char ***values, int *n_values)
| Gets a string array property from the given format info. More...
void | pa_format_info_free_string_array (char **values, int n_values)
| Frees a string array returned by pa_format_info_get_prop_string_array. More...
int | pa_format_info_get_sample_format (const pa_format_info *f, pa_sample_format_t *sf)
| Gets the sample format stored in the format info. More...
int | pa_format_info_get_rate (const pa_format_info *f, uint32_t *rate)
| Gets the sample rate stored in the format info. More...
int | pa_format_info_get_channels (const pa_format_info *f, uint8_t *channels)
| Gets the channel count stored in the format info. More...
int | pa_format_info_get_channel_map (const pa_format_info *f, pa_channel_map *map)
| Gets the channel map stored in the format info. More...
void | pa_format_info_set_prop_int (pa_format_info *f, const char *key, int value)
| Sets an integer property on the given format info. More...
void | pa_format_info_set_prop_int_array (pa_format_info *f, const char *key, const int *values, int n_values)
| Sets a property with a list of integer values on the given format info. More...
void | pa_format_info_set_prop_int_range (pa_format_info *f, const char *key, int min, int max)
| Sets a property which can have any value in a given integer range on the given format info. More...
void | pa_format_info_set_prop_string (pa_format_info *f, const char *key, const char *value)
| Sets a string property on the given format info. More...
void | pa_format_info_set_prop_string_array (pa_format_info *f, const char *key, const char **values, int n_values)
| Sets a property with a list of string values on the given format info. More...
void | pa_format_info_set_sample_format (pa_format_info *f, pa_sample_format_t sf)
| Convenience method to set the sample format as a property on the given format. More...
void | pa_format_info_set_rate (pa_format_info *f, int rate)
| Convenience method to set the sampling rate as a property on the given format. More...
void | pa_format_info_set_channels (pa_format_info *f, int channels)
| Convenience method to set the number of channels as a property on the given format. More...
void | pa_format_info_set_channel_map (pa_format_info *f, const pa_channel_map *map)
| Convenience method to set the channel map as a property on the given format. More...

## Detailed Description

Utility functions for handling a stream or sink format.

## Macro Definition Documentation

## ◆ PA_FORMAT_INFO_SNPRINT_MAX

#define PA_FORMAT_INFO_SNPRINT_MAX 256

Maximum required string length for pa_format_info_snprint().

Please note that this value can change with any release without warning and without being considered API or ABI breakage. You should not use this definition anywhere where it might become part of an ABI.

Since
  1.0

## Typedef Documentation

## ◆ pa_encoding_t

typedef enum pa_encoding pa_encoding_t

Represents the type of encoding used in a stream or accepted by a sink.

Since
  1.0

## ◆ pa_format_info

typedef struct pa_format_info pa_format_info

Represents the format of data provided in a stream or processed by a sink.

Since
  1.0

## ◆ pa_prop_type_t

typedef enum pa_prop_type_t pa_prop_type_t

Represents the type of value type of a property on a pa_format_info.

Since
  2.0

## Enumeration Type Documentation

## ◆ pa_encoding

enum pa_encoding

Represents the type of encoding used in a stream or accepted by a sink.

Since
  1.0

Enumerator
PA_ENCODING_ANY | Any encoding format, PCM or compressed.
PA_ENCODING_PCM | Any PCM format.
PA_ENCODING_AC3_IEC61937 | AC3 data encapsulated in IEC 61937 header/padding.
PA_ENCODING_EAC3_IEC61937 | EAC3 data encapsulated in IEC 61937 header/padding.
PA_ENCODING_MPEG_IEC61937 | MPEG-1 or MPEG-2 (Part 3, not AAC) data encapsulated in IEC 61937 header/padding.
PA_ENCODING_DTS_IEC61937 | DTS data encapsulated in IEC 61937 header/padding.
PA_ENCODING_MPEG2_AAC_IEC61937 | MPEG-2 AAC data encapsulated in IEC 61937 header/padding. Since 4.0
PA_ENCODING_TRUEHD_IEC61937 | Dolby TrueHD data encapsulated in IEC 61937 header/padding. Since 13.0
PA_ENCODING_DTSHD_IEC61937 | DTS-HD Master Audio encapsulated in IEC 61937 header/padding. Since 13.0
PA_ENCODING_MAX | Valid encoding types must be less than this value.
PA_ENCODING_INVALID | Represents an invalid encoding.

## ◆ pa_prop_type_t

enum pa_prop_type_t

Represents the type of value type of a property on a pa_format_info.

Since
  2.0

Enumerator
PA_PROP_TYPE_INT | Integer property.
PA_PROP_TYPE_INT_RANGE | Integer range property.
PA_PROP_TYPE_INT_ARRAY | Integer array property.
PA_PROP_TYPE_STRING | String property.
PA_PROP_TYPE_STRING_ARRAY | String array property.
PA_PROP_TYPE_INVALID | Represents an invalid type.

## Function Documentation

## ◆ pa_encoding_from_string()

pa_encoding_t pa_encoding_from_string | ( | const char * | encoding | ) |

Converts a string of the form returned by pa_encoding_to_string() back to a pa_encoding_t.

Since
  1.0

## ◆ pa_encoding_to_string()

const char * pa_encoding_to_string | ( | pa_encoding_t | e | ) |

Returns a printable string representing the given encoding type.

Since
  1.0

## ◆ pa_format_info_copy()

pa_format_info * pa_format_info_copy | ( | const pa_format_info * | src | ) |

Returns a new pa_format_info struct and representing the same format as src.

Since
  1.0

## ◆ pa_format_info_free()

void pa_format_info_free | ( | pa_format_info * | f | ) |

Frees a pa_format_info structure.

Since
  1.0

## ◆ pa_format_info_free_string_array()

void pa_format_info_free_string_array | ( | char ** | values,
|  | int | n_values
| ) |  |

Frees a string array returned by pa_format_info_get_prop_string_array.

Since
  2.0

## ◆ pa_format_info_from_sample_spec()

pa_format_info * pa_format_info_from_sample_spec | ( | const pa_sample_spec * | ss,
|  | const pa_channel_map * | map
| ) |  |

Utility function to take a pa_sample_spec and generate the corresponding pa_format_info.

Note that if you want the server to choose some of the stream parameters, for example the sample rate, so that they match the device parameters, then you shouldn't use this function. In order to allow the server to choose a parameter value, that parameter must be left unspecified in the pa_format_info object, and this function always specifies all parameters. An exception is the channel map: if you pass NULL for the channel map, then the channel map will be left unspecified, allowing the server to choose it.

Since
  2.0

## ◆ pa_format_info_from_string()

pa_format_info * pa_format_info_from_string | ( | const char * | str | ) |

Parse a human-readable string of the form generated by pa_format_info_snprint() into a pa_format_info structure.

Since
  1.0

## ◆ pa_format_info_get_channel_map()

int pa_format_info_get_channel_map | ( | const pa_format_info * | f,
|  | pa_channel_map * | map
| ) |  |

Gets the channel map stored in the format info.

Returns a negative error code on failure. If the channel map property is not set at all, returns a negative integer.

Since
  13.0

## ◆ pa_format_info_get_channels()

int pa_format_info_get_channels | ( | const pa_format_info * | f,
|  | uint8_t * | channels
| ) |  |

Gets the channel count stored in the format info.

Returns a negative error code on failure. If the channels property is not set at all, returns a negative integer.

Since
  13.0

## ◆ pa_format_info_get_prop_int()

int pa_format_info_get_prop_int | ( | const pa_format_info * | f,
|  | const char * | key,
|  | int * | v
| ) |  |

Gets an integer property from the given format info.

Returns 0 on success and a negative integer on failure.

Since
  2.0

## ◆ pa_format_info_get_prop_int_array()

int pa_format_info_get_prop_int_array | ( | const pa_format_info * | f,
|  | const char * | key,
|  | int ** | values,
|  | int * | n_values
| ) |  |

Gets an integer array property from the given format info.

values contains the values and n_values contains the number of elements. The caller must free values using pa_xfree. Returns 0 on success and a negative integer on failure.

Since
  2.0

## ◆ pa_format_info_get_prop_int_range()

int pa_format_info_get_prop_int_range | ( | const pa_format_info * | f,
|  | const char * | key,
|  | int * | min,
|  | int * | max
| ) |  |

Gets an integer range property from the given format info.

Returns 0 on success and a negative integer on failure.

Since
  2.0

## ◆ pa_format_info_get_prop_string()

int pa_format_info_get_prop_string | ( | const pa_format_info * | f,
|  | const char * | key,
|  | char ** | v
| ) |  |

Gets a string property from the given format info.

The caller must free the returned string using pa_xfree. Returns 0 on success and a negative integer on failure.

Since
  2.0

## ◆ pa_format_info_get_prop_string_array()

int pa_format_info_get_prop_string_array | ( | const pa_format_info * | f,
|  | const char * | key,
|  | char *** | values,
|  | int * | n_values
| ) |  |

Gets a string array property from the given format info.

values contains the values and n_values contains the number of elements. The caller must free values using pa_format_info_free_string_array. Returns 0 on success and a negative integer on failure.

Since
  2.0

## ◆ pa_format_info_get_prop_type()

pa_prop_type_t pa_format_info_get_prop_type | ( | const pa_format_info * | f,
|  | const char * | key
| ) |  |

Gets the type of property key in a given pa_format_info.

Since
  2.0

## ◆ pa_format_info_get_rate()

int pa_format_info_get_rate | ( | const pa_format_info * | f,
|  | uint32_t * | rate
| ) |  |

Gets the sample rate stored in the format info.

Returns a negative error code on failure. If the sample rate property is not set at all, returns a negative integer.

Since
  13.0

## ◆ pa_format_info_get_sample_format()

int pa_format_info_get_sample_format | ( | const pa_format_info * | f,
|  | pa_sample_format_t * | sf
| ) |  |

Gets the sample format stored in the format info.

Returns a negative error code on failure. If the sample format property is not set at all, returns a negative integer.

Since
  13.0

## ◆ pa_format_info_is_compatible()

int pa_format_info_is_compatible | ( | const pa_format_info * | first,
|  | const pa_format_info * | second
| ) |  |

Returns non-zero if the format represented by first is a subset of the format represented by second.

This means that second must have all the fields that first does, but the reverse need not be true. This is typically expected to be used to check if a stream's format is compatible with a given sink. In such a case, first would be the sink's format and second would be the stream's.

Since
  1.0

## ◆ pa_format_info_is_pcm()

int pa_format_info_is_pcm | ( | const pa_format_info * | f | ) |

Returns non-zero when the format info structure represents a PCM (i.e. uncompressed data) format.

Since
  1.0

## ◆ pa_format_info_new()

pa_format_info * pa_format_info_new | ( | void |  | ) |

Allocates a new pa_format_info structure.

Clients must initialise at least the encoding field themselves. Free with pa_format_info_free.

Since
  1.0

## ◆ pa_format_info_set_channel_map()

void pa_format_info_set_channel_map | ( | pa_format_info * | f,
|  | const pa_channel_map * | map
| ) |  |

Convenience method to set the channel map as a property on the given format.

Note for PCM: If the channel map is left unspecified in the pa_format_info object, then the server will select the stream channel map. In that case the stream channel map will most likely match the device channel map, meaning that remixing will be avoided.

Since
  1.0

## ◆ pa_format_info_set_channels()

void pa_format_info_set_channels | ( | pa_format_info * | f,
|  | int | channels
| ) |  |

Convenience method to set the number of channels as a property on the given format.

Note for PCM: If the channel count is left unspecified in the pa_format_info object, then the server will select the stream channel count. In that case the stream channel count will most likely match the device channel count, meaning that up/downmixing will be avoided.

Since
  1.0

## ◆ pa_format_info_set_prop_int()

void pa_format_info_set_prop_int | ( | pa_format_info * | f,
|  | const char * | key,
|  | int | value
| ) |  |

Sets an integer property on the given format info.

Since
  1.0

## ◆ pa_format_info_set_prop_int_array()

void pa_format_info_set_prop_int_array | ( | pa_format_info * | f,
|  | const char * | key,
|  | const int * | values,
|  | int | n_values
| ) |  |

Sets a property with a list of integer values on the given format info.

Since
  1.0

## ◆ pa_format_info_set_prop_int_range()

void pa_format_info_set_prop_int_range | ( | pa_format_info * | f,
|  | const char * | key,
|  | int | min,
|  | int | max
| ) |  |

Sets a property which can have any value in a given integer range on the given format info.

Since
  1.0

## ◆ pa_format_info_set_prop_string()

void pa_format_info_set_prop_string | ( | pa_format_info * | f,
|  | const char * | key,
|  | const char * | value
| ) |  |

Sets a string property on the given format info.

Since
  1.0

## ◆ pa_format_info_set_prop_string_array()

void pa_format_info_set_prop_string_array | ( | pa_format_info * | f,
|  | const char * | key,
|  | const char ** | values,
|  | int | n_values
| ) |  |

Sets a property with a list of string values on the given format info.

Since
  1.0

## ◆ pa_format_info_set_rate()

void pa_format_info_set_rate | ( | pa_format_info * | f,
|  | int | rate
| ) |  |

Convenience method to set the sampling rate as a property on the given format.

Note for PCM: If the sample rate is left unspecified in the pa_format_info object, then the server will select the stream sample rate. In that case the stream sample rate will most likely match the device sample rate, meaning that sample rate conversion will be avoided.

Since
  1.0

## ◆ pa_format_info_set_sample_format()

void pa_format_info_set_sample_format | ( | pa_format_info * | f,
|  | pa_sample_format_t | sf
| ) |  |

Convenience method to set the sample format as a property on the given format.

Note for PCM: If the sample format is left unspecified in the pa_format_info object, then the server will select the stream sample format. In that case the stream sample format will most likely match the device sample format, meaning that sample format conversion will be avoided.

Since
  1.0

## ◆ pa_format_info_snprint()

char * pa_format_info_snprint | ( | char * | s,
|  | size_t | l,
|  | const pa_format_info * | f
| ) |  |

Make a human-readable string representing the given format.

Returns s.

Since
  1.0

## ◆ pa_format_info_to_sample_spec()

int pa_format_info_to_sample_spec | ( | const pa_format_info * | f,
|  | pa_sample_spec * | ss,
|  | pa_channel_map * | map
| ) |  |

Utility function to generate a pa_sample_spec and pa_channel_map corresponding to a given pa_format_info.

The conversion for PCM formats is straight-forward. For non-PCM formats, if there is a fixed size-time conversion (i.e. all IEC61937-encapsulated formats), a "fake" sample spec whose size-time conversion corresponds to this format is provided and the channel map argument is ignored. For formats with variable size-time conversion, this function will fail. Returns a negative integer if conversion failed and 0 on success.

Since
  2.0

## ◆ pa_format_info_valid()

int pa_format_info_valid | ( | const pa_format_info * | f | ) |

Returns non-zero when the format info structure is valid.

Since
  1.0