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