1/* GStreamer
2 * Copyright (C) <2015> Wim Taymans <wim.taymans@gmail.com>
3 *
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Library General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
8 *
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Library General Public License for more details.
13 *
14 * You should have received a copy of the GNU Library General Public
15 * License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
17 * Boston, MA 02110-1301, USA.
18 */
19
20#ifndef __GST_AUDIO_RESAMPLER_H__
21#define __GST_AUDIO_RESAMPLER_H__
22
23#include <gst/gst.h>
24#include <gst/audio/audio.h>
25
26G_BEGIN_DECLS
27
28/**
29 * GstAudioResampler:
30 *
31 * Opaque #GstAudioResampler struct.
32 *
33 * Since: 1.10
34 */
35typedef struct _GstAudioResampler GstAudioResampler;
36
37/**
38 * GST_AUDIO_RESAMPLER_OPT_CUTOFF:
39 *
40 * G_TYPE_DOUBLE, Cutoff parameter for the filter. 0.940 is the default.
41 */
42#define GST_AUDIO_RESAMPLER_OPT_CUTOFF "GstAudioResampler.cutoff"
43/**
44 * GST_AUDIO_RESAMPLER_OPT_STOP_ATTENUATION:
45 *
46 * G_TYPE_DOUBLE, stopband attenuation in decibels. The attenuation
47 * after the stopband for the kaiser window. 85 dB is the default.
48 */
49#define GST_AUDIO_RESAMPLER_OPT_STOP_ATTENUATION "GstAudioResampler.stop-attenutation"
50/**
51 * GST_AUDIO_RESAMPLER_OPT_TRANSITION_BANDWIDTH:
52 *
53 * G_TYPE_DOUBLE, transition bandwidth. The width of the
54 * transition band for the kaiser window. 0.087 is the default.
55 */
56#define GST_AUDIO_RESAMPLER_OPT_TRANSITION_BANDWIDTH "GstAudioResampler.transition-bandwidth"
57
58/**
59 * GST_AUDIO_RESAMPLER_OPT_CUBIC_B:
60 *
61 * G_TYPE_DOUBLE, B parameter of the cubic filter.
62 * Values between 0.0 and 2.0 are accepted. 1.0 is the default.
63 *
64 * Below are some values of popular filters:
65 * B C
66 * Hermite 0.0 0.0
67 * Spline 1.0 0.0
68 * Catmull-Rom 0.0 1/2
69 */
70#define GST_AUDIO_RESAMPLER_OPT_CUBIC_B "GstAudioResampler.cubic-b"
71/**
72 * GST_AUDIO_RESAMPLER_OPT_CUBIC_C:
73 *
74 * G_TYPE_DOUBLE, C parameter of the cubic filter.
75 * Values between 0.0 and 2.0 are accepted. 0.0 is the default.
76 *
77 * See #GST_AUDIO_RESAMPLER_OPT_CUBIC_B for some more common values
78 */
79#define GST_AUDIO_RESAMPLER_OPT_CUBIC_C "GstAudioResampler.cubic-c"
80
81/**
82 * GST_AUDIO_RESAMPLER_OPT_N_TAPS:
83 *
84 * G_TYPE_INT: the number of taps to use for the filter.
85 * 0 is the default and selects the taps automatically.
86 */
87#define GST_AUDIO_RESAMPLER_OPT_N_TAPS "GstAudioResampler.n-taps"
88
89/**
90 * GstAudioResamplerFilterMode:
91 * @GST_AUDIO_RESAMPLER_FILTER_MODE_INTERPOLATED: Use interpolated filter tables. This
92 * uses less memory but more CPU and is slightly less accurate but it allows for more
93 * efficient variable rate resampling with gst_audio_resampler_update().
94 * @GST_AUDIO_RESAMPLER_FILTER_MODE_FULL: Use full filter table. This uses more memory
95 * but less CPU.
96 * @GST_AUDIO_RESAMPLER_FILTER_MODE_AUTO: Automatically choose between interpolated
97 * and full filter tables.
98 *
99 * Select for the filter tables should be set up.
100 *
101 * Since: 1.10
102 */
103typedef enum {
104 GST_AUDIO_RESAMPLER_FILTER_MODE_INTERPOLATED = (0),
105 GST_AUDIO_RESAMPLER_FILTER_MODE_FULL,
106 GST_AUDIO_RESAMPLER_FILTER_MODE_AUTO,
107} GstAudioResamplerFilterMode;
108/**
109 * GST_AUDIO_RESAMPLER_OPT_FILTER_MODE:
110 *
111 * GST_TYPE_AUDIO_RESAMPLER_FILTER_MODE: how the filter tables should be
112 * constructed.
113 * GST_AUDIO_RESAMPLER_FILTER_MODE_AUTO is the default.
114 */
115#define GST_AUDIO_RESAMPLER_OPT_FILTER_MODE "GstAudioResampler.filter-mode"
116/**
117 * GST_AUDIO_RESAMPLER_OPT_FILTER_MODE_THRESHOLD:
118 *
119 * G_TYPE_UINT: the amount of memory to use for full filter tables before
120 * switching to interpolated filter tables.
121 * 1048576 is the default.
122 */
123#define GST_AUDIO_RESAMPLER_OPT_FILTER_MODE_THRESHOLD "GstAudioResampler.filter-mode-threshold"
124
125/**
126 * GstAudioResamplerFilterInterpolation:
127 * @GST_AUDIO_RESAMPLER_FILTER_INTERPOLATION_NONE: no interpolation
128 * @GST_AUDIO_RESAMPLER_FILTER_INTERPOLATION_LINEAR: linear interpolation of the
129 * filter coefficients.
130 * @GST_AUDIO_RESAMPLER_FILTER_INTERPOLATION_CUBIC: cubic interpolation of the
131 * filter coefficients.
132 *
133 * The different filter interpolation methods.
134 *
135 * Since: 1.10
136 */
137typedef enum {
138 GST_AUDIO_RESAMPLER_FILTER_INTERPOLATION_NONE = (0),
139 GST_AUDIO_RESAMPLER_FILTER_INTERPOLATION_LINEAR,
140 GST_AUDIO_RESAMPLER_FILTER_INTERPOLATION_CUBIC,
141} GstAudioResamplerFilterInterpolation;
142/**
143 * GST_AUDIO_RESAMPLER_OPT_FILTER_INTERPOLATION:
144 *
145 * GST_TYPE_AUDIO_RESAMPLER_INTERPOLATION: how the filter coefficients should be
146 * interpolated.
147 * GST_AUDIO_RESAMPLER_FILTER_INTERPOLATION_CUBIC is default.
148 */
149#define GST_AUDIO_RESAMPLER_OPT_FILTER_INTERPOLATION "GstAudioResampler.filter-interpolation"
150/**
151 * GST_AUDIO_RESAMPLER_OPT_FILTER_OVERSAMPLE:
152 *
153 * G_TYPE_UINT, oversampling to use when interpolating filters
154 * 8 is the default.
155 */
156#define GST_AUDIO_RESAMPLER_OPT_FILTER_OVERSAMPLE "GstAudioResampler.filter-oversample"
157
158/**
159 * GST_AUDIO_RESAMPLER_OPT_MAX_PHASE_ERROR:
160 *
161 * G_TYPE_DOUBLE: The maximum allowed phase error when switching sample
162 * rates.
163 * 0.1 is the default.
164 */
165#define GST_AUDIO_RESAMPLER_OPT_MAX_PHASE_ERROR "GstAudioResampler.max-phase-error"
166
167/**
168 * GstAudioResamplerMethod:
169 * @GST_AUDIO_RESAMPLER_METHOD_NEAREST: Duplicates the samples when
170 * upsampling and drops when downsampling
171 * @GST_AUDIO_RESAMPLER_METHOD_LINEAR: Uses linear interpolation to reconstruct
172 * missing samples and averaging to downsample
173 * @GST_AUDIO_RESAMPLER_METHOD_CUBIC: Uses cubic interpolation
174 * @GST_AUDIO_RESAMPLER_METHOD_BLACKMAN_NUTTALL: Uses Blackman-Nuttall windowed sinc interpolation
175 * @GST_AUDIO_RESAMPLER_METHOD_KAISER: Uses Kaiser windowed sinc interpolation
176 *
177 * Different subsampling and upsampling methods
178 *
179 * Since: 1.10
180 */
181typedef enum {
182 GST_AUDIO_RESAMPLER_METHOD_NEAREST,
183 GST_AUDIO_RESAMPLER_METHOD_LINEAR,
184 GST_AUDIO_RESAMPLER_METHOD_CUBIC,
185 GST_AUDIO_RESAMPLER_METHOD_BLACKMAN_NUTTALL,
186 GST_AUDIO_RESAMPLER_METHOD_KAISER
187} GstAudioResamplerMethod;
188
189/**
190 * GstAudioResamplerFlags:
191 * @GST_AUDIO_RESAMPLER_FLAG_NONE: no flags
192 * @GST_AUDIO_RESAMPLER_FLAG_NON_INTERLEAVED_IN: input samples are non-interleaved.
193 * an array of blocks of samples, one for each channel, should be passed to the
194 * resample function.
195 * @GST_AUDIO_RESAMPLER_FLAG_NON_INTERLEAVED_OUT: output samples are non-interleaved.
196 * an array of blocks of samples, one for each channel, should be passed to the
197 * resample function.
198 * @GST_AUDIO_RESAMPLER_FLAG_VARIABLE_RATE: optimize for dynamic updates of the sample
199 * rates with gst_audio_resampler_update(). This will select an interpolating filter
200 * when #GST_AUDIO_RESAMPLER_FILTER_MODE_AUTO is configured.
201 *
202 * Different resampler flags.
203 *
204 * Since: 1.10
205 */
206typedef enum {
207 GST_AUDIO_RESAMPLER_FLAG_NONE = (0),
208 GST_AUDIO_RESAMPLER_FLAG_NON_INTERLEAVED_IN = (1 << 0),
209 GST_AUDIO_RESAMPLER_FLAG_NON_INTERLEAVED_OUT = (1 << 1),
210 GST_AUDIO_RESAMPLER_FLAG_VARIABLE_RATE = (1 << 2),
211} GstAudioResamplerFlags;
212
213#define GST_AUDIO_RESAMPLER_QUALITY_MIN 0
214#define GST_AUDIO_RESAMPLER_QUALITY_MAX 10
215#define GST_AUDIO_RESAMPLER_QUALITY_DEFAULT 4
216
217GST_AUDIO_API
218void gst_audio_resampler_options_set_quality (GstAudioResamplerMethod method,
219 guint quality,
220 gint in_rate, gint out_rate,
221 GstStructure *options);
222
223GST_AUDIO_API
224GstAudioResampler * gst_audio_resampler_new (GstAudioResamplerMethod method,
225 GstAudioResamplerFlags flags,
226 GstAudioFormat format, gint channels,
227 gint in_rate, gint out_rate,
228 GstStructure *options);
229
230GST_AUDIO_API
231void gst_audio_resampler_free (GstAudioResampler *resampler);
232
233GST_AUDIO_API
234void gst_audio_resampler_reset (GstAudioResampler *resampler);
235
236GST_AUDIO_API
237gboolean gst_audio_resampler_update (GstAudioResampler *resampler,
238 gint in_rate, gint out_rate,
239 GstStructure *options);
240
241GST_AUDIO_API
242gsize gst_audio_resampler_get_out_frames (GstAudioResampler *resampler,
243 gsize in_frames);
244
245GST_AUDIO_API
246gsize gst_audio_resampler_get_in_frames (GstAudioResampler *resampler,
247 gsize out_frames);
248
249GST_AUDIO_API
250gsize gst_audio_resampler_get_max_latency (GstAudioResampler *resampler);
251
252GST_AUDIO_API
253void gst_audio_resampler_resample (GstAudioResampler * resampler,
254 gpointer in[], gsize in_frames,
255 gpointer out[], gsize out_frames);
256
257G_END_DECLS
258
259#endif /* __GST_AUDIO_RESAMPLER_H__ */
260

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