gst-libs/gst/audio/audio.h

   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., 59 Temple Place - Suite 330,
  19  * Boston, MA 02111-1307, USA.
  20  */
  21
  22 #include <gst/gst.h>
  23
  24 #ifndef __GST_AUDIO_AUDIO_H__
  25 #define __GST_AUDIO_AUDIO_H__
  26
  27 #include <gst/audio/multichannel.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 #elif G_BYTE_ORDER == G_LITTLE_ENDIAN
  34 #define _GST_AUDIO_FORMAT_NE(fmt) GST_AUDIO_FORMAT_ ## fmt ## LE
  35 #endif
  36
  37 /**
  38  * GstAudioFormat:
  39  * @GST_AUDIO_FORMAT_UNKNOWN: unknown audio format
  40  * @GST_AUDIO_FORMAT_S8: 8 bits in 8 bits, signed
  41  * @GST_AUDIO_FORMAT_U8: 8 bits in 8 bits, unsigned
  42  * @GST_AUDIO_FORMAT_S16LE: 16 bits in 16 bits, signed, little endian
  43  * @GST_AUDIO_FORMAT_S16BE: 16 bits in 16 bits, signed, big endian
  44  * @GST_AUDIO_FORMAT_U16LE: 16 bits in 16 bits, unsigned, little endian
  45  * @GST_AUDIO_FORMAT_U16BE: 16 bits in 16 bits, unsigned, big endian
  46  * @GST_AUDIO_FORMAT_S24_32LE: 24 bits in 32 bits, signed, little endian
  47  * @GST_AUDIO_FORMAT_S24_32BE: 24 bits in 32 bits, signed, big endian
  48  * @GST_AUDIO_FORMAT_U24_32LE: 24 bits in 32 bits, unsigned, little endian
  49  * @GST_AUDIO_FORMAT_U24_32BE: 24 bits in 32 bits, unsigned, big endian
  50  * @GST_AUDIO_FORMAT_S32LE: 32 bits in 32 bits, signed, little endian
  51  * @GST_AUDIO_FORMAT_S32BE: 32 bits in 32 bits, signed, big endian
  52  * @GST_AUDIO_FORMAT_U32LE: 32 bits in 32 bits, unsigned, little endian
  53  * @GST_AUDIO_FORMAT_U32BE: 32 bits in 32 bits, unsigned, big endian
  54  * @GST_AUDIO_FORMAT_S24LE: 24 bits in 24 bits, signed, little endian
  55  * @GST_AUDIO_FORMAT_S24BE: 24 bits in 24 bits, signed, big endian
  56  * @GST_AUDIO_FORMAT_U24LE: 24 bits in 24 bits, unsigned, little endian
  57  * @GST_AUDIO_FORMAT_U24BE: 24 bits in 24 bits, unsigned, big endian
  58  * @GST_AUDIO_FORMAT_S20LE: 20 bits in 24 bits, signed, little endian
  59  * @GST_AUDIO_FORMAT_S20BE: 20 bits in 24 bits, signed, big endian
  60  * @GST_AUDIO_FORMAT_U20LE: 20 bits in 24 bits, unsigned, little endian
  61  * @GST_AUDIO_FORMAT_U20BE: 20 bits in 24 bits, unsigned, big endian
  62  * @GST_AUDIO_FORMAT_S18LE: 18 bits in 24 bits, signed, little endian
  63  * @GST_AUDIO_FORMAT_S18BE: 18 bits in 24 bits, signed, big endian
  64  * @GST_AUDIO_FORMAT_U18LE: 18 bits in 24 bits, unsigned, little endian
  65  * @GST_AUDIO_FORMAT_U18BE: 18 bits in 24 bits, unsigned, big endian
  66  * @GST_AUDIO_FORMAT_F32LE: 32-bit floating point samples, little endian
  67  * @GST_AUDIO_FORMAT_F32BE: 32-bit floating point samples, big endian
  68  * @GST_AUDIO_FORMAT_F64LE: 64-bit floating point samples, little endian
  69  * @GST_AUDIO_FORMAT_F64BE: 64-bit floating point samples, big endian
  70  * @GST_AUDIO_FORMAT_S16: 16 bits in 16 bits, signed, native endianness
  71  * @GST_AUDIO_FORMAT_U16: 16 bits in 16 bits, unsigned, native endianness
  72  * @GST_AUDIO_FORMAT_S24_32: 24 bits in 32 bits, signed, native endianness
  73  * @GST_AUDIO_FORMAT_U24_32: 24 bits in 32 bits, unsigned, native endianness
  74  * @GST_AUDIO_FORMAT_S32: 32 bits in 32 bits, signed, native endianness
  75  * @GST_AUDIO_FORMAT_U32: 32 bits in 32 bits, unsigned, native endianness
  76  * @GST_AUDIO_FORMAT_S24: 24 bits in 24 bits, signed, native endianness
  77  * @GST_AUDIO_FORMAT_U24: 24 bits in 24 bits, unsigned, native endianness
  78  * @GST_AUDIO_FORMAT_S20: 20 bits in 24 bits, signed, native endianness
  79  * @GST_AUDIO_FORMAT_U20: 20 bits in 24 bits, unsigned, native endianness
  80  * @GST_AUDIO_FORMAT_S18: 18 bits in 24 bits, signed, native endianness
  81  * @GST_AUDIO_FORMAT_U18: 18 bits in 24 bits, unsigned, native endianness
  82  * @GST_AUDIO_FORMAT_F32: 32-bit floating point samples, native endianness
  83  * @GST_AUDIO_FORMAT_F64: 64-bit floating point samples, native endianness
  84  *
  85  * Enum value describing the most common audio formats.
  86  */
  87 typedef enum {
  88   GST_AUDIO_FORMAT_UNKNOWN,
  89   /* 8 bit */
  90   GST_AUDIO_FORMAT_S8,
  91   GST_AUDIO_FORMAT_U8,
  92   /* 16 bit */
  93   GST_AUDIO_FORMAT_S16LE,
  94   GST_AUDIO_FORMAT_S16BE,
  95   GST_AUDIO_FORMAT_U16LE,
  96   GST_AUDIO_FORMAT_U16BE,
  97   /* 24 bit in low 3 bytes of 32 bits*/
  98   GST_AUDIO_FORMAT_S24_32LE,
  99   GST_AUDIO_FORMAT_S24_32BE,
 100   GST_AUDIO_FORMAT_U24_32LE,
 101   GST_AUDIO_FORMAT_U24_32BE,
 102   /* 32 bit */
 103   GST_AUDIO_FORMAT_S32LE,
 104   GST_AUDIO_FORMAT_S32BE,
 105   GST_AUDIO_FORMAT_U32LE,
 106   GST_AUDIO_FORMAT_U32BE,
 107   /* 24 bit in 3 bytes*/
 108   GST_AUDIO_FORMAT_S24LE,
 109   GST_AUDIO_FORMAT_S24BE,
 110   GST_AUDIO_FORMAT_U24LE,
 111   GST_AUDIO_FORMAT_U24BE,
 112   /* 20 bit in 3 bytes*/
 113   GST_AUDIO_FORMAT_S20LE,
 114   GST_AUDIO_FORMAT_S20BE,
 115   GST_AUDIO_FORMAT_U20LE,
 116   GST_AUDIO_FORMAT_U20BE,
 117   /* 18 bit in 3 bytes*/
 118   GST_AUDIO_FORMAT_S18LE,
 119   GST_AUDIO_FORMAT_S18BE,
 120   GST_AUDIO_FORMAT_U18LE,
 121   GST_AUDIO_FORMAT_U18BE,
 122   /* float */
 123   GST_AUDIO_FORMAT_F32LE,
 124   GST_AUDIO_FORMAT_F32BE,
 125   GST_AUDIO_FORMAT_F64LE,
 126   GST_AUDIO_FORMAT_F64BE,
 127   /* native endianness equivalents */
 128   GST_AUDIO_FORMAT_S16 = _GST_AUDIO_FORMAT_NE(S16),
 129   GST_AUDIO_FORMAT_U16 = _GST_AUDIO_FORMAT_NE(U16),
 130   GST_AUDIO_FORMAT_S24_32 = _GST_AUDIO_FORMAT_NE(S24_32),
 131   GST_AUDIO_FORMAT_U24_32 = _GST_AUDIO_FORMAT_NE(U24_32),
 132   GST_AUDIO_FORMAT_S32 = _GST_AUDIO_FORMAT_NE(S32),
 133   GST_AUDIO_FORMAT_U32 = _GST_AUDIO_FORMAT_NE(U32),
 134   GST_AUDIO_FORMAT_S24 = _GST_AUDIO_FORMAT_NE(S24),
 135   GST_AUDIO_FORMAT_U24 = _GST_AUDIO_FORMAT_NE(U24),
 136   GST_AUDIO_FORMAT_S20 = _GST_AUDIO_FORMAT_NE(S20),
 137   GST_AUDIO_FORMAT_U20 = _GST_AUDIO_FORMAT_NE(U20),
 138   GST_AUDIO_FORMAT_S18 = _GST_AUDIO_FORMAT_NE(S18),
 139   GST_AUDIO_FORMAT_U18 = _GST_AUDIO_FORMAT_NE(U18),
 140   GST_AUDIO_FORMAT_F32 = _GST_AUDIO_FORMAT_NE(F32),
 141   GST_AUDIO_FORMAT_F64 = _GST_AUDIO_FORMAT_NE(F64)
 142 } GstAudioFormat;
 143
 144 /* FIXME: need GTypes */
 145 typedef struct _GstAudioFormatInfo GstAudioFormatInfo;
 146 typedef struct _GstAudioInfo GstAudioInfo;
 147
 148 /**
 149  * GstAudioFormatFlags:
 150  * @GST_AUDIO_FORMAT_FLAG_INTEGER: integer samples
 151  * @GST_AUDIO_FORMAT_FLAG_FLOAT: float samples
 152  * @GST_AUDIO_FORMAT_FLAG_SIGNED: signed samples
 153  * @GST_AUDIO_FORMAT_FLAG_COMPLEX: complex layout
 154  *
 155  * The different audio flags that a format info can have.
 156  */
 157 typedef enum
 158 {
 159   GST_AUDIO_FORMAT_FLAG_INTEGER  = (1 << 0),
 160   GST_AUDIO_FORMAT_FLAG_FLOAT    = (1 << 1),
 161   GST_AUDIO_FORMAT_FLAG_SIGNED   = (1 << 2),
 162   GST_AUDIO_FORMAT_FLAG_COMPLEX  = (1 << 4)
 163 } GstAudioFormatFlags;
 164
 165 /**
 166  * GstAudioFormatUnpack:
 167  * @info: a #GstAudioFormatInfo
 168  * @dest: a destination array
 169  * @data: pointer to the audio data
 170  * @length: the amount of samples to unpack.
 171  *
 172  * Unpacks @length samples from the given data of format @info.
 173  * The samples will be unpacked into @dest which each channel
 174  * interleaved. @dest should at least be big enough to hold @length *
 175  * channels * size(unpack_format) bytes.
 176  */
 177 typedef void (*GstAudioFormatUnpack)         (GstAudioFormatInfo *info, gpointer dest,
 178                                               const gpointer data, gint length);
 179 /**
 180  * GstAudioFormatPack:
 181  * @info: a #GstAudioFormatInfo
 182  * @src: a source array
 183  * @data: pointer to the destination data
 184  * @length: the amount of samples to pack.
 185  *
 186  * Packs @length samples from @src to the data array in format @info.
 187  * The samples from source have each channel interleaved
 188  * and will be packed into @data.
 189  */
 190 typedef void (*GstAudioFormatPack)           (GstAudioFormatInfo *info, const gpointer src,
 191                                               gpointer data, gint length);
 192
 193 /**
 194  * GstAudioFormatInfo:
 195  * @format: #GstAudioFormat
 196  * @name: string representation of the format
 197  * @description: user readable description of the format
 198  * @flags: #GstAudioFormatFlags
 199  * @endianness: the endianness
 200  * @width: amount of bits used for one sample
 201  * @depth: amount of valid bits in @width
 202  * @silence: @width/8 bytes with 1 silent sample
 203  * @unpack_format: the format of the unpacked samples
 204  * @unpack_func: function to unpack samples
 205  * @pack_func: function to pack samples
 206  *
 207  * Information for an audio format.
 208  */
 209 struct _GstAudioFormatInfo {
 210   GstAudioFormat format;
 211   const gchar *name;
 212   const gchar *description;
 213   GstAudioFormatFlags flags;
 214   gint endianness;
 215   gint width;
 216   gint depth;
 217   guint8 silence[8];
 218
 219   GstAudioFormat unpack_format;
 220   GstAudioFormatUnpack unpack_func;
 221   GstAudioFormatPack pack_func;
 222 };
 223
 224 #define GST_AUDIO_FORMAT_INFO_FORMAT(info)           ((info)->format)
 225 #define GST_AUDIO_FORMAT_INFO_NAME(info)             ((info)->name)
 226 #define GST_AUDIO_FORMAT_INFO_FLAGS(info)            ((info)->flags)
 227
 228 #define GST_AUDIO_FORMAT_INFO_IS_INTEGER(info)       !!((info)->flags & GST_AUDIO_FORMAT_FLAG_INTEGER)
 229 #define GST_AUDIO_FORMAT_INFO_IS_FLOAT(info)         !!((info)->flags & GST_AUDIO_FORMAT_FLAG_FLOAT)
 230 #define GST_AUDIO_FORMAT_INFO_IS_SIGNED(info)        !!((info)->flags & GST_AUDIO_FORMAT_FLAG_SIGNED)
 231
 232 #define GST_AUDIO_FORMAT_INFO_ENDIANNESS(info)       ((info)->endianness)
 233 #define GST_AUDIO_FORMAT_INFO_IS_LITTLE_ENDIAN(info) ((info)->endianness == G_LITTLE_ENDIAN)
 234 #define GST_AUDIO_FORMAT_INFO_IS_BIG_ENDIAN(info)    ((info)->endianness == G_BIG_ENDIAN)
 235 #define GST_AUDIO_FORMAT_INFO_WIDTH(info)            ((info)->width)
 236 #define GST_AUDIO_FORMAT_INFO_DEPTH(info)            ((info)->depth)
 237
 238
 239 GstAudioFormat gst_audio_format_build_integer    (gboolean sign, gint endianness,
 240                                                   gint width, gint depth) G_GNUC_CONST;
 241
 242 GstAudioFormat gst_audio_format_from_string      (const gchar *format) G_GNUC_CONST;
 243 const gchar *  gst_audio_format_to_string        (GstAudioFormat format) G_GNUC_CONST;
 244
 245 const GstAudioFormatInfo *
 246                gst_audio_format_get_info         (GstAudioFormat format) G_GNUC_CONST;
 247
 248 void           gst_audio_format_fill_silence     (const GstAudioFormatInfo *info,
 249                                                   gpointer dest, gsize length);
 250 /**
 251  * GstAudioFlags:
 252  * @GST_AUDIO_FLAG_NONE: no valid flag
 253  * @GST_AUDIO_FLAG_DEFAULT_POSITIONS: position array
 254  *     contains the default layout for the number of channels.
 255  *
 256  * Extra audio flags
 257  */
 258 typedef enum {
 259   GST_AUDIO_FLAG_NONE              = 0,
 260   GST_AUDIO_FLAG_DEFAULT_POSITIONS = (1 << 0)
 261 } GstAudioFlags;
 262
 263 /**
 264  * GstAudioInfo:
 265  * @finfo: the format info of the audio
 266  * @flags: additional audio flags
 267  * @rate: the audio sample rate
 268  * @channels: the number of channels
 269  * @bpf: the number of bytes for one frame, this is the size of one
 270  *         sample * @channels
 271  * @positions: the positions for each channel
 272  *
 273  * Information describing audio properties. This information can be filled
 274  * in from GstCaps with gst_audio_info_from_caps().
 275  *
 276  * Use the provided macros to access the info in this structure.
 277  */
 278 struct _GstAudioInfo {
 279   const GstAudioFormatInfo *finfo;
 280   GstAudioFlags             flags;
 281   gint                      rate;
 282   gint                      channels;
 283   gint                      bpf;
 284   GstAudioChannelPosition   position[64];
 285 };
 286
 287 #define GST_AUDIO_INFO_FORMAT(i)             (GST_AUDIO_FORMAT_INFO_FORMAT((i)->finfo))
 288 #define GST_AUDIO_INFO_NAME(i)               (GST_AUDIO_FORMAT_INFO_NAME((i)->finfo))
 289 #define GST_AUDIO_INFO_WIDTH(i)              (GST_AUDIO_FORMAT_INFO_WIDTH((i)->finfo))
 290 #define GST_AUDIO_INFO_DEPTH(i)              (GST_AUDIO_FORMAT_INFO_DEPTH((i)->finfo))
 291 #define GST_AUDIO_INFO_BPS(info)             (GST_AUDIO_INFO_DEPTH(info) >> 3)
 292
 293 #define GST_AUDIO_INFO_IS_INTEGER(i)         (GST_AUDIO_FORMAT_INFO_IS_INTEGER((i)->finfo))
 294 #define GST_AUDIO_INFO_IS_FLOAT(i)           (GST_AUDIO_FORMAT_INFO_IS_FLOAT((i)->finfo))
 295 #define GST_AUDIO_INFO_IS_SIGNED(i)          (GST_AUDIO_FORMAT_INFO_IS_SIGNED((i)->finfo))
 296
 297 #define GST_AUDIO_INFO_ENDIANNESS(i)         (GST_AUDIO_FORMAT_INFO_ENDIANNES((i)->finfo))
 298 #define GST_AUDIO_INFO_IS_LITTLE_ENDIAN(i)   (GST_AUDIO_FORMAT_INFO_IS_LITTLE_ENDIAN((i)->finfo))
 299 #define GST_AUDIO_INFO_IS_BIG_ENDIAN(i)      (GST_AUDIO_FORMAT_INFO_IS_BIG_ENDIAN((i)->finfo))
 300
 301 #define GST_AUDIO_INFO_FLAGS(info)           ((info)->flags)
 302 #define GST_AUDIO_INFO_HAS_DEFAULT_POSITIONS(info) ((info)->flags & GST_AUDIO_FLAG_DEFAULT_POSITIONS)
 303
 304 #define GST_AUDIO_INFO_RATE(info)            ((info)->rate)
 305 #define GST_AUDIO_INFO_CHANNELS(info)        ((info)->channels)
 306 #define GST_AUDIO_INFO_BPF(info)             ((info)->bpf)
 307 #define GST_AUDIO_INFO_POSITION(info,c)      ((info)->position[c])
 308
 309 void         gst_audio_info_init        (GstAudioInfo *info);
 310 void         gst_audio_info_set_format  (GstAudioInfo *info, GstAudioFormat format,
 311                                          gint rate, gint channels);
 312
 313 gboolean     gst_audio_info_from_caps   (GstAudioInfo *info, const GstCaps *caps);
 314 GstCaps *    gst_audio_info_to_caps     (GstAudioInfo *info);
 315
 316 gboolean     gst_audio_info_convert     (GstAudioInfo * info,
 317                                          GstFormat src_fmt, gint64 src_val,
 318                                          GstFormat dest_fmt, gint64 * dest_val);
 319
 320
 321
 322 #define GST_AUDIO_RATE_RANGE "(int) [ 1, max ]"
 323 #define GST_AUDIO_CHANNELS_RANGE "(int) [ 1, max ]"
 324
 325 #if G_BYTE_ORDER == G_LITTLE_ENDIAN
 326 # define GST_AUDIO_NE(s) G_STRINGIFY(s)"LE"
 327 # define GST_AUDIO_OE(s) G_STRINGIFY(s)"BE"
 328 #else
 329 # define GST_AUDIO_NE(s) G_STRINGIFY(s)"BE"
 330 # define GST_AUDIO_OE(s) G_STRINGIFY(s)"LE"
 331 #endif
 332
 333 #define GST_AUDIO_FORMATS_ALL " { S8, U8, " \
 334     "S16LE, S16BE, U16LE, U16BE, " \
 335     "S24_32LE, S24_32BE, U24_32LE, U24_32BE, " \
 336     "S32LE, S32BE, U32LE, U32BE, " \
 337     "S24LE, S24BE, U24LE, U24BE, " \
 338     "S20LE, S20BE, U20LE, U20BE, " \
 339     "S18LE, S18BE, U18LE, U18BE, " \
 340     "F32LE, F32BE, F64LE, F64BE }"
 341
 342 /**
 343  * GST_AUDIO_CAPS_MAKE:
 344  * @format: string format that describes the pixel layout, as string
 345  *     (e.g. "S16LE", "S8", etc.)
 346  *
 347  * Generic caps string for audio, for use in pad templates.
 348  */
 349 #define GST_AUDIO_CAPS_MAKE(format)                                    \
 350     "audio/x-raw, "                                                    \
 351     "format = (string) " format ", "                                   \
 352     "rate = " GST_AUDIO_RATE_RANGE ", "                                \
 353     "channels = " GST_AUDIO_CHANNELS_RANGE
 354
 355 /**
 356  * GST_AUDIO_DEF_RATE:
 357  *
 358  * Standard sampling rate used in consumer audio.
 359  */
 360 #define GST_AUDIO_DEF_RATE 44100
 361 /**
 362  * GST_AUDIO_DEF_CHANNELS:
 363  *
 364  * Standard number of channels used in consumer audio.
 365  */
 366 #define GST_AUDIO_DEF_CHANNELS 2
 367 /**
 368  * GST_AUDIO_DEF_FORMAT:
 369  *
 370  * Standard format used in consumer audio.
 371  */
 372 #define GST_AUDIO_DEF_FORMAT "S16LE"
 373
 374 /* conversion macros */
 375 /**
 376  * GST_FRAMES_TO_CLOCK_TIME:
 377  * @frames: sample frames
 378  * @rate: sampling rate
 379  *
 380  * Calculate clocktime from sample @frames and @rate.
 381  */
 382 #define GST_FRAMES_TO_CLOCK_TIME(frames, rate) \
 383   ((GstClockTime) gst_util_uint64_scale_round (frames, GST_SECOND, rate))
 384
 385 /**
 386  * GST_CLOCK_TIME_TO_FRAMES:
 387  * @clocktime: clock time
 388  * @rate: sampling rate
 389  *
 390  * Calculate frames from @clocktime and sample @rate.
 391  */
 392 #define GST_CLOCK_TIME_TO_FRAMES(clocktime, rate) \
 393   gst_util_uint64_scale_round (clocktime, rate, GST_SECOND)
 394
 395 /*
 396  * this library defines and implements some helper functions for audio
 397  * handling
 398  */
 399
 400 GstBuffer *    gst_audio_buffer_clip     (GstBuffer *buffer, GstSegment *segment,
 401                                           gint rate, gint bpf);
 402
 403 G_END_DECLS
 404
 405 #endif /* __GST_AUDIO_AUDIO_H__ */