1 #ifndef fooformathfoo 2 #define fooformathfoo 3 4 /*** 5 This file is part of PulseAudio. 6 7 Copyright 2011 Intel Corporation 8 Copyright 2011 Collabora Multimedia 9 Copyright 2011 Arun Raghavan <arun.raghavan@collabora.co.uk> 10 11 PulseAudio is free software; you can redistribute it and/or modify 12 it under the terms of the GNU Lesser General Public License as published 13 by the Free Software Foundation; either version 2.1 of the License, 14 or (at your option) any later version. 15 16 PulseAudio is distributed in the hope that it will be useful, but 17 WITHOUT ANY WARRANTY; without even the implied warranty of 18 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 19 General Public License for more details. 20 21 You should have received a copy of the GNU Lesser General Public License 22 along with PulseAudio; if not, see <http://www.gnu.org/licenses/>. 23 ***/ 24 25 #include <pulse/cdecl.h> 26 #include <pulse/gccmacro.h> 27 #include <pulse/proplist.h> 28 #include <pulse/sample.h> 29 #include <pulse/channelmap.h> 30 31 /** \file 32 * Utility functions for handling a stream or sink format. */ 33 34 PA_C_DECL_BEGIN 35 36 /** Represents the type of encoding used in a stream or accepted by a sink. \since 1.0 */ 37 typedef enum pa_encoding { 38 PA_ENCODING_ANY, 39 /**< Any encoding format, PCM or compressed */ 40 41 PA_ENCODING_PCM, 42 /**< Any PCM format */ 43 44 PA_ENCODING_AC3_IEC61937, 45 /**< AC3 data encapsulated in IEC 61937 header/padding */ 46 47 PA_ENCODING_EAC3_IEC61937, 48 /**< EAC3 data encapsulated in IEC 61937 header/padding */ 49 50 PA_ENCODING_MPEG_IEC61937, 51 /**< MPEG-1 or MPEG-2 (Part 3, not AAC) data encapsulated in IEC 61937 header/padding */ 52 53 PA_ENCODING_DTS_IEC61937, 54 /**< DTS data encapsulated in IEC 61937 header/padding */ 55 56 PA_ENCODING_MPEG2_AAC_IEC61937, 57 /**< MPEG-2 AAC data encapsulated in IEC 61937 header/padding. \since 4.0 */ 58 59 PA_ENCODING_TRUEHD_IEC61937, 60 /**< Dolby TrueHD data encapsulated in IEC 61937 header/padding. \since 13.0 */ 61 62 PA_ENCODING_DTSHD_IEC61937, 63 /**< DTS-HD Master Audio encapsulated in IEC 61937 header/padding. \since 13.0 */ 64 65 /* Remeber to update 66 * https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/SupportedAudioFormats/ 67 * when adding new encodings! */ 68 69 PA_ENCODING_MAX, 70 /**< Valid encoding types must be less than this value */ 71 72 PA_ENCODING_INVALID = -1, 73 /**< Represents an invalid encoding */ 74 } pa_encoding_t; 75 76 /** \cond fulldocs */ 77 #define PA_ENCODING_ANY PA_ENCODING_ANY 78 #define PA_ENCODING_PCM PA_ENCODING_PCM 79 #define PA_ENCODING_AC3_IEC61937 PA_ENCODING_AC3_IEC61937 80 #define PA_ENCODING_EAC3_IEC61937 PA_ENCODING_EAC3_IEC61937 81 #define PA_ENCODING_MPEG_IEC61937 PA_ENCODING_MPEG_IEC61937 82 #define PA_ENCODING_DTS_IEC61937 PA_ENCODING_DTS_IEC61937 83 #define PA_ENCODING_MPEG2_AAC_IEC61937 PA_ENCODING_MPEG2_AAC_IEC61937 84 #define PA_ENCODING_TRUEHD_IEC61937 PA_ENCODING_TRUEHD_IEC61937 85 #define PA_ENCODING_DTSHD_IEC61937 PA_ENCODING_DTSHD_IEC61937 86 #define PA_ENCODING_MAX PA_ENCODING_MAX 87 #define PA_ENCODING_INVALID PA_ENCODING_INVALID 88 /** \endcond */ 89 90 /** Returns a printable string representing the given encoding type. \since 1.0 */ 91 const char *pa_encoding_to_string(pa_encoding_t e) PA_GCC_CONST; 92 93 /** Converts a string of the form returned by \a pa_encoding_to_string() back to 94 * a \a pa_encoding_t. \since 1.0 */ 95 pa_encoding_t pa_encoding_from_string(const char *encoding); 96 97 /** Represents the format of data provided in a stream or processed by a sink. \since 1.0 */ 98 typedef struct pa_format_info { 99 pa_encoding_t encoding; 100 /**< The encoding used for the format */ 101 102 pa_proplist *plist; 103 /**< Additional encoding-specific properties such as sample rate, bitrate, etc. */ 104 } pa_format_info; 105 106 /** Allocates a new \a pa_format_info structure. Clients must initialise at 107 * least the encoding field themselves. Free with pa_format_info_free. \since 1.0 */ 108 pa_format_info* pa_format_info_new(void); 109 110 /** Returns a new \a pa_format_info struct and representing the same format as \a src. \since 1.0 */ 111 pa_format_info* pa_format_info_copy(const pa_format_info *src); 112 113 /** Frees a \a pa_format_info structure. \since 1.0 */ 114 void pa_format_info_free(pa_format_info *f); 115 116 /** Returns non-zero when the format info structure is valid. \since 1.0 */ 117 int pa_format_info_valid(const pa_format_info *f); 118 119 /** Returns non-zero when the format info structure represents a PCM 120 * (i.e.\ uncompressed data) format. \since 1.0 */ 121 int pa_format_info_is_pcm(const pa_format_info *f); 122 123 /** Returns non-zero if the format represented by \a first is a subset of 124 * the format represented by \a second. This means that \a second must 125 * have all the fields that \a first does, but the reverse need not 126 * be true. This is typically expected to be used to check if a 127 * stream's format is compatible with a given sink. In such a case, 128 * \a first would be the sink's format and \a second would be the 129 * stream's. \since 1.0 */ 130 int pa_format_info_is_compatible(const pa_format_info *first, const pa_format_info *second); 131 132 /** Maximum required string length for 133 * pa_format_info_snprint(). Please note that this value can change 134 * with any release without warning and without being considered API 135 * or ABI breakage. You should not use this definition anywhere where 136 * it might become part of an ABI. \since 1.0 */ 137 #define PA_FORMAT_INFO_SNPRINT_MAX 256 138 139 /** Make a human-readable string representing the given format. Returns \a s. \since 1.0 */ 140 char *pa_format_info_snprint(char *s, size_t l, const pa_format_info *f); 141 142 /** Parse a human-readable string of the form generated by 143 * \a pa_format_info_snprint() into a pa_format_info structure. \since 1.0 */ 144 pa_format_info* pa_format_info_from_string(const char *str); 145 146 /** Utility function to take a \a pa_sample_spec and generate the corresponding 147 * \a pa_format_info. 148 * 149 * Note that if you want the server to choose some of the stream parameters, 150 * for example the sample rate, so that they match the device parameters, then 151 * you shouldn't use this function. In order to allow the server to choose 152 * a parameter value, that parameter must be left unspecified in the 153 * pa_format_info object, and this function always specifies all parameters. An 154 * exception is the channel map: if you pass NULL for the channel map, then the 155 * channel map will be left unspecified, allowing the server to choose it. 156 * 157 * \since 2.0 */ 158 pa_format_info* pa_format_info_from_sample_spec(const pa_sample_spec *ss, const pa_channel_map *map); 159 160 /** Utility function to generate a \a pa_sample_spec and \a pa_channel_map corresponding to a given \a pa_format_info. The 161 * conversion for PCM formats is straight-forward. For non-PCM formats, if there is a fixed size-time conversion (i.e. all 162 * IEC61937-encapsulated formats), a "fake" sample spec whose size-time conversion corresponds to this format is provided and 163 * the channel map argument is ignored. For formats with variable size-time conversion, this function will fail. Returns a 164 * negative integer if conversion failed and 0 on success. \since 2.0 */ 165 int pa_format_info_to_sample_spec(const pa_format_info *f, pa_sample_spec *ss, pa_channel_map *map); 166 167 /** Represents the type of value type of a property on a \ref pa_format_info. \since 2.0 */ 168 typedef enum pa_prop_type_t { 169 PA_PROP_TYPE_INT, 170 /**< Integer property */ 171 172 PA_PROP_TYPE_INT_RANGE, 173 /**< Integer range property */ 174 175 PA_PROP_TYPE_INT_ARRAY, 176 /**< Integer array property */ 177 178 PA_PROP_TYPE_STRING, 179 /**< String property */ 180 181 PA_PROP_TYPE_STRING_ARRAY, 182 /**< String array property */ 183 184 PA_PROP_TYPE_INVALID = -1, 185 /**< Represents an invalid type */ 186 } pa_prop_type_t; 187 188 /** \cond fulldocs */ 189 #define PA_PROP_TYPE_INT PA_PROP_TYPE_INT 190 #define PA_PROP_TYPE_INT_RANGE PA_PROP_TYPE_INT_RANGE 191 #define PA_PROP_TYPE_INT_ARRAY PA_PROP_TYPE_INT_ARRAY 192 #define PA_PROP_TYPE_STRING PA_PROP_TYPE_STRING 193 #define PA_PROP_TYPE_STRING_ARRAY PA_PROP_TYPE_STRING_ARRAY 194 #define PA_PROP_TYPE_INVALID PA_PROP_TYPE_INVALID 195 /** \endcond */ 196 197 /** Gets the type of property \a key in a given \ref pa_format_info. \since 2.0 */ 198 pa_prop_type_t pa_format_info_get_prop_type(const pa_format_info *f, const char *key); 199 200 /** Gets an integer property from the given format info. Returns 0 on success and a negative integer on failure. \since 2.0 */ 201 int pa_format_info_get_prop_int(const pa_format_info *f, const char *key, int *v); 202 /** Gets an integer range property from the given format info. Returns 0 on success and a negative integer on failure. 203 * \since 2.0 */ 204 int pa_format_info_get_prop_int_range(const pa_format_info *f, const char *key, int *min, int *max); 205 /** Gets an integer array property from the given format info. \a values contains the values and \a n_values contains the 206 * number of elements. The caller must free \a values using \ref pa_xfree. Returns 0 on success and a negative integer on 207 * failure. \since 2.0 */ 208 int pa_format_info_get_prop_int_array(const pa_format_info *f, const char *key, int **values, int *n_values); 209 /** Gets a string property from the given format info. The caller must free the returned string using \ref pa_xfree. Returns 210 * 0 on success and a negative integer on failure. \since 2.0 */ 211 int pa_format_info_get_prop_string(const pa_format_info *f, const char *key, char **v); 212 /** Gets a string array property from the given format info. \a values contains the values and \a n_values contains 213 * the number of elements. The caller must free \a values using \ref pa_format_info_free_string_array. Returns 0 on success and 214 * a negative integer on failure. \since 2.0 */ 215 int pa_format_info_get_prop_string_array(const pa_format_info *f, const char *key, char ***values, int *n_values); 216 217 /** Frees a string array returned by \ref pa_format_info_get_prop_string_array. \since 2.0 */ 218 void pa_format_info_free_string_array(char **values, int n_values); 219 220 /** Gets the sample format stored in the format info. Returns a negative error 221 * code on failure. If the sample format property is not set at all, returns a 222 * negative integer. \since 13.0 */ 223 int pa_format_info_get_sample_format(const pa_format_info *f, pa_sample_format_t *sf); 224 225 /** Gets the sample rate stored in the format info. Returns a negative error 226 * code on failure. If the sample rate property is not set at all, returns a 227 * negative integer. \since 13.0 */ 228 int pa_format_info_get_rate(const pa_format_info *f, uint32_t *rate); 229 230 /** Gets the channel count stored in the format info. Returns a negative error 231 * code on failure. If the channels property is not set at all, returns a 232 * negative integer. \since 13.0 */ 233 int pa_format_info_get_channels(const pa_format_info *f, uint8_t *channels); 234 235 /** Gets the channel map stored in the format info. Returns a negative error 236 * code on failure. If the channel map property is not 237 * set at all, returns a negative integer. \since 13.0 */ 238 int pa_format_info_get_channel_map(const pa_format_info *f, pa_channel_map *map); 239 240 /** Sets an integer property on the given format info. \since 1.0 */ 241 void pa_format_info_set_prop_int(pa_format_info *f, const char *key, int value); 242 /** Sets a property with a list of integer values on the given format info. \since 1.0 */ 243 void pa_format_info_set_prop_int_array(pa_format_info *f, const char *key, const int *values, int n_values); 244 /** Sets a property which can have any value in a given integer range on the given format info. \since 1.0 */ 245 void pa_format_info_set_prop_int_range(pa_format_info *f, const char *key, int min, int max); 246 /** Sets a string property on the given format info. \since 1.0 */ 247 void pa_format_info_set_prop_string(pa_format_info *f, const char *key, const char *value); 248 /** Sets a property with a list of string values on the given format info. \since 1.0 */ 249 void pa_format_info_set_prop_string_array(pa_format_info *f, const char *key, const char **values, int n_values); 250 251 /** Convenience method to set the sample format as a property on the given 252 * format. 253 * 254 * Note for PCM: If the sample format is left unspecified in the pa_format_info 255 * object, then the server will select the stream sample format. In that case 256 * the stream sample format will most likely match the device sample format, 257 * meaning that sample format conversion will be avoided. 258 * 259 * \since 1.0 */ 260 void pa_format_info_set_sample_format(pa_format_info *f, pa_sample_format_t sf); 261 262 /** Convenience method to set the sampling rate as a property on the given 263 * format. 264 * 265 * Note for PCM: If the sample rate is left unspecified in the pa_format_info 266 * object, then the server will select the stream sample rate. In that case the 267 * stream sample rate will most likely match the device sample rate, meaning 268 * that sample rate conversion will be avoided. 269 * 270 * \since 1.0 */ 271 void pa_format_info_set_rate(pa_format_info *f, int rate); 272 273 /** Convenience method to set the number of channels as a property on the given 274 * format. 275 * 276 * Note for PCM: If the channel count is left unspecified in the pa_format_info 277 * object, then the server will select the stream channel count. In that case 278 * the stream channel count will most likely match the device channel count, 279 * meaning that up/downmixing will be avoided. 280 * 281 * \since 1.0 */ 282 void pa_format_info_set_channels(pa_format_info *f, int channels); 283 284 /** Convenience method to set the channel map as a property on the given 285 * format. 286 * 287 * Note for PCM: If the channel map is left unspecified in the pa_format_info 288 * object, then the server will select the stream channel map. In that case the 289 * stream channel map will most likely match the device channel map, meaning 290 * that remixing will be avoided. 291 * 292 * \since 1.0 */ 293 void pa_format_info_set_channel_map(pa_format_info *f, const pa_channel_map *map); 294 295 PA_C_DECL_END 296 297 #endif 298