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
31typedef struct _GstAudioConverter GstAudioConverter;
32
33/**
34 * GST_AUDIO_CONVERTER_OPT_RESAMPLER_METHOD:
35 *
36 * #GST_TYPE_AUDIO_RESAMPLER_METHOD, The resampler method to use when
37 * changing sample rates.
38 * Default is #GST_AUDIO_RESAMPLER_METHOD_BLACKMAN_NUTTALL.
39 */
40#define GST_AUDIO_CONVERTER_OPT_RESAMPLER_METHOD "GstAudioConverter.resampler-method"
41
42/**
43 * GST_AUDIO_CONVERTER_OPT_DITHER_METHOD:
44 *
45 * #GST_TYPE_AUDIO_DITHER_METHOD, The dither method to use when
46 * changing bit depth.
47 * Default is #GST_AUDIO_DITHER_NONE.
48 */
49#define GST_AUDIO_CONVERTER_OPT_DITHER_METHOD "GstAudioConverter.dither-method"
50
51/**
52 * GST_AUDIO_CONVERTER_OPT_NOISE_SHAPING_METHOD:
53 *
54 * #GST_TYPE_AUDIO_NOISE_SHAPING_METHOD, The noise shaping method to use
55 * to mask noise from quantization errors.
56 * Default is #GST_AUDIO_NOISE_SHAPING_NONE.
57 */
58#define GST_AUDIO_CONVERTER_OPT_NOISE_SHAPING_METHOD "GstAudioConverter.noise-shaping-method"
59
60/**
61 * GST_AUDIO_CONVERTER_OPT_QUANTIZATION:
62 *
63 * #G_TYPE_UINT, The quantization amount. Components will be
64 * quantized to multiples of this value.
65 * Default is 1
66 */
67#define GST_AUDIO_CONVERTER_OPT_QUANTIZATION "GstAudioConverter.quantization"
68
69/**
70 * GST_AUDIO_CONVERTER_OPT_MIX_MATRIX:
71 *
72 * #GST_TYPE_VALUE_LIST, The channel mapping matrix.
73 *
74 * The matrix coefficients must be between -1 and 1: the number of rows is equal
75 * to the number of output channels and the number of columns is equal to the
76 * number of input channels.
77 *
78 * ## Example matrix generation code
79 * To generate the matrix using code:
80 *
81 * |[
82 * GValue v = G_VALUE_INIT;
83 * GValue v2 = G_VALUE_INIT;
84 * GValue v3 = G_VALUE_INIT;
85 *
86 * g_value_init (&v2, GST_TYPE_ARRAY);
87 * g_value_init (&v3, G_TYPE_DOUBLE);
88 * g_value_set_double (&v3, 1);
89 * gst_value_array_append_value (&v2, &v3);
90 * g_value_unset (&v3);
91 * [ Repeat for as many double as your input channels - unset and reinit v3 ]
92 * g_value_init (&v, GST_TYPE_ARRAY);
93 * gst_value_array_append_value (&v, &v2);
94 * g_value_unset (&v2);
95 * [ Repeat for as many v2's as your output channels - unset and reinit v2]
96 * g_object_set_property (G_OBJECT (audiomixmatrix), "matrix", &v);
97 * g_value_unset (&v);
98 * ]|
99 */
100#define GST_AUDIO_CONVERTER_OPT_MIX_MATRIX "GstAudioConverter.mix-matrix"
101
102/**
103 * GstAudioConverterFlags:
104 * @GST_AUDIO_CONVERTER_FLAG_NONE: no flag
105 * @GST_AUDIO_CONVERTER_FLAG_IN_WRITABLE: the input sample arrays are writable and can be
106 * used as temporary storage during conversion.
107 * @GST_AUDIO_CONVERTER_FLAG_VARIABLE_RATE: allow arbitrary rate updates with
108 * gst_audio_converter_update_config().
109 *
110 * Extra flags passed to gst_audio_converter_new() and gst_audio_converter_samples().
111 */
112typedef enum {
113 GST_AUDIO_CONVERTER_FLAG_NONE = 0,
114 GST_AUDIO_CONVERTER_FLAG_IN_WRITABLE = (1 << 0),
115 GST_AUDIO_CONVERTER_FLAG_VARIABLE_RATE = (1 << 1)
116} GstAudioConverterFlags;
117
118GST_AUDIO_API
119GstAudioConverter * gst_audio_converter_new (GstAudioConverterFlags flags,
120 GstAudioInfo *in_info,
121 GstAudioInfo *out_info,
122 GstStructure *config);
123
124GST_AUDIO_API
125GType gst_audio_converter_get_type (void);
126
127GST_AUDIO_API
128void gst_audio_converter_free (GstAudioConverter * convert);
129
130GST_AUDIO_API
131void gst_audio_converter_reset (GstAudioConverter * convert);
132
133GST_AUDIO_API
134gboolean gst_audio_converter_update_config (GstAudioConverter * convert,
135 gint in_rate, gint out_rate,
136 GstStructure *config);
137
138GST_AUDIO_API
139const GstStructure * gst_audio_converter_get_config (GstAudioConverter * convert,
140 gint *in_rate, gint *out_rate);
141
142GST_AUDIO_API
143gsize gst_audio_converter_get_out_frames (GstAudioConverter *convert,
144 gsize in_frames);
145
146GST_AUDIO_API
147gsize gst_audio_converter_get_in_frames (GstAudioConverter *convert,
148 gsize out_frames);
149
150GST_AUDIO_API
151gsize gst_audio_converter_get_max_latency (GstAudioConverter *convert);
152
153GST_AUDIO_API
154gboolean gst_audio_converter_samples (GstAudioConverter * convert,
155 GstAudioConverterFlags flags,
156 gpointer in[], gsize in_frames,
157 gpointer out[], gsize out_frames);
158
159GST_AUDIO_API
160gboolean gst_audio_converter_supports_inplace (GstAudioConverter *convert);
161
162GST_AUDIO_API
163gboolean gst_audio_converter_is_passthrough (GstAudioConverter *convert);
164
165GST_AUDIO_API
166gboolean gst_audio_converter_convert (GstAudioConverter * convert,
167 GstAudioConverterFlags flags,
168 gpointer in, gsize in_size,
169 gpointer *out, gsize *out_size);
170
171G_END_DECLS
172
173#endif /* __GST_AUDIO_CONVERTER_H__ */
174