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 425