more doc
[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 #define spx_int16_t short
45 #ifdef FIXED_POINT
46 #define spx_word16_t short
47 #define spx_word32_t int
48 #else
49 #define spx_word16_t float
50 #define spx_word32_t float
51 #define MULT16_16(a,b) ((a)*(b))
52 #define PSHR32(a,b) (a)
53 #endif
54
55 #else
56
57 #include "speex/speex_types.h"
58
59 #endif
60
61 #ifdef __cplusplus
62 extern "C" {
63 #endif
64
65 #define SPEEX_RESAMPLER_QUALITY_MAX 10
66 #define SPEEX_RESAMPLER_QUALITY_MIN 0
67 #define SPEEX_RESAMPLER_QUALITY_DEFAULT 4
68 #define SPEEX_RESAMPLER_QUALITY_VOIP 3
69 #define SPEEX_RESAMPLER_QUALITY_DESKTOP 5
70    
71 struct SpeexResamplerState_;
72 typedef struct SpeexResamplerState_ SpeexResamplerState;
73
74 /** Create a new resampler with integer input and output rates.
75  * @param nb_channels Number of channels to be processed
76  * @param in_rate Input sampling rate (integer number of Hz).
77  * @param out_rate Output sampling rate (integer number of Hz).
78  * @param quality Resampling quality between 0 and 10, where 0 has poor quality
79  * and 10 has very high quality.
80  * @return Newly created resampler state
81  * @retval NULL Error: not enough memory
82  */
83 SpeexResamplerState *speex_resampler_init(int nb_channels, 
84                                           int in_rate, 
85                                           int out_rate, 
86                                           int quality);
87
88 /** Create a new resampler with fractional input/output rates. The sampling 
89  * rate ratio is an arbitrary rational number with both the numerator and 
90  * denominator being 32-bit integers.
91  * @param nb_channels Number of channels to be processed
92  * @param ratio_num Numerator of the sampling rate ratio
93  * @param ratio_den Denominator of the sampling rate ratio
94  * @param in_rate Input sampling rate rounded to the nearest integer (in Hz).
95  * @param out_rate Output sampling rate rounded to the nearest integer (in Hz).
96  * @param quality Resampling quality between 0 and 10, where 0 has poor quality
97  * and 10 has very high quality.
98  * @return Newly created resampler state
99  * @retval NULL Error: not enough memory
100  */
101 SpeexResamplerState *speex_resampler_init_frac(int nb_channels, 
102                                                int ratio_num, 
103                                                int ratio_den, 
104                                                int in_rate, 
105                                                int out_rate, 
106                                                int quality);
107
108 /** Destroy a resampler state.
109  * @param st Resampler state
110  */
111 void speex_resampler_destroy(SpeexResamplerState *st);
112
113 /** Resample a float array. The input and output buffers must *not* overlap.
114  * @param st Resampler state
115  * @param channel_index Index of the channel to process for the multi-channel 
116  * base (0 otherwise)
117  * @param in Input buffer
118  * @param in_len Number of input samples in the input buffer. Returns the 
119  * number of samples processed
120  * @param out Output buffer
121  * @param out_len Size of the output buffer. Returns the number of samples written
122  */
123 void speex_resampler_process_float(SpeexResamplerState *st, 
124                                    int channel_index, 
125                                    const float *in, 
126                                    int *in_len, 
127                                    float *out, 
128                                    int *out_len);
129
130 /** Resample an int array. The input and output buffers must *not* overlap.
131  * @param st Resampler state
132  * @param channel_index Index of the channel to process for the multi-channel 
133  * base (0 otherwise)
134  * @param in Input buffer
135  * @param in_len Number of input samples in the input buffer. Returns the number
136  * of samples processed
137  * @param out Output buffer
138  * @param out_len Size of the output buffer. Returns the number of samples written
139  */
140 void speex_resampler_process_int(SpeexResamplerState *st, 
141                                  int channel_index, 
142                                  const spx_int16_t *in, 
143                                  int *in_len, 
144                                  spx_int16_t *out, 
145                                  int *out_len);
146
147 /** Resample an interleaved float array. The input and output buffers must *not* overlap.
148  * @param st Resampler state
149  * @param in Input buffer
150  * @param in_len Number of input samples in the input buffer. Returns the number
151  * of samples processed. This is all per-channel.
152  * @param out Output buffer
153  * @param out_len Size of the output buffer. Returns the number of samples written.
154  * This is all per-channel.
155  */
156 void speex_resampler_process_interleaved_float(SpeexResamplerState *st, 
157                                                const float *in, 
158                                                int *in_len, 
159                                                float *out, 
160                                                int *out_len);
161
162 /** Resample an interleaved int array. The input and output buffers must *not* overlap.
163  * @param st Resampler state
164  * @param in Input buffer
165  * @param in_len Number of input samples in the input buffer. Returns the number
166  * of samples processed. This is all per-channel.
167  * @param out Output buffer
168  * @param out_len Size of the output buffer. Returns the number of samples written.
169  * This is all per-channel.
170  */
171 void speex_resampler_process_interleaved_int(SpeexResamplerState *st, 
172                                              const spx_int16_t *in, 
173                                              int *in_len, 
174                                              spx_int16_t *out, 
175                                              int *out_len);
176
177 /** Set (change) the input/output sampling rates (integer value).
178  * @param st Resampler state
179  * @param in_rate Input sampling rate (integer number of Hz).
180  * @param out_rate Output sampling rate (integer number of Hz).
181  */
182 void speex_resampler_set_rate(SpeexResamplerState *st, 
183                               int in_rate, 
184                               int out_rate);
185
186 /** Set (change) the input/output sampling rates and resampling ratio 
187  * (fractional values in Hz supported).
188  * @param st Resampler state
189  * @param ratio_num Numerator of the sampling rate ratio
190  * @param ratio_den Denominator of the sampling rate ratio
191  * @param in_rate Input sampling rate rounded to the nearest integer (in Hz).
192  * @param out_rate Output sampling rate rounded to the nearest integer (in Hz).
193  */
194 void speex_resampler_set_rate_frac(SpeexResamplerState *st, 
195                                    int ratio_num, 
196                                    int ratio_den, 
197                                    int in_rate, 
198                                    int out_rate);
199
200 /** Set (change) the conversion quality.
201  * @param st Resampler state
202  * @param quality Resampling quality between 0 and 10, where 0 has poor 
203  * quality and 10 has very high quality.
204  */
205 void speex_resampler_set_quality(SpeexResamplerState *st, 
206                                  int quality);
207
208 /** Set (change) the input stride.
209  * @param st Resampler state
210  * @param stride Input stride
211  */
212 void speex_resampler_set_input_stride(SpeexResamplerState *st, 
213                                       int stride);
214
215 /** Set (change) the output stride.
216  * @param st Resampler state
217  * @param stride Output stride
218  */
219 void speex_resample_set_output_stride(SpeexResamplerState *st, 
220                                       int stride);
221
222 /** Make sure that the first samples to go out of the resamplers don't have 
223  * leading zeros. This is only useful before starting to use a newly created 
224  * resampler. It is recommended to use that when resampling an audio file, as
225  * it will generate a file with the same length. For real-time processing,
226  * it is probably easier not to use this call (so that the output duration
227  * is the same for the first frame).
228  * @param st Resampler state
229  */
230 void speex_resampler_skip_zeros(SpeexResamplerState *st);
231
232 /** Reset a resampler so a new (unrelated) stream can be processed.
233  * @param st Resampler state
234  */
235 void speex_resampler_reset_mem(SpeexResamplerState *st);
236
237 #ifdef __cplusplus
238 }
239 #endif
240
241 #endif