1/* GStreamer
2 * Copyright (C) 2004 Ronald Bultje <rbultje@ronald.bitfreak.net>
3 * (C) 2015 Wim Taymans <wim.taymans@gmail.com>
4 *
5 * audioconverter.h: audio format conversion library
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Library General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Library General Public License for more details.
16 *
17 * You should have received a copy of the GNU Library General Public
18 * License along with this library; if not, write to the
19 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
20 * Boston, MA 02110-1301, USA.
21 */
22
23#ifndef __GST_AUDIO_CONVERTER_H__
24#define __GST_AUDIO_CONVERTER_H__
25
26#include <gst/gst.h>
27#include <gst/audio/audio.h>
28
29G_BEGIN_DECLS
30
31/**
32 * GstAudioConverter:
33 *
34 * Opaque #GstAudioConverter struct.
35 *
36 * Since: 1.8
37 */
38typedef struct _GstAudioConverter GstAudioConverter;
39
40/**
41 * GST_AUDIO_CONVERTER_OPT_RESAMPLER_METHOD:
42 *
43 * #GstAudioResamplerMethod, The resampler method to use when
44 * changing sample rates.
45 * Default is #GST_AUDIO_RESAMPLER_METHOD_BLACKMAN_NUTTALL.
46 */
47#define GST_AUDIO_CONVERTER_OPT_RESAMPLER_METHOD "GstAudioConverter.resampler-method"
48
49/**
50 * GST_AUDIO_CONVERTER_OPT_DITHER_METHOD:
51 *
52 * #GstAudioDitherMethod, The dither method to use when
53 * changing bit depth.
54 * Default is #GST_AUDIO_DITHER_NONE.
55 */
56#define GST_AUDIO_CONVERTER_OPT_DITHER_METHOD "GstAudioConverter.dither-method"
57
58/**
59 * GST_AUDIO_CONVERTER_OPT_NOISE_SHAPING_METHOD:
60 *
61 * #GstAudioNoiseShapingMethod, The noise shaping method to use
62 * to mask noise from quantization errors.
63 * Default is #GST_AUDIO_NOISE_SHAPING_NONE.
64 */
65#define GST_AUDIO_CONVERTER_OPT_NOISE_SHAPING_METHOD "GstAudioConverter.noise-shaping-method"
66
67/**
68 * GST_AUDIO_CONVERTER_OPT_QUANTIZATION:
69 *
70 * #G_TYPE_UINT, The quantization amount. Components will be
71 * quantized to multiples of this value.
72 * Default is 1
73 */
74#define GST_AUDIO_CONVERTER_OPT_QUANTIZATION "GstAudioConverter.quantization"
75
76/**
77 * GST_AUDIO_CONVERTER_OPT_MIX_MATRIX:
78 *
79 * #GST_TYPE_LIST, The channel mapping matrix.
80 *
81 * The matrix coefficients must be between -1 and 1: the number of rows is equal
82 * to the number of output channels and the number of columns is equal to the
83 * number of input channels.
84 *
85 * ## Example matrix generation code
86 * To generate the matrix using code:
87 *
88 * |[
89 * GValue v = G_VALUE_INIT;
90 * GValue v2 = G_VALUE_INIT;
91 * GValue v3 = G_VALUE_INIT;
92 *
93 * g_value_init (&v2, GST_TYPE_ARRAY);
94 * g_value_init (&v3, G_TYPE_DOUBLE);
95 * g_value_set_double (&v3, 1);
96 * gst_value_array_append_value (&v2, &v3);
97 * g_value_unset (&v3);
98 * [ Repeat for as many double as your input channels - unset and reinit v3 ]
99 * g_value_init (&v, GST_TYPE_ARRAY);
100 * gst_value_array_append_value (&v, &v2);
101 * g_value_unset (&v2);
102 * [ Repeat for as many v2's as your output channels - unset and reinit v2]
103 * g_object_set_property (G_OBJECT (audiomixmatrix), "matrix", &v);
104 * g_value_unset (&v);
105 * ]|
106 */
107#define GST_AUDIO_CONVERTER_OPT_MIX_MATRIX "GstAudioConverter.mix-matrix"
108
109/**
110 * GST_AUDIO_CONVERTER_OPT_DITHER_THRESHOLD:
111 *
112 * Threshold for the output bit depth at/below which to apply dithering.
113 *
114 * Default is 20 bit.
115 *
116 * Since: 1.22
117 */
118#define GST_AUDIO_CONVERTER_OPT_DITHER_THRESHOLD "GstAudioConverter.dither-threshold"
119
120/**
121 * GstAudioConverterFlags:
122 * @GST_AUDIO_CONVERTER_FLAG_NONE: no flag
123 * @GST_AUDIO_CONVERTER_FLAG_IN_WRITABLE: the input sample arrays are writable and can be
124 * used as temporary storage during conversion.
125 * @GST_AUDIO_CONVERTER_FLAG_VARIABLE_RATE: allow arbitrary rate updates with
126 * gst_audio_converter_update_config().
127 *
128 * Extra flags passed to gst_audio_converter_new() and gst_audio_converter_samples().
129 */
130typedef enum {
131 GST_AUDIO_CONVERTER_FLAG_NONE = 0,
132 GST_AUDIO_CONVERTER_FLAG_IN_WRITABLE = (1 << 0),
133 GST_AUDIO_CONVERTER_FLAG_VARIABLE_RATE = (1 << 1)
134} GstAudioConverterFlags;
135
136GST_AUDIO_API
137GstAudioConverter * gst_audio_converter_new (GstAudioConverterFlags flags,
138 GstAudioInfo *in_info,
139 GstAudioInfo *out_info,
140 GstStructure *config);
141
142GST_AUDIO_API
143GType gst_audio_converter_get_type (void);
144
145GST_AUDIO_API
146void gst_audio_converter_free (GstAudioConverter * convert);
147
148GST_AUDIO_API
149void gst_audio_converter_reset (GstAudioConverter * convert);
150
151GST_AUDIO_API
152gboolean gst_audio_converter_update_config (GstAudioConverter * convert,
153 gint in_rate, gint out_rate,
154 GstStructure *config);
155
156GST_AUDIO_API
157const GstStructure * gst_audio_converter_get_config (GstAudioConverter * convert,
158 gint *in_rate, gint *out_rate);
159
160GST_AUDIO_API
161gsize gst_audio_converter_get_out_frames (GstAudioConverter *convert,
162 gsize in_frames);
163
164GST_AUDIO_API
165gsize gst_audio_converter_get_in_frames (GstAudioConverter *convert,
166 gsize out_frames);
167
168GST_AUDIO_API
169gsize gst_audio_converter_get_max_latency (GstAudioConverter *convert);
170
171GST_AUDIO_API
172gboolean gst_audio_converter_samples (GstAudioConverter * convert,
173 GstAudioConverterFlags flags,
174 gpointer in[], gsize in_frames,
175 gpointer out[], gsize out_frames);
176
177GST_AUDIO_API
178gboolean gst_audio_converter_supports_inplace (GstAudioConverter *convert);
179
180GST_AUDIO_API
181gboolean gst_audio_converter_is_passthrough (GstAudioConverter *convert);
182
183GST_AUDIO_API
184gboolean gst_audio_converter_convert (GstAudioConverter * convert,
185 GstAudioConverterFlags flags,
186 gpointer in, gsize in_size,
187 gpointer *out, gsize *out_size);
188
189G_END_DECLS
190
191#endif /* __GST_AUDIO_CONVERTER_H__ */
192

source code of include/gstreamer-1.0/gst/audio/audio-converter.h