2 * Copyright (C) <1999> Erik Walthinsen <omega@cse.ogi.edu>
3 * Library <2001> Thomas Vander Stichele <thomas@apestaart.org>
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Library General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Library General Public License for more details.
15 * You should have received a copy of the GNU Library General Public
16 * License along with this library; if not, write to the
17 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
18 * Boston, MA 02111-1307, USA.
23 #ifndef __GST_AUDIO_AUDIO_H__
24 #define __GST_AUDIO_AUDIO_H__
26 #include <gst/audio/multichannel.h>
30 #if G_BYTE_ORDER == G_BIG_ENDIAN
31 #define _GST_AUDIO_FORMAT_NE(fmt) GST_AUDIO_FORMAT_ ## fmt ## BE
32 #elif G_BYTE_ORDER == G_LITTLE_ENDIAN
33 #define _GST_AUDIO_FORMAT_NE(fmt) GST_AUDIO_FORMAT_ ## fmt ## LE
38 * @GST_AUDIO_FORMAT_UNKNOWN: unknown audio format
39 * @GST_AUDIO_FORMAT_S8: 8 bits in 8 bits, signed
40 * @GST_AUDIO_FORMAT_U8: 8 bits in 8 bits, unsigned
41 * @GST_AUDIO_FORMAT_S16LE: 16 bits in 16 bits, signed, little endian
42 * @GST_AUDIO_FORMAT_S16BE: 16 bits in 16 bits, signed, big endian
43 * @GST_AUDIO_FORMAT_U16LE: 16 bits in 16 bits, unsigned, little endian
44 * @GST_AUDIO_FORMAT_U16BE: 16 bits in 16 bits, unsigned, big endian
45 * @GST_AUDIO_FORMAT_S24_32LE: 24 bits in 32 bits, signed, little endian
46 * @GST_AUDIO_FORMAT_S24_32BE: 24 bits in 32 bits, signed, big endian
47 * @GST_AUDIO_FORMAT_U24_32LE: 24 bits in 32 bits, unsigned, little endian
48 * @GST_AUDIO_FORMAT_U24_32BE: 24 bits in 32 bits, unsigned, big endian
49 * @GST_AUDIO_FORMAT_S32LE: 32 bits in 32 bits, signed, little endian
50 * @GST_AUDIO_FORMAT_S32BE: 32 bits in 32 bits, signed, big endian
51 * @GST_AUDIO_FORMAT_U32LE: 32 bits in 32 bits, unsigned, little endian
52 * @GST_AUDIO_FORMAT_U32BE: 32 bits in 32 bits, unsigned, big endian
53 * @GST_AUDIO_FORMAT_S24LE: 24 bits in 24 bits, signed, little endian
54 * @GST_AUDIO_FORMAT_S24BE: 24 bits in 24 bits, signed, big endian
55 * @GST_AUDIO_FORMAT_U24LE: 24 bits in 24 bits, unsigned, little endian
56 * @GST_AUDIO_FORMAT_U24BE: 24 bits in 24 bits, unsigned, big endian
57 * @GST_AUDIO_FORMAT_S20LE: 20 bits in 24 bits, signed, little endian
58 * @GST_AUDIO_FORMAT_S20BE: 20 bits in 24 bits, signed, big endian
59 * @GST_AUDIO_FORMAT_U20LE: 20 bits in 24 bits, unsigned, little endian
60 * @GST_AUDIO_FORMAT_U20BE: 20 bits in 24 bits, unsigned, big endian
61 * @GST_AUDIO_FORMAT_S18LE: 18 bits in 24 bits, signed, little endian
62 * @GST_AUDIO_FORMAT_S18BE: 18 bits in 24 bits, signed, big endian
63 * @GST_AUDIO_FORMAT_U18LE: 18 bits in 24 bits, unsigned, little endian
64 * @GST_AUDIO_FORMAT_U18BE: 18 bits in 24 bits, unsigned, big endian
65 * @GST_AUDIO_FORMAT_F32LE: 32-bit floating point samples, little endian
66 * @GST_AUDIO_FORMAT_F32BE: 32-bit floating point samples, big endian
67 * @GST_AUDIO_FORMAT_F64LE: 64-bit floating point samples, little endian
68 * @GST_AUDIO_FORMAT_F64BE: 64-bit floating point samples, big endian
69 * @GST_AUDIO_FORMAT_S16: 16 bits in 16 bits, signed, native endianness
70 * @GST_AUDIO_FORMAT_U16: 16 bits in 16 bits, unsigned, native endianness
71 * @GST_AUDIO_FORMAT_S24_32: 24 bits in 32 bits, signed, native endianness
72 * @GST_AUDIO_FORMAT_U24_32: 24 bits in 32 bits, unsigned, native endianness
73 * @GST_AUDIO_FORMAT_S32: 32 bits in 32 bits, signed, native endianness
74 * @GST_AUDIO_FORMAT_U32: 32 bits in 32 bits, unsigned, native endianness
75 * @GST_AUDIO_FORMAT_S24: 24 bits in 24 bits, signed, native endianness
76 * @GST_AUDIO_FORMAT_U24: 24 bits in 24 bits, unsigned, native endianness
77 * @GST_AUDIO_FORMAT_S20: 20 bits in 24 bits, signed, native endianness
78 * @GST_AUDIO_FORMAT_U20: 20 bits in 24 bits, unsigned, native endianness
79 * @GST_AUDIO_FORMAT_S18: 18 bits in 24 bits, signed, native endianness
80 * @GST_AUDIO_FORMAT_U18: 18 bits in 24 bits, unsigned, native endianness
81 * @GST_AUDIO_FORMAT_F32: 32-bit floating point samples, native endianness
82 * @GST_AUDIO_FORMAT_F64: 64-bit floating point samples, native endianness
84 * Enum value describing the most common audio formats.
89 GST_AUDIO_FORMAT_UNKNOWN,
94 GST_AUDIO_FORMAT_S16LE,
95 GST_AUDIO_FORMAT_S16BE,
96 GST_AUDIO_FORMAT_U16LE,
97 GST_AUDIO_FORMAT_U16BE,
98 /* 24 bit in low 3 bytes of 32 bits*/
99 GST_AUDIO_FORMAT_S24_32LE,
100 GST_AUDIO_FORMAT_S24_32BE,
101 GST_AUDIO_FORMAT_U24_32LE,
102 GST_AUDIO_FORMAT_U24_32BE,
104 GST_AUDIO_FORMAT_S32LE,
105 GST_AUDIO_FORMAT_S32BE,
106 GST_AUDIO_FORMAT_U32LE,
107 GST_AUDIO_FORMAT_U32BE,
108 /* 24 bit in 3 bytes*/
109 GST_AUDIO_FORMAT_S24LE,
110 GST_AUDIO_FORMAT_S24BE,
111 GST_AUDIO_FORMAT_U24LE,
112 GST_AUDIO_FORMAT_U24BE,
113 /* 20 bit in 3 bytes*/
114 GST_AUDIO_FORMAT_S20LE,
115 GST_AUDIO_FORMAT_S20BE,
116 GST_AUDIO_FORMAT_U20LE,
117 GST_AUDIO_FORMAT_U20BE,
118 /* 18 bit in 3 bytes*/
119 GST_AUDIO_FORMAT_S18LE,
120 GST_AUDIO_FORMAT_S18BE,
121 GST_AUDIO_FORMAT_U18LE,
122 GST_AUDIO_FORMAT_U18BE,
124 GST_AUDIO_FORMAT_F32LE,
125 GST_AUDIO_FORMAT_F32BE,
126 GST_AUDIO_FORMAT_F64LE,
127 GST_AUDIO_FORMAT_F64BE,
128 /* native endianness equivalents */
129 GST_AUDIO_FORMAT_S16 = _GST_AUDIO_FORMAT_NE(S16),
130 GST_AUDIO_FORMAT_U16 = _GST_AUDIO_FORMAT_NE(U16),
131 GST_AUDIO_FORMAT_S24_32 = _GST_AUDIO_FORMAT_NE(S24_32),
132 GST_AUDIO_FORMAT_U24_32 = _GST_AUDIO_FORMAT_NE(U24_32),
133 GST_AUDIO_FORMAT_S32 = _GST_AUDIO_FORMAT_NE(S32),
134 GST_AUDIO_FORMAT_U32 = _GST_AUDIO_FORMAT_NE(U32),
135 GST_AUDIO_FORMAT_S24 = _GST_AUDIO_FORMAT_NE(S24),
136 GST_AUDIO_FORMAT_U24 = _GST_AUDIO_FORMAT_NE(U24),
137 GST_AUDIO_FORMAT_S20 = _GST_AUDIO_FORMAT_NE(S20),
138 GST_AUDIO_FORMAT_U20 = _GST_AUDIO_FORMAT_NE(U20),
139 GST_AUDIO_FORMAT_S18 = _GST_AUDIO_FORMAT_NE(S18),
140 GST_AUDIO_FORMAT_U18 = _GST_AUDIO_FORMAT_NE(U18),
141 GST_AUDIO_FORMAT_F32 = _GST_AUDIO_FORMAT_NE(F32),
142 GST_AUDIO_FORMAT_F64 = _GST_AUDIO_FORMAT_NE(F64)
145 /* FIXME: need GTypes */
146 typedef struct _GstAudioFormatInfo GstAudioFormatInfo;
147 typedef struct _GstAudioInfo GstAudioInfo;
150 * GstAudioFormatFlags:
151 * @GST_AUDIO_FORMAT_FLAG_INTEGER: integer samples
152 * @GST_AUDIO_FORMAT_FLAG_FLOAT: float samples
153 * @GST_AUDIO_FORMAT_FLAG_SIGNED: signed samples
154 * @GST_AUDIO_FORMAT_FLAG_COMPLEX: complex layout
156 * The different audio flags that a format info can have.
162 GST_AUDIO_FORMAT_FLAG_INTEGER = (1 << 0),
163 GST_AUDIO_FORMAT_FLAG_FLOAT = (1 << 1),
164 GST_AUDIO_FORMAT_FLAG_SIGNED = (1 << 2),
165 GST_AUDIO_FORMAT_FLAG_COMPLEX = (1 << 4)
166 } GstAudioFormatFlags;
169 * GstAudioFormatInfo:
170 * @format: #GstAudioFormat
171 * @name: string representation of the format
172 * @flags: #GstAudioFormatFlags
173 * @endianness: the endianness
174 * @width: amount of bits used for one sample
175 * @depth: amount of valid bits in @width
176 * @silence: @width/8 bytes with 1 silent sample
178 * Information for an audio format.
182 struct _GstAudioFormatInfo {
183 GstAudioFormat format;
185 GstAudioFormatFlags flags;
192 gpointer padding_p[4];
195 #define GST_AUDIO_FORMAT_INFO_FORMAT(info) ((info)->format)
196 #define GST_AUDIO_FORMAT_INFO_NAME(info) ((info)->name)
197 #define GST_AUDIO_FORMAT_INFO_FLAGS(info) ((info)->flags)
199 #define GST_AUDIO_FORMAT_INFO_IS_INTEGER(info) !!((info)->flags & GST_AUDIO_FORMAT_FLAG_INTEGER)
200 #define GST_AUDIO_FORMAT_INFO_IS_FLOAT(info) !!((info)->flags & GST_AUDIO_FORMAT_FLAG_FLOAT)
201 #define GST_AUDIO_FORMAT_INFO_IS_SIGNED(info) !!((info)->flags & GST_AUDIO_FORMAT_FLAG_SIGNED)
203 #define GST_AUDIO_FORMAT_INFO_ENDIANNESS(info) ((info)->endianness)
204 #define GST_AUDIO_FORMAT_INFO_IS_LITTLE_ENDIAN(info) ((info)->endianness == G_LITTLE_ENDIAN)
205 #define GST_AUDIO_FORMAT_INFO_IS_BIG_ENDIAN(info) ((info)->endianness == G_BIG_ENDIAN)
206 #define GST_AUDIO_FORMAT_INFO_WIDTH(info) ((info)->width)
207 #define GST_AUDIO_FORMAT_INFO_DEPTH(info) ((info)->depth)
209 const GstAudioFormatInfo * gst_audio_format_get_info (GstAudioFormat format) G_GNUC_CONST;
213 * @GST_AUDIO_FLAG_NONE: no valid flag
214 * @GST_AUDIO_FLAG_DEFAULT_POSITIONS: unpositioned audio layout, position array
215 * contains the default layout (meaning that the channel layout was not
216 * explicitly specified in the caps)
223 GST_AUDIO_FLAG_NONE = 0,
224 GST_AUDIO_FLAG_DEFAULT_POSITIONS = (1 << 0)
229 * @finfo: the format info of the audio
230 * @flags: additional audio flags
231 * @rate: the audio sample rate
232 * @channels: the number of channels
233 * @bpf: the number of bytes for one frame, this is the size of one
235 * @position: the position for each channel (assume all NONE for >64 channels)
237 * Information describing audio properties. This information can be filled
238 * in from GstCaps with gst_audio_info_from_caps().
240 * Use the provided macros to access the info in this structure.
244 struct _GstAudioInfo {
245 const GstAudioFormatInfo *finfo;
250 GstAudioChannelPosition position[64];
253 #define GST_AUDIO_INFO_IS_VALID(i) ((i)->finfo != NULL && (i)->rate > 0 && (i)->channels > 0 && (i)->bpf > 0)
255 #define GST_AUDIO_INFO_FORMAT(i) (GST_AUDIO_FORMAT_INFO_FORMAT((i)->finfo))
256 #define GST_AUDIO_INFO_NAME(i) (GST_AUDIO_FORMAT_INFO_NAME((i)->finfo))
257 #define GST_AUDIO_INFO_WIDTH(i) (GST_AUDIO_FORMAT_INFO_WIDTH((i)->finfo))
258 #define GST_AUDIO_INFO_DEPTH(i) (GST_AUDIO_FORMAT_INFO_DEPTH((i)->finfo))
259 #define GST_AUDIO_INFO_BPS(info) (GST_AUDIO_INFO_DEPTH(info) >> 3)
261 #define GST_AUDIO_INFO_IS_INTEGER(i) (GST_AUDIO_FORMAT_INFO_IS_INTEGER((i)->finfo))
262 #define GST_AUDIO_INFO_IS_FLOAT(i) (GST_AUDIO_FORMAT_INFO_IS_FLOAT((i)->finfo))
263 #define GST_AUDIO_INFO_IS_SIGNED(i) (GST_AUDIO_FORMAT_INFO_IS_SIGNED((i)->finfo))
265 #define GST_AUDIO_INFO_ENDIANNESS(i) (GST_AUDIO_FORMAT_INFO_ENDIANNES((i)->finfo))
266 #define GST_AUDIO_INFO_IS_LITTLE_ENDIAN(i) (GST_AUDIO_FORMAT_INFO_IS_LITTLE_ENDIAN((i)->finfo))
267 #define GST_AUDIO_INFO_IS_BIG_ENDIAN(i) (GST_AUDIO_FORMAT_INFO_IS_BIG_ENDIAN((i)->finfo))
269 #define GST_AUDIO_INFO_FLAGS(info) ((info)->flags)
270 #define GST_AUDIO_INFO_HAS_DEFAULT_POSITIONS(info) ((info)->flags & GST_AUDIO_FLAG_DEFAULT_POSITIONS)
272 #define GST_AUDIO_INFO_RATE(info) ((info)->rate)
273 #define GST_AUDIO_INFO_CHANNELS(info) ((info)->channels)
274 #define GST_AUDIO_INFO_BPF(info) ((info)->bpf)
275 #define GST_AUDIO_INFO_POSITION(info,c) ((info)->position[c])
277 void gst_audio_info_init (GstAudioInfo * info);
278 void gst_audio_info_clear (GstAudioInfo * info);
280 GstAudioInfo * gst_audio_info_copy (GstAudioInfo * info);
281 void gst_audio_info_free (GstAudioInfo * info);
283 gboolean gst_audio_info_from_caps (GstAudioInfo * info, const GstCaps * caps);
284 GstCaps * gst_audio_info_to_caps (GstAudioInfo * info);
286 gboolean gst_audio_info_convert (GstAudioInfo * info,
287 GstFormat src_fmt, gint64 src_val,
288 GstFormat dest_fmt, gint64 * dest_val);
290 /* For people that are looking at this source: the purpose of these defines is
291 * to make GstCaps a bit easier, in that you don't have to know all of the
292 * properties that need to be defined. you can just use these macros. currently
293 * (8/01) the only plugins that use these are the passthrough, speed, volume,
294 * adder, and [de]interleave plugins. These are for convenience only, and do not
295 * specify the 'limits' of GStreamer. you might also use these definitions as a
296 * base for making your own caps, if need be.
298 * For example, to make a source pad that can output streams of either mono
299 * float or any channel int:
301 * template = gst_pad_template_new
302 * ("sink", GST_PAD_SINK, GST_PAD_ALWAYS,
303 * gst_caps_append(gst_caps_new ("sink_int", "audio/x-raw-int",
304 * GST_AUDIO_INT_PAD_TEMPLATE_PROPS),
305 * gst_caps_new ("sink_float", "audio/x-raw-float",
306 * GST_AUDIO_FLOAT_PAD_TEMPLATE_PROPS)),
309 * sinkpad = gst_pad_new_from_template(template, "sink");
311 * Andy Wingo, 18 August 2001
312 * Thomas, 6 September 2002 */
314 /* conversion macros */
316 * GST_FRAMES_TO_CLOCK_TIME:
317 * @frames: sample frames
318 * @rate: sampling rate
320 * Calculate clocktime from sample @frames and @rate.
322 #define GST_FRAMES_TO_CLOCK_TIME(frames, rate) \
323 ((GstClockTime) gst_util_uint64_scale_round (frames, GST_SECOND, rate))
326 * GST_CLOCK_TIME_TO_FRAMES:
327 * @clocktime: clock time
328 * @rate: sampling rate
330 * Calculate frames from @clocktime and sample @rate.
332 #define GST_CLOCK_TIME_TO_FRAMES(clocktime, rate) \
333 gst_util_uint64_scale_round (clocktime, rate, GST_SECOND)
336 * GST_AUDIO_DEF_RATE:
338 * Standard sampling rate used in consumer audio.
340 #define GST_AUDIO_DEF_RATE 44100
343 * GST_AUDIO_INT_PAD_TEMPLATE_CAPS:
345 * Template caps for integer audio. Can be used when defining a
346 * #GstStaticPadTemplate
348 #define GST_AUDIO_INT_PAD_TEMPLATE_CAPS \
349 "audio/x-raw-int, " \
350 "rate = (int) [ 1, MAX ], " \
351 "channels = (int) [ 1, MAX ], " \
352 "endianness = (int) { LITTLE_ENDIAN, BIG_ENDIAN }, " \
353 "width = (int) { 8, 16, 24, 32 }, " \
354 "depth = (int) [ 1, 32 ], " \
355 "signed = (boolean) { true, false }"
358 * GST_AUDIO_INT_STANDARD_PAD_TEMPLATE_CAPS:
360 * Template caps for 16bit integer stereo audio in native byte-order.
361 * Can be used when defining a #GstStaticPadTemplate
363 #define GST_AUDIO_INT_STANDARD_PAD_TEMPLATE_CAPS \
364 "audio/x-raw-int, " \
365 "rate = (int) [ 1, MAX ], " \
366 "channels = (int) 2, " \
367 "endianness = (int) BYTE_ORDER, " \
368 "width = (int) 16, " \
369 "depth = (int) 16, " \
370 "signed = (boolean) true"
373 * GST_AUDIO_FLOAT_PAD_TEMPLATE_CAPS:
375 * Template caps for float audio. Can be used when defining a
376 * #GstStaticPadTemplate
378 #define GST_AUDIO_FLOAT_PAD_TEMPLATE_CAPS \
379 "audio/x-raw-float, " \
380 "rate = (int) [ 1, MAX ], " \
381 "channels = (int) [ 1, MAX ], " \
382 "endianness = (int) { LITTLE_ENDIAN , BIG_ENDIAN }, " \
383 "width = (int) { 32, 64 }"
386 * GST_AUDIO_FLOAT_STANDARD_PAD_TEMPLATE_CAPS:
388 * Template caps for 32bit float mono audio in native byte-order.
389 * Can be used when defining a #GstStaticPadTemplate
391 #define GST_AUDIO_FLOAT_STANDARD_PAD_TEMPLATE_CAPS \
392 "audio/x-raw-float, " \
393 "width = (int) 32, " \
394 "rate = (int) [ 1, MAX ], " \
395 "channels = (int) 1, " \
396 "endianness = (int) BYTE_ORDER"
399 * this library defines and implements some helper functions for audio
403 /* get byte size of audio frame (based on caps of pad */
404 int gst_audio_frame_byte_size (GstPad* pad);
406 /* get length in frames of buffer */
407 long gst_audio_frame_length (GstPad* pad, GstBuffer* buf);
409 GstClockTime gst_audio_duration_from_pad_buffer (GstPad * pad, GstBuffer * buf);
411 /* check if the buffer size is a whole multiple of the frame size */
412 gboolean gst_audio_is_buffer_framed (GstPad* pad, GstBuffer* buf);
414 /* functions useful for _getcaps functions */
417 * @GST_AUDIO_FIELD_RATE: add rate field to caps
418 * @GST_AUDIO_FIELD_CHANNELS: add channels field to caps
419 * @GST_AUDIO_FIELD_ENDIANNESS: add endianness field to caps
420 * @GST_AUDIO_FIELD_WIDTH: add width field to caps
421 * @GST_AUDIO_FIELD_DEPTH: add depth field to caps
422 * @GST_AUDIO_FIELD_SIGNED: add signed field to caps
424 * Do not use anymore.
426 * Deprecated: use gst_structure_set() directly
428 #ifndef GST_DISABLE_DEPRECATED
430 GST_AUDIO_FIELD_RATE = (1 << 0),
431 GST_AUDIO_FIELD_CHANNELS = (1 << 1),
432 GST_AUDIO_FIELD_ENDIANNESS = (1 << 2),
433 GST_AUDIO_FIELD_WIDTH = (1 << 3),
434 GST_AUDIO_FIELD_DEPTH = (1 << 4),
435 GST_AUDIO_FIELD_SIGNED = (1 << 5)
439 #ifndef GST_DISABLE_DEPRECATED
440 void gst_audio_structure_set_int (GstStructure *structure, GstAudioFieldFlag flag);
441 #endif /* GST_DISABLE_DEPRECATED */
443 GstBuffer *gst_audio_buffer_clip (GstBuffer *buffer, GstSegment *segment, gint rate, gint frame_size);
447 #endif /* __GST_AUDIO_AUDIO_H__ */