Adding error codes.
[speexdsp.git] / include / speex / speex_resampler.h
1 /* Copyright (C) 2007 Jean-Marc Valin
2       
3    File: speex_resampler.h
4    Resampling code
5       
6    The design goals of this code are:
7       - Very fast algorithm
8       - Low memory requirement
9       - Good *perceptual* quality (and not best SNR)
10
11    Redistribution and use in source and binary forms, with or without
12    modification, are permitted provided that the following conditions are
13    met:
14
15    1. Redistributions of source code must retain the above copyright notice,
16    this list of conditions and the following disclaimer.
17
18    2. Redistributions in binary form must reproduce the above copyright
19    notice, this list of conditions and the following disclaimer in the
20    documentation and/or other materials provided with the distribution.
21
22    3. The name of the author may not be used to endorse or promote products
23    derived from this software without specific prior written permission.
24
25    THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
26    IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
27    OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
28    DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
29    INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
30    (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
31    SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
32    HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
33    STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
34    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35    POSSIBILITY OF SUCH DAMAGE.
36 */
37
38
39 #ifndef SPEEX_RESAMPLER_H
40 #define SPEEX_RESAMPLER_H
41
42 #ifdef OUTSIDE_SPEEX
43
44 /********* WARNING: MENTAL SANITY ENDS HERE *************/
45
46 /* If the resampler is defined outside of Speex, we change the symbol names so that 
47    there won't be any clash if linking with Speex later on. */
48
49 /* #define RANDOM_PREFIX your software name here */
50 #ifndef RANDOM_PREFIX
51 #error "Please define RANDOM_PREFIX (above) to something specific to your project to prevent symbol name clashes"
52 #endif
53
54 #define CAT_PREFIX2(a,b) a ## b
55 #define CAT_PREFIX(a,b) CAT_PREFIX2(a, b)
56       
57 #define speex_resampler_init CAT_PREFIX(RANDOM_PREFIX,_resampler_init)
58 #define speex_resampler_init_frac CAT_PREFIX(RANDOM_PREFIX,_resampler_init_frac)
59 #define speex_resampler_destroy CAT_PREFIX(RANDOM_PREFIX,_resampler_destroy)
60 #define speex_resampler_process_float CAT_PREFIX(RANDOM_PREFIX,_resampler_process_float)
61 #define speex_resampler_process_int CAT_PREFIX(RANDOM_PREFIX,_resampler_process_int)
62 #define speex_resampler_process_interleaved_float CAT_PREFIX(RANDOM_PREFIX,_resampler_process_interleaved_float)
63 #define speex_resampler_process_interleaved_int CAT_PREFIX(RANDOM_PREFIX,_resampler_process_interleaved_int)
64 #define speex_resampler_set_rate CAT_PREFIX(RANDOM_PREFIX,_resampler_set_rate)
65 #define speex_resampler_get_rate CAT_PREFIX(RANDOM_PREFIX,_resampler_get_rate)
66 #define speex_resampler_set_rate_frac CAT_PREFIX(RANDOM_PREFIX,_resampler_set_rate_frac)
67 #define speex_resampler_get_ratio CAT_PREFIX(RANDOM_PREFIX,_resampler_get_ratio)
68 #define speex_resampler_set_quality CAT_PREFIX(RANDOM_PREFIX,_resampler_set_quality)
69 #define speex_resampler_get_quality CAT_PREFIX(RANDOM_PREFIX,_resampler_get_quality)
70 #define speex_resampler_set_input_stride CAT_PREFIX(RANDOM_PREFIX,_resampler_set_input_stride)
71 #define speex_resampler_get_input_stride CAT_PREFIX(RANDOM_PREFIX,_resampler_get_input_stride)
72 #define speex_resample_set_output_stride CAT_PREFIX(RANDOM_PREFIX,_resample_set_output_stride)
73 #define speex_resample_get_output_stride CAT_PREFIX(RANDOM_PREFIX,_resample_get_output_stride)
74 #define speex_resampler_skip_zeros CAT_PREFIX(RANDOM_PREFIX,_resampler_skip_zeros)
75 #define speex_resampler_reset_mem CAT_PREFIX(RANDOM_PREFIX,_resampler_reset_mem)
76
77 #define spx_int16_t short
78 #define spx_int32_t int
79 #define spx_uint16_t unsigned short
80 #define spx_uint32_t unsigned int
81       
82 #else /* OUTSIDE_SPEEX */
83
84 #include "speex/speex_types.h"
85
86 #endif /* OUTSIDE_SPEEX */
87
88 #ifdef __cplusplus
89 extern "C" {
90 #endif
91
92 #define SPEEX_RESAMPLER_QUALITY_MAX 10
93 #define SPEEX_RESAMPLER_QUALITY_MIN 0
94 #define SPEEX_RESAMPLER_QUALITY_DEFAULT 4
95 #define SPEEX_RESAMPLER_QUALITY_VOIP 3
96 #define SPEEX_RESAMPLER_QUALITY_DESKTOP 5
97
98 enum {
99    RESAMPLER_ERR_SUCCESS         = 0,
100    RESAMPLER_ERR_ALLOC_FAILED    = 1,
101    RESAMPLER_ERR_BAD_STATE       = 2,
102    RESAMPLER_ERR_INVALID_ARG     = 3,
103    RESAMPLER_ERR_PTR_OVERLAP     = 4,
104    
105    RESAMPLER_ERR_MAX_ERROR
106 };
107
108 struct SpeexResamplerState_;
109 typedef struct SpeexResamplerState_ SpeexResamplerState;
110
111 /** Create a new resampler with integer input and output rates.
112  * @param nb_channels Number of channels to be processed
113  * @param in_rate Input sampling rate (integer number of Hz).
114  * @param out_rate Output sampling rate (integer number of Hz).
115  * @param quality Resampling quality between 0 and 10, where 0 has poor quality
116  * and 10 has very high quality.
117  * @return Newly created resampler state
118  * @retval NULL Error: not enough memory
119  */
120 SpeexResamplerState *speex_resampler_init(spx_uint32_t nb_channels, 
121                                           spx_uint32_t in_rate, 
122                                           spx_uint32_t out_rate, 
123                                           int quality,
124                                           int *err);
125
126 /** Create a new resampler with fractional input/output rates. The sampling 
127  * rate ratio is an arbitrary rational number with both the numerator and 
128  * denominator being 32-bit integers.
129  * @param nb_channels Number of channels to be processed
130  * @param ratio_num Numerator of the sampling rate ratio
131  * @param ratio_den Denominator of the sampling rate ratio
132  * @param in_rate Input sampling rate rounded to the nearest integer (in Hz).
133  * @param out_rate Output sampling rate rounded to the nearest integer (in Hz).
134  * @param quality Resampling quality between 0 and 10, where 0 has poor quality
135  * and 10 has very high quality.
136  * @return Newly created resampler state
137  * @retval NULL Error: not enough memory
138  */
139 SpeexResamplerState *speex_resampler_init_frac(spx_uint32_t nb_channels, 
140                                                spx_uint32_t ratio_num, 
141                                                spx_uint32_t ratio_den, 
142                                                spx_uint32_t in_rate, 
143                                                spx_uint32_t out_rate, 
144                                                int quality,
145                                                int *err);
146
147 /** Destroy a resampler state.
148  * @param st Resampler state
149  */
150 void speex_resampler_destroy(SpeexResamplerState *st);
151
152 /** Resample a float array. The input and output buffers must *not* overlap.
153  * @param st Resampler state
154  * @param channel_index Index of the channel to process for the multi-channel 
155  * base (0 otherwise)
156  * @param in Input buffer
157  * @param in_len Number of input samples in the input buffer. Returns the 
158  * number of samples processed
159  * @param out Output buffer
160  * @param out_len Size of the output buffer. Returns the number of samples written
161  */
162 int speex_resampler_process_float(SpeexResamplerState *st, 
163                                    spx_uint32_t channel_index, 
164                                    const float *in, 
165                                    spx_uint32_t *in_len, 
166                                    float *out, 
167                                    spx_uint32_t *out_len);
168
169 /** Resample an int array. The input and output buffers must *not* overlap.
170  * @param st Resampler state
171  * @param channel_index Index of the channel to process for the multi-channel 
172  * base (0 otherwise)
173  * @param in Input buffer
174  * @param in_len Number of input samples in the input buffer. Returns the number
175  * of samples processed
176  * @param out Output buffer
177  * @param out_len Size of the output buffer. Returns the number of samples written
178  */
179 int speex_resampler_process_int(SpeexResamplerState *st, 
180                                  spx_uint32_t channel_index, 
181                                  const spx_int16_t *in, 
182                                  spx_uint32_t *in_len, 
183                                  spx_int16_t *out, 
184                                  spx_uint32_t *out_len);
185
186 /** Resample an interleaved float array. The input and output buffers must *not* overlap.
187  * @param st Resampler state
188  * @param in Input buffer
189  * @param in_len Number of input samples in the input buffer. Returns the number
190  * of samples processed. This is all per-channel.
191  * @param out Output buffer
192  * @param out_len Size of the output buffer. Returns the number of samples written.
193  * This is all per-channel.
194  */
195 int speex_resampler_process_interleaved_float(SpeexResamplerState *st, 
196                                                const float *in, 
197                                                spx_uint32_t *in_len, 
198                                                float *out, 
199                                                spx_uint32_t *out_len);
200
201 /** Resample an interleaved int array. The input and output buffers must *not* overlap.
202  * @param st Resampler state
203  * @param in Input buffer
204  * @param in_len Number of input samples in the input buffer. Returns the number
205  * of samples processed. This is all per-channel.
206  * @param out Output buffer
207  * @param out_len Size of the output buffer. Returns the number of samples written.
208  * This is all per-channel.
209  */
210 int speex_resampler_process_interleaved_int(SpeexResamplerState *st, 
211                                              const spx_int16_t *in, 
212                                              spx_uint32_t *in_len, 
213                                              spx_int16_t *out, 
214                                              spx_uint32_t *out_len);
215
216 /** Set (change) the input/output sampling rates (integer value).
217  * @param st Resampler state
218  * @param in_rate Input sampling rate (integer number of Hz).
219  * @param out_rate Output sampling rate (integer number of Hz).
220  */
221 int speex_resampler_set_rate(SpeexResamplerState *st, 
222                               spx_uint32_t in_rate, 
223                               spx_uint32_t out_rate);
224
225 /** Get the current input/output sampling rates (integer value).
226  * @param st Resampler state
227  * @param in_rate Input sampling rate (integer number of Hz) copied.
228  * @param out_rate Output sampling rate (integer number of Hz) copied.
229  */
230 void speex_resampler_get_rate(SpeexResamplerState *st, 
231                               spx_uint32_t *in_rate, 
232                               spx_uint32_t *out_rate);
233
234 /** Set (change) the input/output sampling rates and resampling ratio 
235  * (fractional values in Hz supported).
236  * @param st Resampler state
237  * @param ratio_num Numerator of the sampling rate ratio
238  * @param ratio_den Denominator of the sampling rate ratio
239  * @param in_rate Input sampling rate rounded to the nearest integer (in Hz).
240  * @param out_rate Output sampling rate rounded to the nearest integer (in Hz).
241  */
242 int speex_resampler_set_rate_frac(SpeexResamplerState *st, 
243                                    spx_uint32_t ratio_num, 
244                                    spx_uint32_t ratio_den, 
245                                    spx_uint32_t in_rate, 
246                                    spx_uint32_t out_rate);
247
248 /** Get the current resampling ratio. This will be reduced to the least
249  * common denominator.
250  * @param st Resampler state
251  * @param ratio_num Numerator of the sampling rate ratio copied
252  * @param ratio_den Denominator of the sampling rate ratio copied
253  */
254 void speex_resampler_get_ratio(SpeexResamplerState *st, 
255                                spx_uint32_t *ratio_num, 
256                                spx_uint32_t *ratio_den);
257
258 /** Set (change) the conversion quality.
259  * @param st Resampler state
260  * @param quality Resampling quality between 0 and 10, where 0 has poor 
261  * quality and 10 has very high quality.
262  */
263 int speex_resampler_set_quality(SpeexResamplerState *st, 
264                                  int quality);
265
266 /** Get the conversion quality.
267  * @param st Resampler state
268  * @param quality Resampling quality between 0 and 10, where 0 has poor 
269  * quality and 10 has very high quality.
270  */
271 void speex_resampler_get_quality(SpeexResamplerState *st, 
272                                  int *quality);
273
274 /** Set (change) the input stride.
275  * @param st Resampler state
276  * @param stride Input stride
277  */
278 void speex_resampler_set_input_stride(SpeexResamplerState *st, 
279                                       spx_uint32_t stride);
280
281 /** Get the input stride.
282  * @param st Resampler state
283  * @param stride Input stride copied
284  */
285 void speex_resampler_get_input_stride(SpeexResamplerState *st, 
286                                       spx_uint32_t *stride);
287
288 /** Set (change) the output stride.
289  * @param st Resampler state
290  * @param stride Output stride
291  */
292 void speex_resample_set_output_stride(SpeexResamplerState *st, 
293                                       spx_uint32_t stride);
294
295 /** Get the output stride.
296  * @param st Resampler state copied
297  * @param stride Output stride
298  */
299 void speex_resample_get_output_stride(SpeexResamplerState *st, 
300                                       spx_uint32_t *stride);
301
302 /** Make sure that the first samples to go out of the resamplers don't have 
303  * leading zeros. This is only useful before starting to use a newly created 
304  * resampler. It is recommended to use that when resampling an audio file, as
305  * it will generate a file with the same length. For real-time processing,
306  * it is probably easier not to use this call (so that the output duration
307  * is the same for the first frame).
308  * @param st Resampler state
309  */
310 int speex_resampler_skip_zeros(SpeexResamplerState *st);
311
312 /** Reset a resampler so a new (unrelated) stream can be processed.
313  * @param st Resampler state
314  */
315 int speex_resampler_reset_mem(SpeexResamplerState *st);
316
317 #ifdef __cplusplus
318 }
319 #endif
320
321 #endif