5 This file is part of PulseAudio.
7 Copyright 2004-2006 Lennart Poettering
8 Copyright 2006 Pierre Ossman <ossman@cendio.se> for Cendio AB
10 PulseAudio is free software; you can redistribute it and/or modify
11 it under the terms of the GNU Lesser General Public License as published
12 by the Free Software Foundation; either version 2.1 of the License,
13 or (at your option) any later version.
15 PulseAudio is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public License
21 along with PulseAudio; if not, write to the Free Software
22 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
27 #include <sys/types.h>
28 #include <sys/param.h>
30 #include <pulse/gccmacro.h>
31 #include <pulse/cdecl.h>
32 #include <pulse/version.h>
34 /** \page sample Sample Format Specifications
36 * \section overv_sec Overview
38 * PulseAudio is capable of handling a multitude of sample formats, rates
39 * and channels, transparently converting and mixing them as needed.
41 * \section format_sec Sample Format
43 * PulseAudio supports the following sample formats:
45 * \li PA_SAMPLE_U8 - Unsigned 8 bit integer PCM.
46 * \li PA_SAMPLE_S16LE - Signed 16 integer bit PCM, little endian.
47 * \li PA_SAMPLE_S16BE - Signed 16 integer bit PCM, big endian.
48 * \li PA_SAMPLE_FLOAT32LE - 32 bit IEEE floating point PCM, little endian.
49 * \li PA_SAMPLE_FLOAT32BE - 32 bit IEEE floating point PCM, big endian.
50 * \li PA_SAMPLE_ALAW - 8 bit a-Law.
51 * \li PA_SAMPLE_ULAW - 8 bit mu-Law.
52 * \li PA_SAMPLE_S32LE - Signed 32 bit integer PCM, little endian.
53 * \li PA_SAMPLE_S32BE - Signed 32 bit integer PCM, big endian.
54 * \li PA_SAMPLE_S24LE - Signed 24 bit integer PCM packed, little endian.
55 * \li PA_SAMPLE_S24BE - Signed 24 bit integer PCM packed, big endian.
56 * \li PA_SAMPLE_S24_32LE - Signed 24 bit integer PCM in LSB of 32 bit words, little endian.
57 * \li PA_SAMPLE_S24_32BE - Signed 24 bit integer PCM in LSB of 32 bit words, big endian.
59 * The floating point sample formats have the range from -1.0 to 1.0.
61 * The sample formats that are sensitive to endianness have convenience
62 * macros for native endian (NE), and reverse endian (RE).
64 * \section rate_sec Sample Rates
66 * PulseAudio supports any sample rate between 1 Hz and 192000 Hz. There is no
67 * point trying to exceed the sample rate of the output device though as the
68 * signal will only get downsampled, consuming CPU on the machine running the
71 * \section chan_sec Channels
73 * PulseAudio supports up to 32 individual channels. The order of the
74 * channels is up to the application, but they must be continuous. To map
75 * channels to speakers, see \ref channelmap.
77 * \section calc_sec Calculations
79 * The PulseAudio library contains a number of convenience functions to do
80 * calculations on sample formats:
82 * \li pa_bytes_per_second() - The number of bytes one second of audio will
83 * take given a sample format.
84 * \li pa_frame_size() - The size, in bytes, of one frame (i.e. one set of
85 * samples, one for each channel).
86 * \li pa_sample_size() - The size, in bytes, of one sample.
87 * \li pa_bytes_to_usec() - Calculate the time it would take to play a buffer
90 * \section util_sec Convenience Functions
92 * The library also contains a couple of other convenience functions:
94 * \li pa_sample_spec_valid() - Tests if a sample format specification is
96 * \li pa_sample_spec_equal() - Tests if the sample format specifications are
98 * \li pa_sample_format_to_string() - Return a textual description of a
100 * \li pa_parse_sample_format() - Parse a text string into a sample format.
101 * \li pa_sample_spec_snprint() - Create a textual description of a complete
102 * sample format specification.
103 * \li pa_bytes_snprint() - Pretty print a byte value (e.g. 2.5 MiB).
107 * Constants and routines for sample type handling
109 * See also \subpage sample
114 #if !defined(WORDS_BIGENDIAN)
116 #if defined(__BYTE_ORDER)
117 #if __BYTE_ORDER == __BIG_ENDIAN
118 #define WORDS_BIGENDIAN
122 /* On Sparc, WORDS_BIGENDIAN needs to be set if _BIG_ENDIAN is defined. */
124 #define WORDS_BIGENDIAN
129 /** Maximum number of allowed channels */
130 #define PA_CHANNELS_MAX 32U
132 /** Maximum allowed sample rate */
133 #define PA_RATE_MAX (48000U*4U)
136 typedef enum pa_sample_format
{
138 /**< Unsigned 8 Bit PCM */
147 /**< Signed 16 Bit PCM, little endian (PC) */
150 /**< Signed 16 Bit PCM, big endian */
153 /**< 32 Bit IEEE floating point, little endian (PC), range -1.0 to 1.0 */
156 /**< 32 Bit IEEE floating point, big endian, range -1.0 to 1.0 */
159 /**< Signed 32 Bit PCM, little endian (PC) */
162 /**< Signed 32 Bit PCM, big endian */
165 /**< Signed 24 Bit PCM packed, little endian (PC). \since 0.9.15 */
168 /**< Signed 24 Bit PCM packed, big endian. \since 0.9.15 */
171 /**< Signed 24 Bit PCM in LSB of 32 Bit words, little endian (PC). \since 0.9.15 */
174 /**< Signed 24 Bit PCM in LSB of 32 Bit words, big endian. \since 0.9.15 */
177 /**< Upper limit of valid sample types */
179 PA_SAMPLE_INVALID
= -1
180 /**< An invalid value */
181 } pa_sample_format_t
;
183 #ifdef WORDS_BIGENDIAN
184 /** Signed 16 Bit PCM, native endian */
185 #define PA_SAMPLE_S16NE PA_SAMPLE_S16BE
186 /** 32 Bit IEEE floating point, native endian */
187 #define PA_SAMPLE_FLOAT32NE PA_SAMPLE_FLOAT32BE
188 /** Signed 32 Bit PCM, native endian */
189 #define PA_SAMPLE_S32NE PA_SAMPLE_S32BE
190 /** Signed 24 Bit PCM packed, native endian. \since 0.9.15 */
191 #define PA_SAMPLE_S24NE PA_SAMPLE_S24BE
192 /** Signed 24 Bit PCM in LSB of 32 Bit words, native endian. \since 0.9.15 */
193 #define PA_SAMPLE_S24_32NE PA_SAMPLE_S24_32BE
195 /** Signed 16 Bit PCM reverse endian */
196 #define PA_SAMPLE_S16RE PA_SAMPLE_S16LE
197 /** 32 Bit IEEE floating point, reverse endian */
198 #define PA_SAMPLE_FLOAT32RE PA_SAMPLE_FLOAT32LE
199 /** Signed 32 Bit PCM, reverse endian */
200 #define PA_SAMPLE_S32RE PA_SAMPLE_S32LE
201 /** Signed 24 Bit PCM, packed reverse endian. \since 0.9.15 */
202 #define PA_SAMPLE_S24RE PA_SAMPLE_S24LE
203 /** Signed 24 Bit PCM, in LSB of 32 Bit words, reverse endian. \since 0.9.15 */
204 #define PA_SAMPLE_S24_32RE PA_SAMPLE_S24_32LE
206 /** Signed 16 Bit PCM, native endian */
207 #define PA_SAMPLE_S16NE PA_SAMPLE_S16LE
208 /** 32 Bit IEEE floating point, native endian */
209 #define PA_SAMPLE_FLOAT32NE PA_SAMPLE_FLOAT32LE
210 /** Signed 32 Bit PCM, native endian */
211 #define PA_SAMPLE_S32NE PA_SAMPLE_S32LE
212 /** Signed 24 Bit PCM packed, native endian. \since 0.9.15 */
213 #define PA_SAMPLE_S24NE PA_SAMPLE_S24LE
214 /** Signed 24 Bit PCM in LSB of 32 Bit words, native endian. \since 0.9.15 */
215 #define PA_SAMPLE_S24_32NE PA_SAMPLE_S24_32LE
217 /** Signed 16 Bit PCM, reverse endian */
218 #define PA_SAMPLE_S16RE PA_SAMPLE_S16BE
219 /** 32 Bit IEEE floating point, reverse endian */
220 #define PA_SAMPLE_FLOAT32RE PA_SAMPLE_FLOAT32BE
221 /** Signed 32 Bit PCM, reverse endian */
222 #define PA_SAMPLE_S32RE PA_SAMPLE_S32BE
223 /** Signed 24 Bit PCM, packed reverse endian. \since 0.9.15 */
224 #define PA_SAMPLE_S24RE PA_SAMPLE_S24BE
225 /** Signed 24 Bit PCM, in LSB of 32 Bit words, reverse endian. \since 0.9.15 */
226 #define PA_SAMPLE_S24_32RE PA_SAMPLE_S24_32BE
229 /** A Shortcut for PA_SAMPLE_FLOAT32NE */
230 #define PA_SAMPLE_FLOAT32 PA_SAMPLE_FLOAT32NE
232 /** \cond fulldocs */
233 /* Allow clients to check with #ifdef for these sample formats */
234 #define PA_SAMPLE_U8 PA_SAMPLE_U8
235 #define PA_SAMPLE_ALAW PA_SAMPLE_ALAW
236 #define PA_SAMPLE_ULAW PA_SAMPLE_ULAW
237 #define PA_SAMPLE_S16LE PA_SAMPLE_S16LE
238 #define PA_SAMPLE_S16BE PA_SAMPLE_S16BE
239 #define PA_SAMPLE_FLOAT32LE PA_SAMPLE_FLOAT32LE
240 #define PA_SAMPLE_FLOAT32BE PA_SAMPLE_FLOAT32BE
241 #define PA_SAMPLE_S32LE PA_SAMPLE_S32LE
242 #define PA_SAMPLE_S32BE PA_SAMPLE_S32BE
243 #define PA_SAMPLE_S24LE PA_SAMPLE_S24LE
244 #define PA_SAMPLE_S24BE PA_SAMPLE_S24BE
245 #define PA_SAMPLE_S24_32LE PA_SAMPLE_S24_32LE
246 #define PA_SAMPLE_S24_32BE PA_SAMPLE_S24_32BE
249 /** A sample format and attribute specification */
250 typedef struct pa_sample_spec
{
251 pa_sample_format_t format
;
252 /**< The sample format */
255 /**< The sample rate. (e.g. 44100) */
258 /**< Audio channels. (1 for mono, 2 for stereo, ...) */
261 /** Type for usec specifications (unsigned). Always 64 bit. */
262 typedef uint64_t pa_usec_t
;
264 /** Return the amount of bytes playback of a second of audio with the specified sample type takes */
265 size_t pa_bytes_per_second(const pa_sample_spec
*spec
) PA_GCC_PURE
;
267 /** Return the size of a frame with the specific sample type */
268 size_t pa_frame_size(const pa_sample_spec
*spec
) PA_GCC_PURE
;
270 /** Return the size of a sample with the specific sample type */
271 size_t pa_sample_size(const pa_sample_spec
*spec
) PA_GCC_PURE
;
273 /** Similar to pa_sample_size() but take a sample format instead of a
274 * full sample spec. \since 0.9.15 */
275 size_t pa_sample_size_of_format(pa_sample_format_t f
) PA_GCC_PURE
;
277 /** Calculate the time the specified bytes take to play with the
278 * specified sample type. The return value will always be rounded
279 * down for non-integral return values. */
280 pa_usec_t
pa_bytes_to_usec(uint64_t length
, const pa_sample_spec
*spec
) PA_GCC_PURE
;
282 /** Calculates the number of bytes that are required for the specified
283 * time. The return value will always be rounded down for non-integral
284 * return values. \since 0.9 */
285 size_t pa_usec_to_bytes(pa_usec_t t
, const pa_sample_spec
*spec
) PA_GCC_PURE
;
287 /** Initialize the specified sample spec and return a pointer to
288 * it. The sample spec will have a defined state but
289 * pa_sample_spec_valid() will fail for it. \since 0.9.13 */
290 pa_sample_spec
* pa_sample_spec_init(pa_sample_spec
*spec
);
292 /** Return non-zero when the sample type specification is valid */
293 int pa_sample_spec_valid(const pa_sample_spec
*spec
) PA_GCC_PURE
;
295 /** Return non-zero when the two sample type specifications match */
296 int pa_sample_spec_equal(const pa_sample_spec
*a
, const pa_sample_spec
*b
) PA_GCC_PURE
;
298 /** Return a descriptive string for the specified sample format. \since 0.8 */
299 const char *pa_sample_format_to_string(pa_sample_format_t f
) PA_GCC_PURE
;
301 /** Parse a sample format text. Inverse of pa_sample_format_to_string() */
302 pa_sample_format_t
pa_parse_sample_format(const char *format
) PA_GCC_PURE
;
304 /** Maximum required string length for
305 * pa_sample_spec_snprint(). Please note that this value can change
306 * with any release without warning and without being considered API
307 * or ABI breakage. You should not use this definition anywhere where
308 * it might become part of an ABI. */
309 #define PA_SAMPLE_SPEC_SNPRINT_MAX 32
311 /** Pretty print a sample type specification to a string */
312 char* pa_sample_spec_snprint(char *s
, size_t l
, const pa_sample_spec
*spec
);
314 /** Maximum required string length for pa_bytes_snprint(). Please note
315 * that this value can change with any release without warning and
316 * without being considered API or ABI breakage. You should not use
317 * this definition anywhere where it might become part of an
318 * ABI. \since 0.9.16 */
319 #define PA_BYTES_SNPRINT_MAX 11
321 /** Pretty print a byte size value (i.e.\ "2.5 MiB") */
322 char* pa_bytes_snprint(char *s
, size_t l
, unsigned v
);
324 /** Return 1 when the specified format is little endian, return -1
325 * when endianness does not apply to this format. \since 0.9.16 */
326 int pa_sample_format_is_le(pa_sample_format_t f
) PA_GCC_PURE
;
328 /** Return 1 when the specified format is big endian, return -1 when
329 * endianness does not apply to this format. \since 0.9.16 */
330 int pa_sample_format_is_be(pa_sample_format_t f
) PA_GCC_PURE
;
332 #ifdef WORDS_BIGENDIAN
333 #define pa_sample_format_is_ne(f) pa_sample_format_is_be(f)
334 #define pa_sample_format_is_re(f) pa_sample_format_is_le(f)
336 /** Return 1 when the specified format is native endian, return -1
337 * when endianness does not apply to this format. \since 0.9.16 */
338 #define pa_sample_format_is_ne(f) pa_sample_format_is_le(f)
339 /** Return 1 when the specified format is reverse endian, return -1
340 * when endianness does not apply to this format. \since 0.9.16 */
341 #define pa_sample_format_is_re(f) pa_sample_format_is_be(f)