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
29G_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 */
90typedef 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
149typedef 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 */
162typedef 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 */
182typedef 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 */
201typedef 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 */
217typedef 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 */
237struct _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
256GST_AUDIO_API
257GType 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
274GST_AUDIO_API
275GstAudioFormat gst_audio_format_build_integer (gboolean sign, gint endianness,
276 gint width, gint depth) G_GNUC_CONST;
277
278GST_AUDIO_API
279GstAudioFormat gst_audio_format_from_string (const gchar *format) G_GNUC_CONST;
280
281GST_AUDIO_API
282const gchar * gst_audio_format_to_string (GstAudioFormat format) G_GNUC_CONST;
283
284GST_AUDIO_API
285const GstAudioFormatInfo *
286 gst_audio_format_get_info (GstAudioFormat format) G_GNUC_CONST;
287
288GST_AUDIO_API
289void 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
371G_END_DECLS
372
373#endif /* __GST_AUDIO_FORMAT_H__ */
374