speex_resampler.h

00001 /* Copyright (C) 2007 Jean-Marc Valin
00002       
00003    File: speex_resampler.h
00004    Resampling code
00005       
00006    The design goals of this code are:
00007       - Very fast algorithm
00008       - Low memory requirement
00009       - Good *perceptual* quality (and not best SNR)
00010 
00011    Redistribution and use in source and binary forms, with or without
00012    modification, are permitted provided that the following conditions are
00013    met:
00014 
00015    1. Redistributions of source code must retain the above copyright notice,
00016    this list of conditions and the following disclaimer.
00017 
00018    2. Redistributions in binary form must reproduce the above copyright
00019    notice, this list of conditions and the following disclaimer in the
00020    documentation and/or other materials provided with the distribution.
00021 
00022    3. The name of the author may not be used to endorse or promote products
00023    derived from this software without specific prior written permission.
00024 
00025    THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
00026    IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
00027    OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00028    DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
00029    INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00030    (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
00031    SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
00032    HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
00033    STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
00034    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00035    POSSIBILITY OF SUCH DAMAGE.
00036 */
00037 
00038 
00039 #ifndef SPEEX_RESAMPLER_H
00040 #define SPEEX_RESAMPLER_H
00041 
00042 #ifdef OUTSIDE_SPEEX
00043 
00044 /********* WARNING: MENTAL SANITY ENDS HERE *************/
00045 
00046 /* If the resampler is defined outside of Speex, we change the symbol names so that 
00047    there won't be any clash if linking with Speex later on. */
00048 
00049 /* #define RANDOM_PREFIX your software name here */
00050 #ifndef RANDOM_PREFIX
00051 #error "Please define RANDOM_PREFIX (above) to something specific to your project to prevent symbol name clashes"
00052 #endif
00053 
00054 #define CAT_PREFIX2(a,b) a ## b
00055 #define CAT_PREFIX(a,b) CAT_PREFIX2(a, b)
00056       
00057 #define speex_resampler_init CAT_PREFIX(RANDOM_PREFIX,_resampler_init)
00058 #define speex_resampler_init_frac CAT_PREFIX(RANDOM_PREFIX,_resampler_init_frac)
00059 #define speex_resampler_destroy CAT_PREFIX(RANDOM_PREFIX,_resampler_destroy)
00060 #define speex_resampler_process_float CAT_PREFIX(RANDOM_PREFIX,_resampler_process_float)
00061 #define speex_resampler_process_int CAT_PREFIX(RANDOM_PREFIX,_resampler_process_int)
00062 #define speex_resampler_process_interleaved_float CAT_PREFIX(RANDOM_PREFIX,_resampler_process_interleaved_float)
00063 #define speex_resampler_process_interleaved_int CAT_PREFIX(RANDOM_PREFIX,_resampler_process_interleaved_int)
00064 #define speex_resampler_set_rate CAT_PREFIX(RANDOM_PREFIX,_resampler_set_rate)
00065 #define speex_resampler_get_rate CAT_PREFIX(RANDOM_PREFIX,_resampler_get_rate)
00066 #define speex_resampler_set_rate_frac CAT_PREFIX(RANDOM_PREFIX,_resampler_set_rate_frac)
00067 #define speex_resampler_get_ratio CAT_PREFIX(RANDOM_PREFIX,_resampler_get_ratio)
00068 #define speex_resampler_set_quality CAT_PREFIX(RANDOM_PREFIX,_resampler_set_quality)
00069 #define speex_resampler_get_quality CAT_PREFIX(RANDOM_PREFIX,_resampler_get_quality)
00070 #define speex_resampler_set_input_stride CAT_PREFIX(RANDOM_PREFIX,_resampler_set_input_stride)
00071 #define speex_resampler_get_input_stride CAT_PREFIX(RANDOM_PREFIX,_resampler_get_input_stride)
00072 #define speex_resampler_set_output_stride CAT_PREFIX(RANDOM_PREFIX,_resampler_set_output_stride)
00073 #define speex_resampler_get_output_stride CAT_PREFIX(RANDOM_PREFIX,_resampler_get_output_stride)
00074 #define speex_resampler_skip_zeros CAT_PREFIX(RANDOM_PREFIX,_resampler_skip_zeros)
00075 #define speex_resampler_reset_mem CAT_PREFIX(RANDOM_PREFIX,_resampler_reset_mem)
00076 #define speex_resampler_strerror CAT_PREFIX(RANDOM_PREFIX,_resampler_strerror)
00077 
00078 #define spx_int16_t short
00079 #define spx_int32_t int
00080 #define spx_uint16_t unsigned short
00081 #define spx_uint32_t unsigned int
00082       
00083 #else /* OUTSIDE_SPEEX */
00084 
00085 #include "speex/speex_types.h"
00086 
00087 #endif /* OUTSIDE_SPEEX */
00088 
00089 #ifdef __cplusplus
00090 extern "C" {
00091 #endif
00092 
00093 #define SPEEX_RESAMPLER_QUALITY_MAX 10
00094 #define SPEEX_RESAMPLER_QUALITY_MIN 0
00095 #define SPEEX_RESAMPLER_QUALITY_DEFAULT 4
00096 #define SPEEX_RESAMPLER_QUALITY_VOIP 3
00097 #define SPEEX_RESAMPLER_QUALITY_DESKTOP 5
00098 
00099 enum {
00100    RESAMPLER_ERR_SUCCESS         = 0,
00101    RESAMPLER_ERR_ALLOC_FAILED    = 1,
00102    RESAMPLER_ERR_BAD_STATE       = 2,
00103    RESAMPLER_ERR_INVALID_ARG     = 3,
00104    RESAMPLER_ERR_PTR_OVERLAP     = 4,
00105    
00106    RESAMPLER_ERR_MAX_ERROR
00107 };
00108 
00109 struct SpeexResamplerState_;
00110 typedef struct SpeexResamplerState_ SpeexResamplerState;
00111 
00112 /** Create a new resampler with integer input and output rates.
00113  * @param nb_channels Number of channels to be processed
00114  * @param in_rate Input sampling rate (integer number of Hz).
00115  * @param out_rate Output sampling rate (integer number of Hz).
00116  * @param quality Resampling quality between 0 and 10, where 0 has poor quality
00117  * and 10 has very high quality.
00118  * @return Newly created resampler state
00119  * @retval NULL Error: not enough memory
00120  */
00121 SpeexResamplerState *speex_resampler_init(spx_uint32_t nb_channels, 
00122                                           spx_uint32_t in_rate, 
00123                                           spx_uint32_t out_rate, 
00124                                           int quality,
00125                                           int *err);
00126 
00127 /** Create a new resampler with fractional input/output rates. The sampling 
00128  * rate ratio is an arbitrary rational number with both the numerator and 
00129  * denominator being 32-bit integers.
00130  * @param nb_channels Number of channels to be processed
00131  * @param ratio_num Numerator of the sampling rate ratio
00132  * @param ratio_den Denominator of the sampling rate ratio
00133  * @param in_rate Input sampling rate rounded to the nearest integer (in Hz).
00134  * @param out_rate Output sampling rate rounded to the nearest integer (in Hz).
00135  * @param quality Resampling quality between 0 and 10, where 0 has poor quality
00136  * and 10 has very high quality.
00137  * @return Newly created resampler state
00138  * @retval NULL Error: not enough memory
00139  */
00140 SpeexResamplerState *speex_resampler_init_frac(spx_uint32_t nb_channels, 
00141                                                spx_uint32_t ratio_num, 
00142                                                spx_uint32_t ratio_den, 
00143                                                spx_uint32_t in_rate, 
00144                                                spx_uint32_t out_rate, 
00145                                                int quality,
00146                                                int *err);
00147 
00148 /** Destroy a resampler state.
00149  * @param st Resampler state
00150  */
00151 void speex_resampler_destroy(SpeexResamplerState *st);
00152 
00153 /** Resample a float array. The input and output buffers must *not* overlap.
00154  * @param st Resampler state
00155  * @param channel_index Index of the channel to process for the multi-channel 
00156  * base (0 otherwise)
00157  * @param in Input buffer
00158  * @param in_len Number of input samples in the input buffer. Returns the 
00159  * number of samples processed
00160  * @param out Output buffer
00161  * @param out_len Size of the output buffer. Returns the number of samples written
00162  */
00163 int speex_resampler_process_float(SpeexResamplerState *st, 
00164                                    spx_uint32_t channel_index, 
00165                                    const float *in, 
00166                                    spx_uint32_t *in_len, 
00167                                    float *out, 
00168                                    spx_uint32_t *out_len);
00169 
00170 /** Resample an int array. The input and output buffers must *not* overlap.
00171  * @param st Resampler state
00172  * @param channel_index Index of the channel to process for the multi-channel 
00173  * base (0 otherwise)
00174  * @param in Input buffer
00175  * @param in_len Number of input samples in the input buffer. Returns the number
00176  * of samples processed
00177  * @param out Output buffer
00178  * @param out_len Size of the output buffer. Returns the number of samples written
00179  */
00180 int speex_resampler_process_int(SpeexResamplerState *st, 
00181                                  spx_uint32_t channel_index, 
00182                                  const spx_int16_t *in, 
00183                                  spx_uint32_t *in_len, 
00184                                  spx_int16_t *out, 
00185                                  spx_uint32_t *out_len);
00186 
00187 /** Resample an interleaved float array. The input and output buffers must *not* overlap.
00188  * @param st Resampler state
00189  * @param in Input buffer
00190  * @param in_len Number of input samples in the input buffer. Returns the number
00191  * of samples processed. This is all per-channel.
00192  * @param out Output buffer
00193  * @param out_len Size of the output buffer. Returns the number of samples written.
00194  * This is all per-channel.
00195  */
00196 int speex_resampler_process_interleaved_float(SpeexResamplerState *st, 
00197                                                const float *in, 
00198                                                spx_uint32_t *in_len, 
00199                                                float *out, 
00200                                                spx_uint32_t *out_len);
00201 
00202 /** Resample an interleaved int array. The input and output buffers must *not* overlap.
00203  * @param st Resampler state
00204  * @param in Input buffer
00205  * @param in_len Number of input samples in the input buffer. Returns the number
00206  * of samples processed. This is all per-channel.
00207  * @param out Output buffer
00208  * @param out_len Size of the output buffer. Returns the number of samples written.
00209  * This is all per-channel.
00210  */
00211 int speex_resampler_process_interleaved_int(SpeexResamplerState *st, 
00212                                              const spx_int16_t *in, 
00213                                              spx_uint32_t *in_len, 
00214                                              spx_int16_t *out, 
00215                                              spx_uint32_t *out_len);
00216 
00217 /** Set (change) the input/output sampling rates (integer value).
00218  * @param st Resampler state
00219  * @param in_rate Input sampling rate (integer number of Hz).
00220  * @param out_rate Output sampling rate (integer number of Hz).
00221  */
00222 int speex_resampler_set_rate(SpeexResamplerState *st, 
00223                               spx_uint32_t in_rate, 
00224                               spx_uint32_t out_rate);
00225 
00226 /** Get the current input/output sampling rates (integer value).
00227  * @param st Resampler state
00228  * @param in_rate Input sampling rate (integer number of Hz) copied.
00229  * @param out_rate Output sampling rate (integer number of Hz) copied.
00230  */
00231 void speex_resampler_get_rate(SpeexResamplerState *st, 
00232                               spx_uint32_t *in_rate, 
00233                               spx_uint32_t *out_rate);
00234 
00235 /** Set (change) the input/output sampling rates and resampling ratio 
00236  * (fractional values in Hz supported).
00237  * @param st Resampler state
00238  * @param ratio_num Numerator of the sampling rate ratio
00239  * @param ratio_den Denominator of the sampling rate ratio
00240  * @param in_rate Input sampling rate rounded to the nearest integer (in Hz).
00241  * @param out_rate Output sampling rate rounded to the nearest integer (in Hz).
00242  */
00243 int speex_resampler_set_rate_frac(SpeexResamplerState *st, 
00244                                    spx_uint32_t ratio_num, 
00245                                    spx_uint32_t ratio_den, 
00246                                    spx_uint32_t in_rate, 
00247                                    spx_uint32_t out_rate);
00248 
00249 /** Get the current resampling ratio. This will be reduced to the least
00250  * common denominator.
00251  * @param st Resampler state
00252  * @param ratio_num Numerator of the sampling rate ratio copied
00253  * @param ratio_den Denominator of the sampling rate ratio copied
00254  */
00255 void speex_resampler_get_ratio(SpeexResamplerState *st, 
00256                                spx_uint32_t *ratio_num, 
00257                                spx_uint32_t *ratio_den);
00258 
00259 /** Set (change) the conversion quality.
00260  * @param st Resampler state
00261  * @param quality Resampling quality between 0 and 10, where 0 has poor 
00262  * quality and 10 has very high quality.
00263  */
00264 int speex_resampler_set_quality(SpeexResamplerState *st, 
00265                                  int quality);
00266 
00267 /** Get the conversion quality.
00268  * @param st Resampler state
00269  * @param quality Resampling quality between 0 and 10, where 0 has poor 
00270  * quality and 10 has very high quality.
00271  */
00272 void speex_resampler_get_quality(SpeexResamplerState *st, 
00273                                  int *quality);
00274 
00275 /** Set (change) the input stride.
00276  * @param st Resampler state
00277  * @param stride Input stride
00278  */
00279 void speex_resampler_set_input_stride(SpeexResamplerState *st, 
00280                                       spx_uint32_t stride);
00281 
00282 /** Get the input stride.
00283  * @param st Resampler state
00284  * @param stride Input stride copied
00285  */
00286 void speex_resampler_get_input_stride(SpeexResamplerState *st, 
00287                                       spx_uint32_t *stride);
00288 
00289 /** Set (change) the output stride.
00290  * @param st Resampler state
00291  * @param stride Output stride
00292  */
00293 void speex_resampler_set_output_stride(SpeexResamplerState *st, 
00294                                       spx_uint32_t stride);
00295 
00296 /** Get the output stride.
00297  * @param st Resampler state copied
00298  * @param stride Output stride
00299  */
00300 void speex_resampler_get_output_stride(SpeexResamplerState *st, 
00301                                       spx_uint32_t *stride);
00302 
00303 /** Make sure that the first samples to go out of the resamplers don't have 
00304  * leading zeros. This is only useful before starting to use a newly created 
00305  * resampler. It is recommended to use that when resampling an audio file, as
00306  * it will generate a file with the same length. For real-time processing,
00307  * it is probably easier not to use this call (so that the output duration
00308  * is the same for the first frame).
00309  * @param st Resampler state
00310  */
00311 int speex_resampler_skip_zeros(SpeexResamplerState *st);
00312 
00313 /** Reset a resampler so a new (unrelated) stream can be processed.
00314  * @param st Resampler state
00315  */
00316 int speex_resampler_reset_mem(SpeexResamplerState *st);
00317 
00318 /** Returns the English meaning for an error code
00319  * @param err Error code
00320  * @return English string
00321  */
00322 const char *speex_resampler_strerror(int err);
00323 
00324 #ifdef __cplusplus
00325 }
00326 #endif
00327 
00328 #endif