1 /* GStreamer 2 * Copyright (C) <1999> Erik Walthinsen <omega@cse.ogi.edu> 3 * Library <2001> Thomas Vander Stichele <thomas@apestaart.org> 4 * <2011> Wim Taymans <wim.taymans@gmail.com> 5 * 6 * This library is free software; you can redistribute it and/or 7 * modify it under the terms of the GNU Library General Public 8 * License as published by the Free Software Foundation; either 9 * version 2 of the License, or (at your option) any later version. 10 * 11 * This library is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 * Library General Public License for more details. 15 * 16 * You should have received a copy of the GNU Library General Public 17 * License along with this library; if not, write to the 18 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, 19 * Boston, MA 02110-1301, USA. 20 */ 21 22 #ifndef __GST_AUDIO_AUDIO_H__ 23 #include <gst/audio/audio.h> 24 #endif 25 26 #ifndef __GST_AUDIO_FORMAT_H__ 27 #define __GST_AUDIO_FORMAT_H__ 28 29 G_BEGIN_DECLS 30 31 #if G_BYTE_ORDER == G_BIG_ENDIAN 32 #define _GST_AUDIO_FORMAT_NE(fmt) GST_AUDIO_FORMAT_ ## fmt ## BE 33 #define _GST_AUDIO_FORMAT_OE(fmt) GST_AUDIO_FORMAT_ ## fmt ## LE 34 #elif G_BYTE_ORDER == G_LITTLE_ENDIAN 35 #define _GST_AUDIO_FORMAT_NE(fmt) GST_AUDIO_FORMAT_ ## fmt ## LE 36 #define _GST_AUDIO_FORMAT_OE(fmt) GST_AUDIO_FORMAT_ ## fmt ## BE 37 #endif 38 39 /** 40 * GstAudioFormat: 41 * @GST_AUDIO_FORMAT_UNKNOWN: unknown or unset audio format 42 * @GST_AUDIO_FORMAT_ENCODED: encoded audio format 43 * @GST_AUDIO_FORMAT_S8: 8 bits in 8 bits, signed 44 * @GST_AUDIO_FORMAT_U8: 8 bits in 8 bits, unsigned 45 * @GST_AUDIO_FORMAT_S16LE: 16 bits in 16 bits, signed, little endian 46 * @GST_AUDIO_FORMAT_S16BE: 16 bits in 16 bits, signed, big endian 47 * @GST_AUDIO_FORMAT_U16LE: 16 bits in 16 bits, unsigned, little endian 48 * @GST_AUDIO_FORMAT_U16BE: 16 bits in 16 bits, unsigned, big endian 49 * @GST_AUDIO_FORMAT_S24_32LE: 24 bits in 32 bits, signed, little endian 50 * @GST_AUDIO_FORMAT_S24_32BE: 24 bits in 32 bits, signed, big endian 51 * @GST_AUDIO_FORMAT_U24_32LE: 24 bits in 32 bits, unsigned, little endian 52 * @GST_AUDIO_FORMAT_U24_32BE: 24 bits in 32 bits, unsigned, big endian 53 * @GST_AUDIO_FORMAT_S32LE: 32 bits in 32 bits, signed, little endian 54 * @GST_AUDIO_FORMAT_S32BE: 32 bits in 32 bits, signed, big endian 55 * @GST_AUDIO_FORMAT_U32LE: 32 bits in 32 bits, unsigned, little endian 56 * @GST_AUDIO_FORMAT_U32BE: 32 bits in 32 bits, unsigned, big endian 57 * @GST_AUDIO_FORMAT_S24LE: 24 bits in 24 bits, signed, little endian 58 * @GST_AUDIO_FORMAT_S24BE: 24 bits in 24 bits, signed, big endian 59 * @GST_AUDIO_FORMAT_U24LE: 24 bits in 24 bits, unsigned, little endian 60 * @GST_AUDIO_FORMAT_U24BE: 24 bits in 24 bits, unsigned, big endian 61 * @GST_AUDIO_FORMAT_S20LE: 20 bits in 24 bits, signed, little endian 62 * @GST_AUDIO_FORMAT_S20BE: 20 bits in 24 bits, signed, big endian 63 * @GST_AUDIO_FORMAT_U20LE: 20 bits in 24 bits, unsigned, little endian 64 * @GST_AUDIO_FORMAT_U20BE: 20 bits in 24 bits, unsigned, big endian 65 * @GST_AUDIO_FORMAT_S18LE: 18 bits in 24 bits, signed, little endian 66 * @GST_AUDIO_FORMAT_S18BE: 18 bits in 24 bits, signed, big endian 67 * @GST_AUDIO_FORMAT_U18LE: 18 bits in 24 bits, unsigned, little endian 68 * @GST_AUDIO_FORMAT_U18BE: 18 bits in 24 bits, unsigned, big endian 69 * @GST_AUDIO_FORMAT_F32LE: 32-bit floating point samples, little endian 70 * @GST_AUDIO_FORMAT_F32BE: 32-bit floating point samples, big endian 71 * @GST_AUDIO_FORMAT_F64LE: 64-bit floating point samples, little endian 72 * @GST_AUDIO_FORMAT_F64BE: 64-bit floating point samples, big endian 73 * @GST_AUDIO_FORMAT_S16: 16 bits in 16 bits, signed, native endianness 74 * @GST_AUDIO_FORMAT_U16: 16 bits in 16 bits, unsigned, native endianness 75 * @GST_AUDIO_FORMAT_S24_32: 24 bits in 32 bits, signed, native endianness 76 * @GST_AUDIO_FORMAT_U24_32: 24 bits in 32 bits, unsigned, native endianness 77 * @GST_AUDIO_FORMAT_S32: 32 bits in 32 bits, signed, native endianness 78 * @GST_AUDIO_FORMAT_U32: 32 bits in 32 bits, unsigned, native endianness 79 * @GST_AUDIO_FORMAT_S24: 24 bits in 24 bits, signed, native endianness 80 * @GST_AUDIO_FORMAT_U24: 24 bits in 24 bits, unsigned, native endianness 81 * @GST_AUDIO_FORMAT_S20: 20 bits in 24 bits, signed, native endianness 82 * @GST_AUDIO_FORMAT_U20: 20 bits in 24 bits, unsigned, native endianness 83 * @GST_AUDIO_FORMAT_S18: 18 bits in 24 bits, signed, native endianness 84 * @GST_AUDIO_FORMAT_U18: 18 bits in 24 bits, unsigned, native endianness 85 * @GST_AUDIO_FORMAT_F32: 32-bit floating point samples, native endianness 86 * @GST_AUDIO_FORMAT_F64: 64-bit floating point samples, native endianness 87 * 88 * Enum value describing the most common audio formats. 89 */ 90 typedef enum { 91 GST_AUDIO_FORMAT_UNKNOWN, 92 GST_AUDIO_FORMAT_ENCODED, 93 /* 8 bit */ 94 GST_AUDIO_FORMAT_S8, 95 GST_AUDIO_FORMAT_U8, 96 /* 16 bit */ 97 GST_AUDIO_FORMAT_S16LE, 98 GST_AUDIO_FORMAT_S16BE, 99 GST_AUDIO_FORMAT_U16LE, 100 GST_AUDIO_FORMAT_U16BE, 101 /* 24 bit in low 3 bytes of 32 bits*/ 102 GST_AUDIO_FORMAT_S24_32LE, 103 GST_AUDIO_FORMAT_S24_32BE, 104 GST_AUDIO_FORMAT_U24_32LE, 105 GST_AUDIO_FORMAT_U24_32BE, 106 /* 32 bit */ 107 GST_AUDIO_FORMAT_S32LE, 108 GST_AUDIO_FORMAT_S32BE, 109 GST_AUDIO_FORMAT_U32LE, 110 GST_AUDIO_FORMAT_U32BE, 111 /* 24 bit in 3 bytes*/ 112 GST_AUDIO_FORMAT_S24LE, 113 GST_AUDIO_FORMAT_S24BE, 114 GST_AUDIO_FORMAT_U24LE, 115 GST_AUDIO_FORMAT_U24BE, 116 /* 20 bit in 3 bytes*/ 117 GST_AUDIO_FORMAT_S20LE, 118 GST_AUDIO_FORMAT_S20BE, 119 GST_AUDIO_FORMAT_U20LE, 120 GST_AUDIO_FORMAT_U20BE, 121 /* 18 bit in 3 bytes*/ 122 GST_AUDIO_FORMAT_S18LE, 123 GST_AUDIO_FORMAT_S18BE, 124 GST_AUDIO_FORMAT_U18LE, 125 GST_AUDIO_FORMAT_U18BE, 126 /* float */ 127 GST_AUDIO_FORMAT_F32LE, 128 GST_AUDIO_FORMAT_F32BE, 129 GST_AUDIO_FORMAT_F64LE, 130 GST_AUDIO_FORMAT_F64BE, 131 /* native endianness equivalents */ 132 GST_AUDIO_FORMAT_S16 = _GST_AUDIO_FORMAT_NE(S16), 133 GST_AUDIO_FORMAT_U16 = _GST_AUDIO_FORMAT_NE(U16), 134 GST_AUDIO_FORMAT_S24_32 = _GST_AUDIO_FORMAT_NE(S24_32), 135 GST_AUDIO_FORMAT_U24_32 = _GST_AUDIO_FORMAT_NE(U24_32), 136 GST_AUDIO_FORMAT_S32 = _GST_AUDIO_FORMAT_NE(S32), 137 GST_AUDIO_FORMAT_U32 = _GST_AUDIO_FORMAT_NE(U32), 138 GST_AUDIO_FORMAT_S24 = _GST_AUDIO_FORMAT_NE(S24), 139 GST_AUDIO_FORMAT_U24 = _GST_AUDIO_FORMAT_NE(U24), 140 GST_AUDIO_FORMAT_S20 = _GST_AUDIO_FORMAT_NE(S20), 141 GST_AUDIO_FORMAT_U20 = _GST_AUDIO_FORMAT_NE(U20), 142 GST_AUDIO_FORMAT_S18 = _GST_AUDIO_FORMAT_NE(S18), 143 GST_AUDIO_FORMAT_U18 = _GST_AUDIO_FORMAT_NE(U18), 144 GST_AUDIO_FORMAT_F32 = _GST_AUDIO_FORMAT_NE(F32), 145 GST_AUDIO_FORMAT_F64 = _GST_AUDIO_FORMAT_NE(F64) 146 } GstAudioFormat; 147 148 149 typedef struct _GstAudioFormatInfo GstAudioFormatInfo; 150 151 /** 152 * GstAudioFormatFlags: 153 * @GST_AUDIO_FORMAT_FLAG_INTEGER: integer samples 154 * @GST_AUDIO_FORMAT_FLAG_FLOAT: float samples 155 * @GST_AUDIO_FORMAT_FLAG_SIGNED: signed samples 156 * @GST_AUDIO_FORMAT_FLAG_COMPLEX: complex layout 157 * @GST_AUDIO_FORMAT_FLAG_UNPACK: the format can be used in 158 * #GstAudioFormatUnpack and #GstAudioFormatPack functions 159 * 160 * The different audio flags that a format info can have. 161 */ 162 typedef enum 163 { 164 GST_AUDIO_FORMAT_FLAG_INTEGER = (1 << 0), 165 GST_AUDIO_FORMAT_FLAG_FLOAT = (1 << 1), 166 GST_AUDIO_FORMAT_FLAG_SIGNED = (1 << 2), 167 GST_AUDIO_FORMAT_FLAG_COMPLEX = (1 << 4), 168 GST_AUDIO_FORMAT_FLAG_UNPACK = (1 << 5) 169 } GstAudioFormatFlags; 170 171 /** 172 * GstAudioPackFlags: 173 * @GST_AUDIO_PACK_FLAG_NONE: No flag 174 * @GST_AUDIO_PACK_FLAG_TRUNCATE_RANGE: When the source has a smaller depth 175 * than the target format, set the least significant bits of the target 176 * to 0. This is likely sightly faster but less accurate. When this flag 177 * is not specified, the most significant bits of the source are duplicated 178 * in the least significant bits of the destination. 179 * 180 * The different flags that can be used when packing and unpacking. 181 */ 182 typedef enum 183 { 184 GST_AUDIO_PACK_FLAG_NONE = 0, 185 GST_AUDIO_PACK_FLAG_TRUNCATE_RANGE = (1 << 0) 186 } GstAudioPackFlags; 187 188 /** 189 * GstAudioFormatUnpack: 190 * @info: a #GstAudioFormatInfo 191 * @flags: #GstAudioPackFlags 192 * @dest: (array) (element-type guint8): a destination array 193 * @data: (array) (element-type guint8): pointer to the audio data 194 * @length: the amount of samples to unpack. 195 * 196 * Unpacks @length samples from the given data of format @info. 197 * The samples will be unpacked into @dest which each channel 198 * interleaved. @dest should at least be big enough to hold @length * 199 * channels * size(unpack_format) bytes. 200 */ 201 typedef void (*GstAudioFormatUnpack) (const GstAudioFormatInfo *info, 202 GstAudioPackFlags flags, gpointer dest, 203 gconstpointer data, gint length); 204 /** 205 * GstAudioFormatPack: 206 * @info: a #GstAudioFormatInfo 207 * @flags: #GstAudioPackFlags 208 * @src: (array) (element-type guint8): a source array 209 * @data: (array) (element-type guint8): pointer to the destination 210 * data 211 * @length: the amount of samples to pack. 212 * 213 * Packs @length samples from @src to the data array in format @info. 214 * The samples from source have each channel interleaved 215 * and will be packed into @data. 216 */ 217 typedef void (*GstAudioFormatPack) (const GstAudioFormatInfo *info, 218 GstAudioPackFlags flags, gconstpointer src, 219 gpointer data, gint length); 220 221 /** 222 * GstAudioFormatInfo: 223 * @format: #GstAudioFormat 224 * @name: string representation of the format 225 * @description: user readable description of the format 226 * @flags: #GstAudioFormatFlags 227 * @endianness: the endianness 228 * @width: amount of bits used for one sample 229 * @depth: amount of valid bits in @width 230 * @silence: @width/8 bytes with 1 silent sample 231 * @unpack_format: the format of the unpacked samples 232 * @unpack_func: function to unpack samples 233 * @pack_func: function to pack samples 234 * 235 * Information for an audio format. 236 */ 237 struct _GstAudioFormatInfo { 238 /*< public >*/ 239 GstAudioFormat format; 240 const gchar *name; 241 const gchar *description; 242 GstAudioFormatFlags flags; 243 gint endianness; 244 gint width; 245 gint depth; 246 guint8 silence[8]; 247 248 GstAudioFormat unpack_format; 249 GstAudioFormatUnpack unpack_func; 250 GstAudioFormatPack pack_func; 251 252 /*< private >*/ 253 gpointer _gst_reserved[GST_PADDING]; 254 }; 255 256 GST_AUDIO_API 257 GType gst_audio_format_info_get_type (void); 258 259 #define GST_AUDIO_FORMAT_INFO_FORMAT(info) ((info)->format) 260 #define GST_AUDIO_FORMAT_INFO_NAME(info) ((info)->name) 261 #define GST_AUDIO_FORMAT_INFO_FLAGS(info) ((info)->flags) 262 263 #define GST_AUDIO_FORMAT_INFO_IS_INTEGER(info) !!((info)->flags & GST_AUDIO_FORMAT_FLAG_INTEGER) 264 #define GST_AUDIO_FORMAT_INFO_IS_FLOAT(info) !!((info)->flags & GST_AUDIO_FORMAT_FLAG_FLOAT) 265 #define GST_AUDIO_FORMAT_INFO_IS_SIGNED(info) !!((info)->flags & GST_AUDIO_FORMAT_FLAG_SIGNED) 266 267 #define GST_AUDIO_FORMAT_INFO_ENDIANNESS(info) ((info)->endianness) 268 #define GST_AUDIO_FORMAT_INFO_IS_LITTLE_ENDIAN(info) ((info)->endianness == G_LITTLE_ENDIAN) 269 #define GST_AUDIO_FORMAT_INFO_IS_BIG_ENDIAN(info) ((info)->endianness == G_BIG_ENDIAN) 270 #define GST_AUDIO_FORMAT_INFO_WIDTH(info) ((info)->width) 271 #define GST_AUDIO_FORMAT_INFO_DEPTH(info) ((info)->depth) 272 273 274 GST_AUDIO_API 275 GstAudioFormat gst_audio_format_build_integer (gboolean sign, gint endianness, 276 gint width, gint depth) G_GNUC_CONST; 277 278 GST_AUDIO_API 279 GstAudioFormat gst_audio_format_from_string (const gchar *format) G_GNUC_CONST; 280 281 GST_AUDIO_API 282 const gchar * gst_audio_format_to_string (GstAudioFormat format) G_GNUC_CONST; 283 284 GST_AUDIO_API 285 const GstAudioFormatInfo * 286 gst_audio_format_get_info (GstAudioFormat format) G_GNUC_CONST; 287 288 GST_AUDIO_API 289 void gst_audio_format_fill_silence (const GstAudioFormatInfo *info, 290 gpointer dest, gsize length); 291 292 /** 293 * GST_AUDIO_RATE_RANGE: 294 * 295 * Maximum range of allowed sample rates, for use in template caps strings. 296 */ 297 #define GST_AUDIO_RATE_RANGE "(int) [ 1, max ]" 298 /** 299 * GST_AUDIO_CHANNELS_RANGE: 300 * 301 * Maximum range of allowed channels, for use in template caps strings. 302 */ 303 #define GST_AUDIO_CHANNELS_RANGE "(int) [ 1, max ]" 304 305 /** 306 * GST_AUDIO_NE: 307 * @s: format string without endianness marker 308 * 309 * Turns audio format string @s into the format string for native endianness. 310 */ 311 /** 312 * GST_AUDIO_OE: 313 * @s: format string without endianness marker 314 * 315 * Turns audio format string @s into the format string for other endianness. 316 */ 317 #if G_BYTE_ORDER == G_LITTLE_ENDIAN 318 # define GST_AUDIO_NE(s) G_STRINGIFY(s)"LE" 319 # define GST_AUDIO_OE(s) G_STRINGIFY(s)"BE" 320 #else 321 # define GST_AUDIO_NE(s) G_STRINGIFY(s)"BE" 322 # define GST_AUDIO_OE(s) G_STRINGIFY(s)"LE" 323 #endif 324 325 /** 326 * GST_AUDIO_FORMATS_ALL: 327 * 328 * List of all audio formats, for use in template caps strings. 329 */ 330 #define GST_AUDIO_FORMATS_ALL " { S8, U8, " \ 331 "S16LE, S16BE, U16LE, U16BE, " \ 332 "S24_32LE, S24_32BE, U24_32LE, U24_32BE, " \ 333 "S32LE, S32BE, U32LE, U32BE, " \ 334 "S24LE, S24BE, U24LE, U24BE, " \ 335 "S20LE, S20BE, U20LE, U20BE, " \ 336 "S18LE, S18BE, U18LE, U18BE, " \ 337 "F32LE, F32BE, F64LE, F64BE }" 338 339 /** 340 * GST_AUDIO_CAPS_MAKE: 341 * @format: string format that describes the sample layout, as string 342 * (e.g. "S16LE", "S8", etc.) 343 * 344 * Generic caps string for audio, for use in pad templates. 345 */ 346 #define GST_AUDIO_CAPS_MAKE(format) \ 347 "audio/x-raw, " \ 348 "format = (string) " format ", " \ 349 "rate = " GST_AUDIO_RATE_RANGE ", " \ 350 "channels = " GST_AUDIO_CHANNELS_RANGE 351 352 /** 353 * GST_AUDIO_DEF_RATE: 354 * 355 * Standard sampling rate used in consumer audio. 356 */ 357 #define GST_AUDIO_DEF_RATE 44100 358 /** 359 * GST_AUDIO_DEF_CHANNELS: 360 * 361 * Standard number of channels used in consumer audio. 362 */ 363 #define GST_AUDIO_DEF_CHANNELS 2 364 /** 365 * GST_AUDIO_DEF_FORMAT: 366 * 367 * Standard format used in consumer audio. 368 */ 369 #define GST_AUDIO_DEF_FORMAT "S16LE" 370 371 G_END_DECLS 372 373 #endif /* __GST_AUDIO_FORMAT_H__ */ 374