1 module pulse.sample;
2
3 import core.stdc.config;
4
5 extern (C):
6
7 /***
8 This file is part of PulseAudio.
9
10 Copyright 2004-2006 Lennart Poettering
11 Copyright 2006 Pierre Ossman <ossman@cendio.se> for Cendio AB
12
13 PulseAudio is free software; you can redistribute it and/or modify
14 it under the terms of the GNU Lesser General Public License as published
15 by the Free Software Foundation; either version 2.1 of the License,
16 or (at your option) any later version.
17
18 PulseAudio is distributed in the hope that it will be useful, but
19 WITHOUT ANY WARRANTY; without even the implied warranty of
20 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
21 General Public License for more details.
22
23 You should have received a copy of the GNU Lesser General Public License
24 along with PulseAudio; if not, see <http://www.gnu.org/licenses/>.
25 ***/
26
27 /** \page sample Sample Format Specifications
28 *
29 * \section overv_sec Overview
30 *
31 * PulseAudio is capable of handling a multitude of sample formats, rates
32 * and channels, transparently converting and mixing them as needed.
33 *
34 * \section format_sec Sample Format
35 *
36 * PulseAudio supports the following sample formats:
37 *
38 * \li PA_SAMPLE_U8 - Unsigned 8 bit integer PCM.
39 * \li PA_SAMPLE_S16LE - Signed 16 integer bit PCM, little endian.
40 * \li PA_SAMPLE_S16BE - Signed 16 integer bit PCM, big endian.
41 * \li PA_SAMPLE_FLOAT32LE - 32 bit IEEE floating point PCM, little endian.
42 * \li PA_SAMPLE_FLOAT32BE - 32 bit IEEE floating point PCM, big endian.
43 * \li PA_SAMPLE_ALAW - 8 bit a-Law.
44 * \li PA_SAMPLE_ULAW - 8 bit mu-Law.
45 * \li PA_SAMPLE_S32LE - Signed 32 bit integer PCM, little endian.
46 * \li PA_SAMPLE_S32BE - Signed 32 bit integer PCM, big endian.
47 * \li PA_SAMPLE_S24LE - Signed 24 bit integer PCM packed, little endian.
48 * \li PA_SAMPLE_S24BE - Signed 24 bit integer PCM packed, big endian.
49 * \li PA_SAMPLE_S24_32LE - Signed 24 bit integer PCM in LSB of 32 bit words, little endian.
50 * \li PA_SAMPLE_S24_32BE - Signed 24 bit integer PCM in LSB of 32 bit words, big endian.
51 *
52 * The floating point sample formats have the range from -1.0 to 1.0.
53 *
54 * The sample formats that are sensitive to endianness have convenience
55 * macros for native endian (NE), and reverse endian (RE).
56 *
57 * \section rate_sec Sample Rates
58 *
59 * PulseAudio supports any sample rate between 1 Hz and 192000 Hz. There is no
60 * point trying to exceed the sample rate of the output device though as the
61 * signal will only get downsampled, consuming CPU on the machine running the
62 * server.
63 *
64 * \section chan_sec Channels
65 *
66 * PulseAudio supports up to 32 individual channels. The order of the
67 * channels is up to the application, but they must be continuous. To map
68 * channels to speakers, see \ref channelmap.
69 *
70 * \section calc_sec Calculations
71 *
72 * The PulseAudio library contains a number of convenience functions to do
73 * calculations on sample formats:
74 *
75 * \li pa_bytes_per_second() - The number of bytes one second of audio will
76 * take given a sample format.
77 * \li pa_frame_size() - The size, in bytes, of one frame (i.e. one set of
78 * samples, one for each channel).
79 * \li pa_sample_size() - The size, in bytes, of one sample.
80 * \li pa_bytes_to_usec() - Calculate the time it would take to play a buffer
81 * of a certain size.
82 *
83 * \section util_sec Convenience Functions
84 *
85 * The library also contains a couple of other convenience functions:
86 *
87 * \li pa_sample_spec_valid() - Tests if a sample format specification is
88 * valid.
89 * \li pa_sample_spec_equal() - Tests if the sample format specifications are
90 * identical.
91 * \li pa_sample_format_to_string() - Return a textual description of a
92 * sample format.
93 * \li pa_parse_sample_format() - Parse a text string into a sample format.
94 * \li pa_sample_spec_snprint() - Create a textual description of a complete
95 * sample format specification.
96 * \li pa_bytes_snprint() - Pretty print a byte value (e.g. 2.5 MiB).
97 */
98
99 /** \file
100 * Constants and routines for sample type handling
101 *
102 * See also \subpage sample
103 */
104
105 /* On Sparc, WORDS_BIGENDIAN needs to be set if _BIG_ENDIAN is defined. */
106
107 /** Maximum number of allowed channels */
108 enum PA_CHANNELS_MAX = 32U;
109
110 /** Maximum allowed sample rate */
111 enum PA_RATE_MAX = 48000U * 8U;
112
113 /** Sample format */
114 enum pa_sample_format
115 {
116 PA_SAMPLE_U8 = 0,
117 /**< Unsigned 8 Bit PCM */
118
119 PA_SAMPLE_ALAW = 1,
120 /**< 8 Bit a-Law */
121
122 PA_SAMPLE_ULAW = 2,
123 /**< 8 Bit mu-Law */
124
125 PA_SAMPLE_S16LE = 3,
126 /**< Signed 16 Bit PCM, little endian (PC) */
127
128 PA_SAMPLE_S16BE = 4,
129 /**< Signed 16 Bit PCM, big endian */
130
131 PA_SAMPLE_FLOAT32LE = 5,
132 /**< 32 Bit IEEE floating point, little endian (PC), range -1.0 to 1.0 */
133
134 PA_SAMPLE_FLOAT32BE = 6,
135 /**< 32 Bit IEEE floating point, big endian, range -1.0 to 1.0 */
136
137 PA_SAMPLE_S32LE = 7,
138 /**< Signed 32 Bit PCM, little endian (PC) */
139
140 PA_SAMPLE_S32BE = 8,
141 /**< Signed 32 Bit PCM, big endian */
142
143 PA_SAMPLE_S24LE = 9,
144 /**< Signed 24 Bit PCM packed, little endian (PC). \since 0.9.15 */
145
146 PA_SAMPLE_S24BE = 10,
147 /**< Signed 24 Bit PCM packed, big endian. \since 0.9.15 */
148
149 PA_SAMPLE_S24_32LE = 11,
150 /**< Signed 24 Bit PCM in LSB of 32 Bit words, little endian (PC). \since 0.9.15 */
151
152 PA_SAMPLE_S24_32BE = 12,
153 /**< Signed 24 Bit PCM in LSB of 32 Bit words, big endian. \since 0.9.15 */
154
155 /* Remeber to update
156 * https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/SupportedAudioFormats/
157 * when adding new formats! */
158
159 PA_SAMPLE_MAX = 13,
160 /**< Upper limit of valid sample types */
161
162 PA_SAMPLE_INVALID = -1
163 /**< An invalid value */
164 }
165
166 alias pa_sample_format_t = pa_sample_format;
167
168 /** Signed 16 Bit PCM, native endian */
169
170 /** 32 Bit IEEE floating point, native endian */
171
172 /** Signed 32 Bit PCM, native endian */
173
174 /** Signed 24 Bit PCM packed, native endian. \since 0.9.15 */
175
176 /** Signed 24 Bit PCM in LSB of 32 Bit words, native endian. \since 0.9.15 */
177
178 /** Signed 16 Bit PCM reverse endian */
179
180 /** 32 Bit IEEE floating point, reverse endian */
181
182 /** Signed 32 Bit PCM, reverse endian */
183
184 /** Signed 24 Bit PCM, packed reverse endian. \since 0.9.15 */
185
186 /** Signed 24 Bit PCM, in LSB of 32 Bit words, reverse endian. \since 0.9.15 */
187
188 /** Signed 16 Bit PCM, native endian */
189 enum PA_SAMPLE_S16NE = pa_sample_format_t.PA_SAMPLE_S16LE;
190 /** 32 Bit IEEE floating point, native endian */
191 enum PA_SAMPLE_FLOAT32NE = pa_sample_format_t.PA_SAMPLE_FLOAT32LE;
192 /** Signed 32 Bit PCM, native endian */
193 enum PA_SAMPLE_S32NE = pa_sample_format_t.PA_SAMPLE_S32LE;
194 /** Signed 24 Bit PCM packed, native endian. \since 0.9.15 */
195 enum PA_SAMPLE_S24NE = pa_sample_format_t.PA_SAMPLE_S24LE;
196 /** Signed 24 Bit PCM in LSB of 32 Bit words, native endian. \since 0.9.15 */
197 enum PA_SAMPLE_S24_32NE = pa_sample_format_t.PA_SAMPLE_S24_32LE;
198
199 /** Signed 16 Bit PCM, reverse endian */
200 enum PA_SAMPLE_S16RE = pa_sample_format_t.PA_SAMPLE_S16BE;
201 /** 32 Bit IEEE floating point, reverse endian */
202 enum PA_SAMPLE_FLOAT32RE = pa_sample_format_t.PA_SAMPLE_FLOAT32BE;
203 /** Signed 32 Bit PCM, reverse endian */
204 enum PA_SAMPLE_S32RE = pa_sample_format_t.PA_SAMPLE_S32BE;
205 /** Signed 24 Bit PCM, packed reverse endian. \since 0.9.15 */
206 enum PA_SAMPLE_S24RE = pa_sample_format_t.PA_SAMPLE_S24BE;
207 /** Signed 24 Bit PCM, in LSB of 32 Bit words, reverse endian. \since 0.9.15 */
208 enum PA_SAMPLE_S24_32RE = pa_sample_format_t.PA_SAMPLE_S24_32BE;
209
210 /** A Shortcut for PA_SAMPLE_FLOAT32NE */
211 enum PA_SAMPLE_FLOAT32 = PA_SAMPLE_FLOAT32NE;
212
213 /** \cond fulldocs */
214 /* Allow clients to check with #ifdef for these sample formats */
215 enum PA_SAMPLE_U8 = pa_sample_format_t.PA_SAMPLE_U8;
216 enum PA_SAMPLE_ALAW = pa_sample_format_t.PA_SAMPLE_ALAW;
217 enum PA_SAMPLE_ULAW = pa_sample_format_t.PA_SAMPLE_ULAW;
218 enum PA_SAMPLE_S16LE = pa_sample_format_t.PA_SAMPLE_S16LE;
219 enum PA_SAMPLE_S16BE = pa_sample_format_t.PA_SAMPLE_S16BE;
220 enum PA_SAMPLE_FLOAT32LE = pa_sample_format_t.PA_SAMPLE_FLOAT32LE;
221 enum PA_SAMPLE_FLOAT32BE = pa_sample_format_t.PA_SAMPLE_FLOAT32BE;
222 enum PA_SAMPLE_S32LE = pa_sample_format_t.PA_SAMPLE_S32LE;
223 enum PA_SAMPLE_S32BE = pa_sample_format_t.PA_SAMPLE_S32BE;
224 enum PA_SAMPLE_S24LE = pa_sample_format_t.PA_SAMPLE_S24LE;
225 enum PA_SAMPLE_S24BE = pa_sample_format_t.PA_SAMPLE_S24BE;
226 enum PA_SAMPLE_S24_32LE = pa_sample_format_t.PA_SAMPLE_S24_32LE;
227 enum PA_SAMPLE_S24_32BE = pa_sample_format_t.PA_SAMPLE_S24_32BE;
228 /** \endcond */
229
230 /** A sample format and attribute specification */
231 struct pa_sample_spec
232 {
233 pa_sample_format_t format;
234 /**< The sample format */
235
236 uint rate;
237 /**< The sample rate. (e.g. 44100) */
238
239 ubyte channels;
240 /**< Audio channels. (1 for mono, 2 for stereo, ...) */
241 }
242
243 /** Type for usec specifications (unsigned). Always 64 bit. */
244 alias pa_usec_t = c_ulong;
245
246 /** Return the amount of bytes that constitute playback of one second of
247 * audio, with the specified sample spec. */
248 size_t pa_bytes_per_second (const(pa_sample_spec)* spec);
249
250 /** Return the size of a frame with the specific sample type */
251 size_t pa_frame_size (const(pa_sample_spec)* spec);
252
253 /** Return the size of a sample with the specific sample type */
254 size_t pa_sample_size (const(pa_sample_spec)* spec);
255
256 /** Similar to pa_sample_size() but take a sample format instead of a
257 * full sample spec. \since 0.9.15 */
258 size_t pa_sample_size_of_format (pa_sample_format_t f);
259
260 /** Calculate the time it would take to play a buffer of the specified
261 * size with the specified sample type. The return value will always
262 * be rounded down for non-integral return values. */
263 pa_usec_t pa_bytes_to_usec (ulong length, const(pa_sample_spec)* spec);
264
265 /** Calculates the size of a buffer required, for playback duration
266 * of the time specified, with the specified sample type. The
267 * return value will always be rounded down for non-integral
268 * return values. \since 0.9 */
269 size_t pa_usec_to_bytes (pa_usec_t t, const(pa_sample_spec)* spec);
270
271 /** Initialize the specified sample spec and return a pointer to
272 * it. The sample spec will have a defined state but
273 * pa_sample_spec_valid() will fail for it. \since 0.9.13 */
274 pa_sample_spec* pa_sample_spec_init (pa_sample_spec* spec);
275
276 /** Return non-zero if the given integer is a valid sample format. \since 5.0 */
277 int pa_sample_format_valid (uint format);
278
279 /** Return non-zero if the rate is within the supported range. \since 5.0 */
280 int pa_sample_rate_valid (uint rate);
281
282 /** Return non-zero if the channel count is within the supported range.
283 * \since 5.0 */
284 int pa_channels_valid (ubyte channels);
285
286 /** Return non-zero when the sample type specification is valid */
287 int pa_sample_spec_valid (const(pa_sample_spec)* spec);
288
289 /** Return non-zero when the two sample type specifications match */
290 int pa_sample_spec_equal (const(pa_sample_spec)* a, const(pa_sample_spec)* b);
291
292 /** Return a descriptive string for the specified sample format. \since 0.8 */
293 const(char)* pa_sample_format_to_string (pa_sample_format_t f);
294
295 /** Parse a sample format text. Inverse of pa_sample_format_to_string() */
296 pa_sample_format_t pa_parse_sample_format (const(char)* format);
297
298 /** Maximum required string length for
299 * pa_sample_spec_snprint(). Please note that this value can change
300 * with any release without warning and without being considered API
301 * or ABI breakage. You should not use this definition anywhere where
302 * it might become part of an ABI. */
303 enum PA_SAMPLE_SPEC_SNPRINT_MAX = 32;
304
305 /** Pretty print a sample type specification to a string. Returns \a s. */
306 char* pa_sample_spec_snprint (char* s, size_t l, const(pa_sample_spec)* spec);
307
308 /** Maximum required string length for pa_bytes_snprint(). Please note
309 * that this value can change with any release without warning and
310 * without being considered API or ABI breakage. You should not use
311 * this definition anywhere where it might become part of an
312 * ABI. \since 0.9.16 */
313 enum PA_BYTES_SNPRINT_MAX = 11;
314
315 /** Pretty print a byte size value (i.e.\ "2.5 MiB"). Returns \a s. */
316 char* pa_bytes_snprint (char* s, size_t l, uint v);
317
318 /** Returns 1 when the specified format is little endian, 0 when
319 * big endian. Returns -1 when endianness does not apply to the
320 * specified format, or endianess is unknown. \since 0.9.16 */
321 int pa_sample_format_is_le (pa_sample_format_t f);
322
323 /** Returns 1 when the specified format is big endian, 0 when
324 * little endian. Returns -1 when endianness does not apply to the
325 * specified format, or endianess is unknown. \since 0.9.16 */
326 int pa_sample_format_is_be (pa_sample_format_t f);
327
328 /** Returns 1 when the specified format is native endian, 0 when
329 * not. Returns -1 when endianness does not apply to the
330 * specified format, or endianess is unknown. \since 0.9.16 */
331 alias pa_sample_format_is_ne = pa_sample_format_is_le;
332 /** Returns 1 when the specified format is reverse endian, 0 when
333 * native. Returns -1 when endianness does not apply to the
334 * specified format, or endianess is unknown. \since 0.9.16 */
335 alias pa_sample_format_is_re = pa_sample_format_is_be;
336