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
28typedef struct _GstAudioResampler GstAudioResampler;
29
30/**
31 * GST_AUDIO_RESAMPLER_OPT_CUTOFF:
32 *
33 * G_TYPE_DOUBLE, Cutoff parameter for the filter. 0.940 is the default.
34 */
35#define GST_AUDIO_RESAMPLER_OPT_CUTOFF "GstAudioResampler.cutoff"
36/**
37 * GST_AUDIO_RESAMPLER_OPT_STOP_ATTENUATION:
38 *
39 * G_TYPE_DOUBLE, stopband attenuation in decibels. The attenuation
40 * after the stopband for the kaiser window. 85 dB is the default.
41 */
42#define GST_AUDIO_RESAMPLER_OPT_STOP_ATTENUATION "GstAudioResampler.stop-attenutation"
43/**
44 * GST_AUDIO_RESAMPLER_OPT_TRANSITION_BANDWIDTH:
45 *
46 * G_TYPE_DOUBLE, transition bandwidth. The width of the
47 * transition band for the kaiser window. 0.087 is the default.
48 */
49#define GST_AUDIO_RESAMPLER_OPT_TRANSITION_BANDWIDTH "GstAudioResampler.transition-bandwidth"
50
51/**
52 * GST_AUDIO_RESAMPLER_OPT_CUBIC_B:
53 *
54 * G_TYPE_DOUBLE, B parameter of the cubic filter.
55 * Values between 0.0 and 2.0 are accepted. 1.0 is the default.
56 *
57 * Below are some values of popular filters:
58 * B C
59 * Hermite 0.0 0.0
60 * Spline 1.0 0.0
61 * Catmull-Rom 0.0 1/2
62 */
63#define GST_AUDIO_RESAMPLER_OPT_CUBIC_B "GstAudioResampler.cubic-b"
64/**
65 * GST_AUDIO_RESAMPLER_OPT_CUBIC_C:
66 *
67 * G_TYPE_DOUBLE, C parameter of the cubic filter.
68 * Values between 0.0 and 2.0 are accepted. 0.0 is the default.
69 *
70 * See #GST_AUDIO_RESAMPLER_OPT_CUBIC_B for some more common values
71 */
72#define GST_AUDIO_RESAMPLER_OPT_CUBIC_C "GstAudioResampler.cubic-c"
73
74/**
75 * GST_AUDIO_RESAMPLER_OPT_N_TAPS:
76 *
77 * G_TYPE_INT: the number of taps to use for the filter.
78 * 0 is the default and selects the taps automatically.
79 */
80#define GST_AUDIO_RESAMPLER_OPT_N_TAPS "GstAudioResampler.n-taps"
81
82/**
83 * GstAudioResamplerFilterMode:
84 * @GST_AUDIO_RESAMPLER_FILTER_MODE_INTERPOLATED: Use interpolated filter tables. This
85 * uses less memory but more CPU and is slightly less accurate but it allows for more
86 * efficient variable rate resampling with gst_audio_resampler_update().
87 * @GST_AUDIO_RESAMPLER_FILTER_MODE_FULL: Use full filter table. This uses more memory
88 * but less CPU.
89 * @GST_AUDIO_RESAMPLER_FILTER_MODE_AUTO: Automatically choose between interpolated
90 * and full filter tables.
91 *
92 * Select for the filter tables should be set up.
93 */
94typedef enum {
95 GST_AUDIO_RESAMPLER_FILTER_MODE_INTERPOLATED = (0),
96 GST_AUDIO_RESAMPLER_FILTER_MODE_FULL,
97 GST_AUDIO_RESAMPLER_FILTER_MODE_AUTO,
98} GstAudioResamplerFilterMode;
99/**
100 * GST_AUDIO_RESAMPLER_OPT_FILTER_MODE:
101 *
102 * GST_TYPE_AUDIO_RESAMPLER_FILTER_MODE: how the filter tables should be
103 * constructed.
104 * GST_AUDIO_RESAMPLER_FILTER_MODE_AUTO is the default.
105 */
106#define GST_AUDIO_RESAMPLER_OPT_FILTER_MODE "GstAudioResampler.filter-mode"
107/**
108 * GST_AUDIO_RESAMPLER_OPT_FILTER_MODE_THRESHOLD:
109 *
110 * G_TYPE_UINT: the amount of memory to use for full filter tables before
111 * switching to interpolated filter tables.
112 * 1048576 is the default.
113 */
114#define GST_AUDIO_RESAMPLER_OPT_FILTER_MODE_THRESHOLD "GstAudioResampler.filter-mode-threshold"
115
116/**
117 * GstAudioResamplerFilterInterpolation:
118 * @GST_AUDIO_RESAMPLER_FILTER_INTERPOLATION_NONE: no interpolation
119 * @GST_AUDIO_RESAMPLER_FILTER_INTERPOLATION_LINEAR: linear interpolation of the
120 * filter coeficients.
121 * @GST_AUDIO_RESAMPLER_FILTER_INTERPOLATION_CUBIC: cubic interpolation of the
122 * filter coeficients.
123 *
124 * The different filter interpolation methods.
125 */
126typedef enum {
127 GST_AUDIO_RESAMPLER_FILTER_INTERPOLATION_NONE = (0),
128 GST_AUDIO_RESAMPLER_FILTER_INTERPOLATION_LINEAR,
129 GST_AUDIO_RESAMPLER_FILTER_INTERPOLATION_CUBIC,
130} GstAudioResamplerFilterInterpolation;
131/**
132 * GST_AUDIO_RESAMPLER_OPT_FILTER_INTERPOLATION:
133 *
134 * GST_TYPE_AUDIO_RESAMPLER_INTERPOLATION: how the filter coeficients should be
135 * interpolated.
136 * GST_AUDIO_RESAMPLER_FILTER_INTERPOLATION_CUBIC is default.
137 */
138#define GST_AUDIO_RESAMPLER_OPT_FILTER_INTERPOLATION "GstAudioResampler.filter-interpolation"
139/**
140 * GST_AUDIO_RESAMPLER_OPT_FILTER_OVERSAMPLE:
141 *
142 * G_TYPE_UINT, oversampling to use when interpolating filters
143 * 8 is the default.
144 */
145#define GST_AUDIO_RESAMPLER_OPT_FILTER_OVERSAMPLE "GstAudioResampler.filter-oversample"
146
147/**
148 * GST_AUDIO_RESAMPLER_OPT_MAX_PHASE_ERROR:
149 *
150 * G_TYPE_DOUBLE: The maximum allowed phase error when switching sample
151 * rates.
152 * 0.1 is the default.
153 */
154#define GST_AUDIO_RESAMPLER_OPT_MAX_PHASE_ERROR "GstAudioResampler.max-phase-error"
155
156/**
157 * GstAudioResamplerMethod:
158 * @GST_AUDIO_RESAMPLER_METHOD_NEAREST: Duplicates the samples when
159 * upsampling and drops when downsampling
160 * @GST_AUDIO_RESAMPLER_METHOD_LINEAR: Uses linear interpolation to reconstruct
161 * missing samples and averaging to downsample
162 * @GST_AUDIO_RESAMPLER_METHOD_CUBIC: Uses cubic interpolation
163 * @GST_AUDIO_RESAMPLER_METHOD_BLACKMAN_NUTTALL: Uses Blackman-Nuttall windowed sinc interpolation
164 * @GST_AUDIO_RESAMPLER_METHOD_KAISER: Uses Kaiser windowed sinc interpolation
165 *
166 * Different subsampling and upsampling methods
167 *
168 * Since: 1.6
169 */
170typedef enum {
171 GST_AUDIO_RESAMPLER_METHOD_NEAREST,
172 GST_AUDIO_RESAMPLER_METHOD_LINEAR,
173 GST_AUDIO_RESAMPLER_METHOD_CUBIC,
174 GST_AUDIO_RESAMPLER_METHOD_BLACKMAN_NUTTALL,
175 GST_AUDIO_RESAMPLER_METHOD_KAISER
176} GstAudioResamplerMethod;
177
178/**
179 * GstAudioResamplerFlags:
180 * @GST_AUDIO_RESAMPLER_FLAG_NONE: no flags
181 * @GST_AUDIO_RESAMPLER_FLAG_NON_INTERLEAVED_IN: input samples are non-interleaved.
182 * an array of blocks of samples, one for each channel, should be passed to the
183 * resample function.
184 * @GST_AUDIO_RESAMPLER_FLAG_NON_INTERLEAVED_OUT: output samples are non-interleaved.
185 * an array of blocks of samples, one for each channel, should be passed to the
186 * resample function.
187 * @GST_AUDIO_RESAMPLER_FLAG_VARIABLE_RATE: optimize for dynamic updates of the sample
188 * rates with gst_audio_resampler_update(). This will select an interpolating filter
189 * when #GST_AUDIO_RESAMPLER_FILTER_MODE_AUTO is configured.
190 *
191 * Different resampler flags.
192 */
193typedef enum {
194 GST_AUDIO_RESAMPLER_FLAG_NONE = (0),
195 GST_AUDIO_RESAMPLER_FLAG_NON_INTERLEAVED_IN = (1 << 0),
196 GST_AUDIO_RESAMPLER_FLAG_NON_INTERLEAVED_OUT = (1 << 1),
197 GST_AUDIO_RESAMPLER_FLAG_VARIABLE_RATE = (1 << 2),
198} GstAudioResamplerFlags;
199
200#define GST_AUDIO_RESAMPLER_QUALITY_MIN 0
201#define GST_AUDIO_RESAMPLER_QUALITY_MAX 10
202#define GST_AUDIO_RESAMPLER_QUALITY_DEFAULT 4
203
204GST_AUDIO_API
205void gst_audio_resampler_options_set_quality (GstAudioResamplerMethod method,
206 guint quality,
207 gint in_rate, gint out_rate,
208 GstStructure *options);
209
210GST_AUDIO_API
211GstAudioResampler * gst_audio_resampler_new (GstAudioResamplerMethod method,
212 GstAudioResamplerFlags flags,
213 GstAudioFormat format, gint channels,
214 gint in_rate, gint out_rate,
215 GstStructure *options);
216
217GST_AUDIO_API
218void gst_audio_resampler_free (GstAudioResampler *resampler);
219
220GST_AUDIO_API
221void gst_audio_resampler_reset (GstAudioResampler *resampler);
222
223GST_AUDIO_API
224gboolean gst_audio_resampler_update (GstAudioResampler *resampler,
225 gint in_rate, gint out_rate,
226 GstStructure *options);
227
228GST_AUDIO_API
229gsize gst_audio_resampler_get_out_frames (GstAudioResampler *resampler,
230 gsize in_frames);
231
232GST_AUDIO_API
233gsize gst_audio_resampler_get_in_frames (GstAudioResampler *resampler,
234 gsize out_frames);
235
236GST_AUDIO_API
237gsize gst_audio_resampler_get_max_latency (GstAudioResampler *resampler);
238
239GST_AUDIO_API
240void gst_audio_resampler_resample (GstAudioResampler * resampler,
241 gpointer in[], gsize in_frames,
242 gpointer out[], gsize out_frames);
243
244G_END_DECLS
245
246#endif /* __GST_AUDIO_RESAMPLER_H__ */
247