Alexandre Savard | 0a32ed7 | 2012-08-07 19:26:46 -0400 | [diff] [blame] | 1 | /* Copyright (C) 2002-2006 Jean-Marc Valin*/ |
| 2 | /** |
| 3 | @file speex.h |
| 4 | @brief Describes the different modes of the codec |
| 5 | */ |
| 6 | /* |
| 7 | Redistribution and use in source and binary forms, with or without |
| 8 | modification, are permitted provided that the following conditions |
| 9 | are met: |
| 10 | |
| 11 | - Redistributions of source code must retain the above copyright |
| 12 | notice, this list of conditions and the following disclaimer. |
| 13 | |
| 14 | - Redistributions in binary form must reproduce the above copyright |
| 15 | notice, this list of conditions and the following disclaimer in the |
| 16 | documentation and/or other materials provided with the distribution. |
| 17 | |
| 18 | - Neither the name of the Xiph.org Foundation nor the names of its |
| 19 | contributors may be used to endorse or promote products derived from |
| 20 | this software without specific prior written permission. |
| 21 | |
| 22 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
| 23 | ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
| 24 | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
| 25 | A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR |
| 26 | CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, |
| 27 | EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, |
| 28 | PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR |
| 29 | PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF |
| 30 | LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING |
| 31 | NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS |
| 32 | SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| 33 | |
| 34 | */ |
| 35 | |
| 36 | #ifndef SPEEX_H |
| 37 | #define SPEEX_H |
| 38 | /** @defgroup Codec Speex encoder and decoder |
| 39 | * This is the Speex codec itself. |
| 40 | * @{ |
| 41 | */ |
| 42 | |
| 43 | #include "speex/speex_bits.h" |
| 44 | #include "speex/speex_types.h" |
| 45 | |
| 46 | #ifdef __cplusplus |
| 47 | extern "C" { |
| 48 | #endif |
| 49 | |
| 50 | /* Values allowed for *ctl() requests */ |
| 51 | |
| 52 | /** Set enhancement on/off (decoder only) */ |
| 53 | #define SPEEX_SET_ENH 0 |
| 54 | /** Get enhancement state (decoder only) */ |
| 55 | #define SPEEX_GET_ENH 1 |
| 56 | |
| 57 | /*Would be SPEEX_SET_FRAME_SIZE, but it's (currently) invalid*/ |
| 58 | /** Obtain frame size used by encoder/decoder */ |
| 59 | #define SPEEX_GET_FRAME_SIZE 3 |
| 60 | |
| 61 | /** Set quality value */ |
| 62 | #define SPEEX_SET_QUALITY 4 |
| 63 | /** Get current quality setting */ |
| 64 | /* #define SPEEX_GET_QUALITY 5 -- Doesn't make much sense, does it? */ |
| 65 | |
| 66 | /** Set sub-mode to use */ |
| 67 | #define SPEEX_SET_MODE 6 |
| 68 | /** Get current sub-mode in use */ |
| 69 | #define SPEEX_GET_MODE 7 |
| 70 | |
| 71 | /** Set low-band sub-mode to use (wideband only)*/ |
| 72 | #define SPEEX_SET_LOW_MODE 8 |
| 73 | /** Get current low-band mode in use (wideband only)*/ |
| 74 | #define SPEEX_GET_LOW_MODE 9 |
| 75 | |
| 76 | /** Set high-band sub-mode to use (wideband only)*/ |
| 77 | #define SPEEX_SET_HIGH_MODE 10 |
| 78 | /** Get current high-band mode in use (wideband only)*/ |
| 79 | #define SPEEX_GET_HIGH_MODE 11 |
| 80 | |
| 81 | /** Set VBR on (1) or off (0) */ |
| 82 | #define SPEEX_SET_VBR 12 |
| 83 | /** Get VBR status (1 for on, 0 for off) */ |
| 84 | #define SPEEX_GET_VBR 13 |
| 85 | |
| 86 | /** Set quality value for VBR encoding (0-10) */ |
| 87 | #define SPEEX_SET_VBR_QUALITY 14 |
| 88 | /** Get current quality value for VBR encoding (0-10) */ |
| 89 | #define SPEEX_GET_VBR_QUALITY 15 |
| 90 | |
| 91 | /** Set complexity of the encoder (0-10) */ |
| 92 | #define SPEEX_SET_COMPLEXITY 16 |
| 93 | /** Get current complexity of the encoder (0-10) */ |
| 94 | #define SPEEX_GET_COMPLEXITY 17 |
| 95 | |
| 96 | /** Set bit-rate used by the encoder (or lower) */ |
| 97 | #define SPEEX_SET_BITRATE 18 |
| 98 | /** Get current bit-rate used by the encoder or decoder */ |
| 99 | #define SPEEX_GET_BITRATE 19 |
| 100 | |
| 101 | /** Define a handler function for in-band Speex request*/ |
| 102 | #define SPEEX_SET_HANDLER 20 |
| 103 | |
| 104 | /** Define a handler function for in-band user-defined request*/ |
| 105 | #define SPEEX_SET_USER_HANDLER 22 |
| 106 | |
| 107 | /** Set sampling rate used in bit-rate computation */ |
| 108 | #define SPEEX_SET_SAMPLING_RATE 24 |
| 109 | /** Get sampling rate used in bit-rate computation */ |
| 110 | #define SPEEX_GET_SAMPLING_RATE 25 |
| 111 | |
| 112 | /** Reset the encoder/decoder memories to zero*/ |
| 113 | #define SPEEX_RESET_STATE 26 |
| 114 | |
| 115 | /** Get VBR info (mostly used internally) */ |
| 116 | #define SPEEX_GET_RELATIVE_QUALITY 29 |
| 117 | |
| 118 | /** Set VAD status (1 for on, 0 for off) */ |
| 119 | #define SPEEX_SET_VAD 30 |
| 120 | |
| 121 | /** Get VAD status (1 for on, 0 for off) */ |
| 122 | #define SPEEX_GET_VAD 31 |
| 123 | |
| 124 | /** Set Average Bit-Rate (ABR) to n bits per seconds */ |
| 125 | #define SPEEX_SET_ABR 32 |
| 126 | /** Get Average Bit-Rate (ABR) setting (in bps) */ |
| 127 | #define SPEEX_GET_ABR 33 |
| 128 | |
| 129 | /** Set DTX status (1 for on, 0 for off) */ |
| 130 | #define SPEEX_SET_DTX 34 |
| 131 | /** Get DTX status (1 for on, 0 for off) */ |
| 132 | #define SPEEX_GET_DTX 35 |
| 133 | |
| 134 | /** Set submode encoding in each frame (1 for yes, 0 for no, setting to no breaks the standard) */ |
| 135 | #define SPEEX_SET_SUBMODE_ENCODING 36 |
| 136 | /** Get submode encoding in each frame */ |
| 137 | #define SPEEX_GET_SUBMODE_ENCODING 37 |
| 138 | |
| 139 | /*#define SPEEX_SET_LOOKAHEAD 38*/ |
| 140 | /** Returns the lookahead used by Speex */ |
| 141 | #define SPEEX_GET_LOOKAHEAD 39 |
| 142 | |
| 143 | /** Sets tuning for packet-loss concealment (expected loss rate) */ |
| 144 | #define SPEEX_SET_PLC_TUNING 40 |
| 145 | /** Gets tuning for PLC */ |
| 146 | #define SPEEX_GET_PLC_TUNING 41 |
| 147 | |
| 148 | /** Sets the max bit-rate allowed in VBR mode */ |
| 149 | #define SPEEX_SET_VBR_MAX_BITRATE 42 |
| 150 | /** Gets the max bit-rate allowed in VBR mode */ |
| 151 | #define SPEEX_GET_VBR_MAX_BITRATE 43 |
| 152 | |
| 153 | /** Turn on/off input/output high-pass filtering */ |
| 154 | #define SPEEX_SET_HIGHPASS 44 |
| 155 | /** Get status of input/output high-pass filtering */ |
| 156 | #define SPEEX_GET_HIGHPASS 45 |
| 157 | |
| 158 | /** Get "activity level" of the last decoded frame, i.e. |
| 159 | how much damage we cause if we remove the frame */ |
| 160 | #define SPEEX_GET_ACTIVITY 47 |
| 161 | |
| 162 | |
| 163 | /* Preserving compatibility:*/ |
| 164 | /** Equivalent to SPEEX_SET_ENH */ |
| 165 | #define SPEEX_SET_PF 0 |
| 166 | /** Equivalent to SPEEX_GET_ENH */ |
| 167 | #define SPEEX_GET_PF 1 |
| 168 | |
| 169 | |
| 170 | |
| 171 | |
| 172 | /* Values allowed for mode queries */ |
| 173 | /** Query the frame size of a mode */ |
| 174 | #define SPEEX_MODE_FRAME_SIZE 0 |
| 175 | |
| 176 | /** Query the size of an encoded frame for a particular sub-mode */ |
| 177 | #define SPEEX_SUBMODE_BITS_PER_FRAME 1 |
| 178 | |
| 179 | |
| 180 | |
| 181 | /** Get major Speex version */ |
| 182 | #define SPEEX_LIB_GET_MAJOR_VERSION 1 |
| 183 | /** Get minor Speex version */ |
| 184 | #define SPEEX_LIB_GET_MINOR_VERSION 3 |
| 185 | /** Get micro Speex version */ |
| 186 | #define SPEEX_LIB_GET_MICRO_VERSION 5 |
| 187 | /** Get extra Speex version */ |
| 188 | #define SPEEX_LIB_GET_EXTRA_VERSION 7 |
| 189 | /** Get Speex version string */ |
| 190 | #define SPEEX_LIB_GET_VERSION_STRING 9 |
| 191 | |
| 192 | /*#define SPEEX_LIB_SET_ALLOC_FUNC 10 |
| 193 | #define SPEEX_LIB_GET_ALLOC_FUNC 11 |
| 194 | #define SPEEX_LIB_SET_FREE_FUNC 12 |
| 195 | #define SPEEX_LIB_GET_FREE_FUNC 13 |
| 196 | |
| 197 | #define SPEEX_LIB_SET_WARNING_FUNC 14 |
| 198 | #define SPEEX_LIB_GET_WARNING_FUNC 15 |
| 199 | #define SPEEX_LIB_SET_ERROR_FUNC 16 |
| 200 | #define SPEEX_LIB_GET_ERROR_FUNC 17 |
| 201 | */ |
| 202 | |
| 203 | /** Number of defined modes in Speex */ |
| 204 | #define SPEEX_NB_MODES 3 |
| 205 | |
| 206 | /** modeID for the defined narrowband mode */ |
| 207 | #define SPEEX_MODEID_NB 0 |
| 208 | |
| 209 | /** modeID for the defined wideband mode */ |
| 210 | #define SPEEX_MODEID_WB 1 |
| 211 | |
| 212 | /** modeID for the defined ultra-wideband mode */ |
| 213 | #define SPEEX_MODEID_UWB 2 |
| 214 | |
| 215 | struct SpeexMode; |
| 216 | |
| 217 | |
| 218 | /* Prototypes for mode function pointers */ |
| 219 | |
| 220 | /** Encoder state initialization function */ |
| 221 | typedef void *(*encoder_init_func)(const struct SpeexMode *mode); |
| 222 | |
| 223 | /** Encoder state destruction function */ |
| 224 | typedef void (*encoder_destroy_func)(void *st); |
| 225 | |
| 226 | /** Main encoding function */ |
| 227 | typedef int (*encode_func)(void *state, void *in, SpeexBits *bits); |
| 228 | |
| 229 | /** Function for controlling the encoder options */ |
| 230 | typedef int (*encoder_ctl_func)(void *state, int request, void *ptr); |
| 231 | |
| 232 | /** Decoder state initialization function */ |
| 233 | typedef void *(*decoder_init_func)(const struct SpeexMode *mode); |
| 234 | |
| 235 | /** Decoder state destruction function */ |
| 236 | typedef void (*decoder_destroy_func)(void *st); |
| 237 | |
| 238 | /** Main decoding function */ |
| 239 | typedef int (*decode_func)(void *state, SpeexBits *bits, void *out); |
| 240 | |
| 241 | /** Function for controlling the decoder options */ |
| 242 | typedef int (*decoder_ctl_func)(void *state, int request, void *ptr); |
| 243 | |
| 244 | |
| 245 | /** Query function for a mode */ |
| 246 | typedef int (*mode_query_func)(const void *mode, int request, void *ptr); |
| 247 | |
| 248 | /** Struct defining a Speex mode */ |
| 249 | typedef struct SpeexMode { |
| 250 | /** Pointer to the low-level mode data */ |
| 251 | const void *mode; |
| 252 | |
| 253 | /** Pointer to the mode query function */ |
| 254 | mode_query_func query; |
| 255 | |
| 256 | /** The name of the mode (you should not rely on this to identify the mode)*/ |
| 257 | const char *modeName; |
| 258 | |
| 259 | /**ID of the mode*/ |
| 260 | int modeID; |
| 261 | |
| 262 | /**Version number of the bitstream (incremented every time we break |
| 263 | bitstream compatibility*/ |
| 264 | int bitstream_version; |
| 265 | |
| 266 | /** Pointer to encoder initialization function */ |
| 267 | encoder_init_func enc_init; |
| 268 | |
| 269 | /** Pointer to encoder destruction function */ |
| 270 | encoder_destroy_func enc_destroy; |
| 271 | |
| 272 | /** Pointer to frame encoding function */ |
| 273 | encode_func enc; |
| 274 | |
| 275 | /** Pointer to decoder initialization function */ |
| 276 | decoder_init_func dec_init; |
| 277 | |
| 278 | /** Pointer to decoder destruction function */ |
| 279 | decoder_destroy_func dec_destroy; |
| 280 | |
| 281 | /** Pointer to frame decoding function */ |
| 282 | decode_func dec; |
| 283 | |
| 284 | /** ioctl-like requests for encoder */ |
| 285 | encoder_ctl_func enc_ctl; |
| 286 | |
| 287 | /** ioctl-like requests for decoder */ |
| 288 | decoder_ctl_func dec_ctl; |
| 289 | |
| 290 | } SpeexMode; |
| 291 | |
| 292 | /** |
| 293 | * Returns a handle to a newly created Speex encoder state structure. For now, |
| 294 | * the "mode" argument can be &nb_mode or &wb_mode . In the future, more modes |
| 295 | * may be added. Note that for now if you have more than one channels to |
| 296 | * encode, you need one state per channel. |
| 297 | * |
| 298 | * @param mode The mode to use (either speex_nb_mode or speex_wb.mode) |
| 299 | * @return A newly created encoder state or NULL if state allocation fails |
| 300 | */ |
| 301 | void *speex_encoder_init(const SpeexMode *mode); |
| 302 | |
| 303 | /** Frees all resources associated to an existing Speex encoder state. |
| 304 | * @param state Encoder state to be destroyed */ |
| 305 | void speex_encoder_destroy(void *state); |
| 306 | |
| 307 | /** Uses an existing encoder state to encode one frame of speech pointed to by |
| 308 | "in". The encoded bit-stream is saved in "bits". |
| 309 | @param state Encoder state |
| 310 | @param in Frame that will be encoded with a +-2^15 range. This data MAY be |
| 311 | overwritten by the encoder and should be considered uninitialised |
| 312 | after the call. |
| 313 | @param bits Bit-stream where the data will be written |
| 314 | @return 0 if frame needs not be transmitted (DTX only), 1 otherwise |
| 315 | */ |
| 316 | int speex_encode(void *state, float *in, SpeexBits *bits); |
| 317 | |
| 318 | /** Uses an existing encoder state to encode one frame of speech pointed to by |
| 319 | "in". The encoded bit-stream is saved in "bits". |
| 320 | @param state Encoder state |
| 321 | @param in Frame that will be encoded with a +-2^15 range |
| 322 | @param bits Bit-stream where the data will be written |
| 323 | @return 0 if frame needs not be transmitted (DTX only), 1 otherwise |
| 324 | */ |
| 325 | int speex_encode_int(void *state, spx_int16_t *in, SpeexBits *bits); |
| 326 | |
| 327 | /** Used like the ioctl function to control the encoder parameters |
| 328 | * |
| 329 | * @param state Encoder state |
| 330 | * @param request ioctl-type request (one of the SPEEX_* macros) |
| 331 | * @param ptr Data exchanged to-from function |
| 332 | * @return 0 if no error, -1 if request in unknown, -2 for invalid parameter |
| 333 | */ |
| 334 | int speex_encoder_ctl(void *state, int request, void *ptr); |
| 335 | |
| 336 | |
| 337 | /** Returns a handle to a newly created decoder state structure. For now, |
| 338 | * the mode argument can be &nb_mode or &wb_mode . In the future, more modes |
| 339 | * may be added. Note that for now if you have more than one channels to |
| 340 | * decode, you need one state per channel. |
| 341 | * |
| 342 | * @param mode Speex mode (one of speex_nb_mode or speex_wb_mode) |
| 343 | * @return A newly created decoder state or NULL if state allocation fails |
| 344 | */ |
| 345 | void *speex_decoder_init(const SpeexMode *mode); |
| 346 | |
| 347 | /** Frees all resources associated to an existing decoder state. |
| 348 | * |
| 349 | * @param state State to be destroyed |
| 350 | */ |
| 351 | void speex_decoder_destroy(void *state); |
| 352 | |
| 353 | /** Uses an existing decoder state to decode one frame of speech from |
| 354 | * bit-stream bits. The output speech is saved written to out. |
| 355 | * |
| 356 | * @param state Decoder state |
| 357 | * @param bits Bit-stream from which to decode the frame (NULL if the packet was lost) |
| 358 | * @param out Where to write the decoded frame |
| 359 | * @return return status (0 for no error, -1 for end of stream, -2 corrupt stream) |
| 360 | */ |
| 361 | int speex_decode(void *state, SpeexBits *bits, float *out); |
| 362 | |
| 363 | /** Uses an existing decoder state to decode one frame of speech from |
| 364 | * bit-stream bits. The output speech is saved written to out. |
| 365 | * |
| 366 | * @param state Decoder state |
| 367 | * @param bits Bit-stream from which to decode the frame (NULL if the packet was lost) |
| 368 | * @param out Where to write the decoded frame |
| 369 | * @return return status (0 for no error, -1 for end of stream, -2 corrupt stream) |
| 370 | */ |
| 371 | int speex_decode_int(void *state, SpeexBits *bits, spx_int16_t *out); |
| 372 | |
| 373 | /** Used like the ioctl function to control the encoder parameters |
| 374 | * |
| 375 | * @param state Decoder state |
| 376 | * @param request ioctl-type request (one of the SPEEX_* macros) |
| 377 | * @param ptr Data exchanged to-from function |
| 378 | * @return 0 if no error, -1 if request in unknown, -2 for invalid parameter |
| 379 | */ |
| 380 | int speex_decoder_ctl(void *state, int request, void *ptr); |
| 381 | |
| 382 | |
| 383 | /** Query function for mode information |
| 384 | * |
| 385 | * @param mode Speex mode |
| 386 | * @param request ioctl-type request (one of the SPEEX_* macros) |
| 387 | * @param ptr Data exchanged to-from function |
| 388 | * @return 0 if no error, -1 if request in unknown, -2 for invalid parameter |
| 389 | */ |
| 390 | int speex_mode_query(const SpeexMode *mode, int request, void *ptr); |
| 391 | |
| 392 | /** Functions for controlling the behavior of libspeex |
| 393 | * @param request ioctl-type request (one of the SPEEX_LIB_* macros) |
| 394 | * @param ptr Data exchanged to-from function |
| 395 | * @return 0 if no error, -1 if request in unknown, -2 for invalid parameter |
| 396 | */ |
| 397 | int speex_lib_ctl(int request, void *ptr); |
| 398 | |
| 399 | /** Default narrowband mode */ |
| 400 | extern const SpeexMode speex_nb_mode; |
| 401 | |
| 402 | /** Default wideband mode */ |
| 403 | extern const SpeexMode speex_wb_mode; |
| 404 | |
| 405 | /** Default "ultra-wideband" mode */ |
| 406 | extern const SpeexMode speex_uwb_mode; |
| 407 | |
| 408 | /** List of all modes available */ |
| 409 | extern const SpeexMode * const speex_mode_list[SPEEX_NB_MODES]; |
| 410 | |
| 411 | /** Obtain one of the modes available */ |
| 412 | const SpeexMode * speex_lib_get_mode (int mode); |
| 413 | |
| 414 | #ifndef WIN32 |
| 415 | /* We actually override the function in the narrowband case so that we can avoid linking in the wideband stuff */ |
| 416 | #define speex_lib_get_mode(mode) ((mode)==SPEEX_MODEID_NB ? &speex_nb_mode : speex_lib_get_mode (mode)) |
| 417 | #endif |
| 418 | |
| 419 | #ifdef __cplusplus |
| 420 | } |
| 421 | #endif |
| 422 | |
| 423 | /** @}*/ |
| 424 | #endif |