Preventing symbol clashes in case the resampler is copied
[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 */
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 speex_resampler_init RANDOM_PREFIX ## _resampler_init
55 #define speex_resampler_init_frac RANDOM_PREFIX ## _resampler_init_frac
56 #define speex_resampler_destroy RANDOM_PREFIX ## _resampler_destroy
57 #define speex_resampler_process_float RANDOM_PREFIX ## _resampler_process_float
58 #define speex_resampler_process_int RANDOM_PREFIX ## _resampler_process_int
59 #define speex_resampler_process_interleaved_float RANDOM_PREFIX ## _resampler_process_interleaved_float
60 #define speex_resampler_process_interleaved_int RANDOM_PREFIX ## _resampler_process_interleaved_int
61 #define speex_resampler_set_rate RANDOM_PREFIX ## _resampler_set_rate
62 #define speex_resampler_get_rate RANDOM_PREFIX ## _resampler_get_rate
63 #define speex_resampler_set_rate_frac RANDOM_PREFIX ## _resampler_set_rate_frac
64 #define speex_resampler_get_ratio RANDOM_PREFIX ## _resampler_get_ratio
65 #define speex_resampler_set_quality RANDOM_PREFIX ## _resampler_set_quality
66 #define speex_resampler_get_quality RANDOM_PREFIX ## _resampler_get_quality
67 #define speex_resampler_set_input_stride RANDOM_PREFIX ## _resampler_set_input_stride
68 #define speex_resampler_get_input_stride RANDOM_PREFIX ## _resampler_get_input_stride
69 #define speex_resample_set_output_stride RANDOM_PREFIX ## _resample_set_output_stride
70 #define speex_resample_get_output_stride RANDOM_PREFIX ## _resample_get_output_stride
71 #define speex_resampler_skip_zeros RANDOM_PREFIX ## _resampler_skip_zeros
72 #define speex_resampler_reset_mem RANDOM_PREFIX ## _resampler_reset_mem
73
74 #define spx_int16_t short
75
76 #ifdef FIXED_POINT
77 #define spx_word16_t short
78 #define spx_word32_t int
79
80 #else /* FIXED_POINT */
81
82 #define spx_word16_t float
83 #define spx_word32_t float
84 #define MULT16_16(a,b) ((a)*(b))
85 #define MULT16_32_Q15(a,b) ((a)*(b))
86 #define PSHR32(a,b) (a)
87 #endif /* FIXED_POINT */
88
89 #else /* OUTSIDE_SPEEX */
90
91 #include "speex/speex_types.h"
92
93 #endif /* OUTSIDE_SPEEX */
94
95 #ifdef __cplusplus
96 extern "C" {
97 #endif
98
99 #define SPEEX_RESAMPLER_QUALITY_MAX 10
100 #define SPEEX_RESAMPLER_QUALITY_MIN 0
101 #define SPEEX_RESAMPLER_QUALITY_DEFAULT 4
102 #define SPEEX_RESAMPLER_QUALITY_VOIP 3
103 #define SPEEX_RESAMPLER_QUALITY_DESKTOP 5
104    
105 struct SpeexResamplerState_;
106 typedef struct SpeexResamplerState_ SpeexResamplerState;
107
108 /** Create a new resampler with integer input and output rates.
109  * @param nb_channels Number of channels to be processed
110  * @param in_rate Input sampling rate (integer number of Hz).
111  * @param out_rate Output sampling rate (integer number of Hz).
112  * @param quality Resampling quality between 0 and 10, where 0 has poor quality
113  * and 10 has very high quality.
114  * @return Newly created resampler state
115  * @retval NULL Error: not enough memory
116  */
117 SpeexResamplerState *speex_resampler_init(int nb_channels, 
118                                           int in_rate, 
119                                           int out_rate, 
120                                           int quality);
121
122 /** Create a new resampler with fractional input/output rates. The sampling 
123  * rate ratio is an arbitrary rational number with both the numerator and 
124  * denominator being 32-bit integers.
125  * @param nb_channels Number of channels to be processed
126  * @param ratio_num Numerator of the sampling rate ratio
127  * @param ratio_den Denominator of the sampling rate ratio
128  * @param in_rate Input sampling rate rounded to the nearest integer (in Hz).
129  * @param out_rate Output sampling rate rounded to the nearest integer (in Hz).
130  * @param quality Resampling quality between 0 and 10, where 0 has poor quality
131  * and 10 has very high quality.
132  * @return Newly created resampler state
133  * @retval NULL Error: not enough memory
134  */
135 SpeexResamplerState *speex_resampler_init_frac(int nb_channels, 
136                                                int ratio_num, 
137                                                int ratio_den, 
138                                                int in_rate, 
139                                                int out_rate, 
140                                                int quality);
141
142 /** Destroy a resampler state.
143  * @param st Resampler state
144  */
145 void speex_resampler_destroy(SpeexResamplerState *st);
146
147 /** Resample a float array. The input and output buffers must *not* overlap.
148  * @param st Resampler state
149  * @param channel_index Index of the channel to process for the multi-channel 
150  * base (0 otherwise)
151  * @param in Input buffer
152  * @param in_len Number of input samples in the input buffer. Returns the 
153  * number of samples processed
154  * @param out Output buffer
155  * @param out_len Size of the output buffer. Returns the number of samples written
156  */
157 void speex_resampler_process_float(SpeexResamplerState *st, 
158                                    int channel_index, 
159                                    const float *in, 
160                                    int *in_len, 
161                                    float *out, 
162                                    int *out_len);
163
164 /** Resample an int array. The input and output buffers must *not* overlap.
165  * @param st Resampler state
166  * @param channel_index Index of the channel to process for the multi-channel 
167  * base (0 otherwise)
168  * @param in Input buffer
169  * @param in_len Number of input samples in the input buffer. Returns the number
170  * of samples processed
171  * @param out Output buffer
172  * @param out_len Size of the output buffer. Returns the number of samples written
173  */
174 void speex_resampler_process_int(SpeexResamplerState *st, 
175                                  int channel_index, 
176                                  const spx_int16_t *in, 
177                                  int *in_len, 
178                                  spx_int16_t *out, 
179                                  int *out_len);
180
181 /** Resample an interleaved float array. The input and output buffers must *not* overlap.
182  * @param st Resampler state
183  * @param in Input buffer
184  * @param in_len Number of input samples in the input buffer. Returns the number
185  * of samples processed. This is all per-channel.
186  * @param out Output buffer
187  * @param out_len Size of the output buffer. Returns the number of samples written.
188  * This is all per-channel.
189  */
190 void speex_resampler_process_interleaved_float(SpeexResamplerState *st, 
191                                                const float *in, 
192                                                int *in_len, 
193                                                float *out, 
194                                                int *out_len);
195
196 /** Resample an interleaved int array. The input and output buffers must *not* overlap.
197  * @param st Resampler state
198  * @param in Input buffer
199  * @param in_len Number of input samples in the input buffer. Returns the number
200  * of samples processed. This is all per-channel.
201  * @param out Output buffer
202  * @param out_len Size of the output buffer. Returns the number of samples written.
203  * This is all per-channel.
204  */
205 void speex_resampler_process_interleaved_int(SpeexResamplerState *st, 
206                                              const spx_int16_t *in, 
207                                              int *in_len, 
208                                              spx_int16_t *out, 
209                                              int *out_len);
210
211 /** Set (change) the input/output sampling rates (integer value).
212  * @param st Resampler state
213  * @param in_rate Input sampling rate (integer number of Hz).
214  * @param out_rate Output sampling rate (integer number of Hz).
215  */
216 void speex_resampler_set_rate(SpeexResamplerState *st, 
217                               int in_rate, 
218                               int out_rate);
219
220 /** Get the current input/output sampling rates (integer value).
221  * @param st Resampler state
222  * @param in_rate Input sampling rate (integer number of Hz) copied.
223  * @param out_rate Output sampling rate (integer number of Hz) copied.
224  */
225 void speex_resampler_get_rate(SpeexResamplerState *st, 
226                               int *in_rate, 
227                               int *out_rate);
228
229 /** Set (change) the input/output sampling rates and resampling ratio 
230  * (fractional values in Hz supported).
231  * @param st Resampler state
232  * @param ratio_num Numerator of the sampling rate ratio
233  * @param ratio_den Denominator of the sampling rate ratio
234  * @param in_rate Input sampling rate rounded to the nearest integer (in Hz).
235  * @param out_rate Output sampling rate rounded to the nearest integer (in Hz).
236  */
237 void speex_resampler_set_rate_frac(SpeexResamplerState *st, 
238                                    int ratio_num, 
239                                    int ratio_den, 
240                                    int in_rate, 
241                                    int out_rate);
242
243 /** Get the current resampling ratio. This will be reduced to the least
244  * common denominator.
245  * @param st Resampler state
246  * @param ratio_num Numerator of the sampling rate ratio copied
247  * @param ratio_den Denominator of the sampling rate ratio copied
248  */
249 void speex_resampler_get_ratio(SpeexResamplerState *st, 
250                                    int *ratio_num, 
251                                    int *ratio_den);
252
253 /** Set (change) the conversion quality.
254  * @param st Resampler state
255  * @param quality Resampling quality between 0 and 10, where 0 has poor 
256  * quality and 10 has very high quality.
257  */
258 void speex_resampler_set_quality(SpeexResamplerState *st, 
259                                  int quality);
260
261 /** Get the conversion quality.
262  * @param st Resampler state
263  * @param quality Resampling quality between 0 and 10, where 0 has poor 
264  * quality and 10 has very high quality.
265  */
266 void speex_resampler_get_quality(SpeexResamplerState *st, 
267                                  int *quality);
268
269 /** Set (change) the input stride.
270  * @param st Resampler state
271  * @param stride Input stride
272  */
273 void speex_resampler_set_input_stride(SpeexResamplerState *st, 
274                                       int stride);
275
276 /** Get the input stride.
277  * @param st Resampler state
278  * @param stride Input stride copied
279  */
280 void speex_resampler_get_input_stride(SpeexResamplerState *st, 
281                                       int *stride);
282
283 /** Set (change) the output stride.
284  * @param st Resampler state
285  * @param stride Output stride
286  */
287 void speex_resample_set_output_stride(SpeexResamplerState *st, 
288                                       int stride);
289
290 /** Get the output stride.
291  * @param st Resampler state copied
292  * @param stride Output stride
293  */
294 void speex_resample_get_output_stride(SpeexResamplerState *st, 
295                                       int *stride);
296
297 /** Make sure that the first samples to go out of the resamplers don't have 
298  * leading zeros. This is only useful before starting to use a newly created 
299  * resampler. It is recommended to use that when resampling an audio file, as
300  * it will generate a file with the same length. For real-time processing,
301  * it is probably easier not to use this call (so that the output duration
302  * is the same for the first frame).
303  * @param st Resampler state
304  */
305 void speex_resampler_skip_zeros(SpeexResamplerState *st);
306
307 /** Reset a resampler so a new (unrelated) stream can be processed.
308  * @param st Resampler state
309  */
310 void speex_resampler_reset_mem(SpeexResamplerState *st);
311
312 #ifdef __cplusplus
313 }
314 #endif
315
316 #endif