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
34PA_C_DECL_BEGIN
35
36/** Represents the type of encoding used in a stream or accepted by a sink. \since 1.0 */
37typedef 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 */
91const 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 */
95pa_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 */
98typedef 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 */
108pa_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 */
111pa_format_info* pa_format_info_copy(const pa_format_info *src);
112
113/** Frees a \a pa_format_info structure. \since 1.0 */
114void pa_format_info_free(pa_format_info *f);
115
116/** Returns non-zero when the format info structure is valid. \since 1.0 */
117int 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 */
121int 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 */
130int 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 */
140char *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 */
144pa_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 */
158pa_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 */
165int 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 */
168typedef 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 */
198pa_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 */
201int 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 */
204int 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 */
208int 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 */
211int 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 */
215int 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 */
218void 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 */
223int 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 */
228int 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 */
233int 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 */
238int 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 */
241void 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 */
243void 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 */
245void 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 */
247void 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 */
249void 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 */
260void 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 */
271void 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 */
282void 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 */
293void pa_format_info_set_channel_map(pa_format_info *f, const pa_channel_map *map);
294
295PA_C_DECL_END
296
297#endif
298