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