1 /* Copyright (C) 2002 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 39 #include "speex_bits.h" 40 #include "speex_types.h" 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 /* Values allowed for *ctl() requests */ 47 48 /** Set enhancement on/off (decoder only) */ 49 #define SPEEX_SET_ENH 0 50 /** Get enhancement state (decoder only) */ 51 #define SPEEX_GET_ENH 1 52 53 /*Would be SPEEX_SET_FRAME_SIZE, but it's (currently) invalid*/ 54 /** Obtain frame size used by encoder/decoder */ 55 #define SPEEX_GET_FRAME_SIZE 3 56 57 /** Set quality value */ 58 #define SPEEX_SET_QUALITY 4 59 /** Get current quality setting */ 60 /* #define SPEEX_GET_QUALITY 5 -- Doesn't make much sense, does it? */ 61 62 /** Set sub-mode to use */ 63 #define SPEEX_SET_MODE 6 64 /** Get current sub-mode in use */ 65 #define SPEEX_GET_MODE 7 66 67 /** Set low-band sub-mode to use (wideband only)*/ 68 #define SPEEX_SET_LOW_MODE 8 69 /** Get current low-band mode in use (wideband only)*/ 70 #define SPEEX_GET_LOW_MODE 9 71 72 /** Set high-band sub-mode to use (wideband only)*/ 73 #define SPEEX_SET_HIGH_MODE 10 74 /** Get current high-band mode in use (wideband only)*/ 75 #define SPEEX_GET_HIGH_MODE 11 76 77 /** Set VBR on (1) or off (0) */ 78 #define SPEEX_SET_VBR 12 79 /** Get VBR status (1 for on, 0 for off) */ 80 #define SPEEX_GET_VBR 13 81 82 /** Set quality value for VBR encoding (0-10) */ 83 #define SPEEX_SET_VBR_QUALITY 14 84 /** Get current quality value for VBR encoding (0-10) */ 85 #define SPEEX_GET_VBR_QUALITY 15 86 87 /** Set complexity of the encoder (0-10) */ 88 #define SPEEX_SET_COMPLEXITY 16 89 /** Get current complexity of the encoder (0-10) */ 90 #define SPEEX_GET_COMPLEXITY 17 91 92 /** Set bit-rate used by the encoder (or lower) */ 93 #define SPEEX_SET_BITRATE 18 94 /** Get current bit-rate used by the encoder or decoder */ 95 #define SPEEX_GET_BITRATE 19 96 97 /** Define a handler function for in-band Speex request*/ 98 #define SPEEX_SET_HANDLER 20 99 100 /** Define a handler function for in-band user-defined request*/ 101 #define SPEEX_SET_USER_HANDLER 22 102 103 /** Set sampling rate used in bit-rate computation */ 104 #define SPEEX_SET_SAMPLING_RATE 24 105 /** Get sampling rate used in bit-rate computation */ 106 #define SPEEX_GET_SAMPLING_RATE 25 107 108 /** Reset the encoder/decoder memories to zero*/ 109 #define SPEEX_RESET_STATE 26 110 111 /** Get VBR info (mostly used internally) */ 112 #define SPEEX_GET_RELATIVE_QUALITY 29 113 114 /** Set VAD status (1 for on, 0 for off) */ 115 #define SPEEX_SET_VAD 30 116 117 /** Get VAD status (1 for on, 0 for off) */ 118 #define SPEEX_GET_VAD 31 119 120 /** Set Average Bit-Rate (ABR) to n bits per seconds */ 121 #define SPEEX_SET_ABR 32 122 /** Get Average Bit-Rate (ABR) setting (in bps) */ 123 #define SPEEX_GET_ABR 33 124 125 /** Set DTX status (1 for on, 0 for off) */ 126 #define SPEEX_SET_DTX 34 127 /** Get DTX status (1 for on, 0 for off) */ 128 #define SPEEX_GET_DTX 35 129 130 /** Set submode encoding in each frame (1 for yes, 0 for no, setting to no breaks the standard) */ 131 #define SPEEX_SET_SUBMODE_ENCODING 36 132 /** Get submode encoding in each frame */ 133 #define SPEEX_GET_SUBMODE_ENCODING 37 134 135 /*#define SPEEX_SET_LOOKAHEAD 38*/ 136 /** Returns the lookahead used by Speex */ 137 #define SPEEX_GET_LOOKAHEAD 39 138 139 /** Sets tuning for packet-loss concealment (expected loss rate) */ 140 #define SPEEX_SET_PLC_TUNING 40 141 /** Gets tuning for PLC */ 142 #define SPEEX_GET_PLC_TUNING 41 143 144 /* Used internally, not to be used in applications */ 145 /** Used internally*/ 146 #define SPEEX_GET_PI_GAIN 100 147 /** Used internally*/ 148 #define SPEEX_GET_EXC 101 149 /** Used internally*/ 150 #define SPEEX_GET_INNOV 102 151 /** Used internally*/ 152 #define SPEEX_GET_DTX_STATUS 103 153 154 155 /* Preserving compatibility:*/ 156 /** Equivalent to SPEEX_SET_ENH */ 157 #define SPEEX_SET_PF 0 158 /** Equivalent to SPEEX_GET_ENH */ 159 #define SPEEX_GET_PF 1 160 161 162 163 164 /* Values allowed for mode queries */ 165 /** Query the frame size of a mode */ 166 #define SPEEX_MODE_FRAME_SIZE 0 167 168 /** Query the size of an encoded frame for a particular sub-mode */ 169 #define SPEEX_SUBMODE_BITS_PER_FRAME 1 170 171 172 173 /** Get major Speex version */ 174 #define SPEEX_LIB_GET_MAJOR_VERSION 1 175 /** Get minor Speex version */ 176 #define SPEEX_LIB_GET_MINOR_VERSION 3 177 /** Get micro Speex version */ 178 #define SPEEX_LIB_GET_MICRO_VERSION 5 179 /** Get extra Speex version */ 180 #define SPEEX_LIB_GET_EXTRA_VERSION 7 181 /** Get Speex version string */ 182 #define SPEEX_LIB_GET_VERSION_STRING 9 183 184 /*#define SPEEX_LIB_SET_ALLOC_FUNC 10 185 #define SPEEX_LIB_GET_ALLOC_FUNC 11 186 #define SPEEX_LIB_SET_FREE_FUNC 12 187 #define SPEEX_LIB_GET_FREE_FUNC 13 188 189 #define SPEEX_LIB_SET_WARNING_FUNC 14 190 #define SPEEX_LIB_GET_WARNING_FUNC 15 191 #define SPEEX_LIB_SET_ERROR_FUNC 16 192 #define SPEEX_LIB_GET_ERROR_FUNC 17 193 */ 194 195 /** Number of defined modes in Speex */ 196 #define SPEEX_NB_MODES 3 197 198 /** modeID for the defined narrowband mode */ 199 #define SPEEX_MODEID_NB 0 200 201 /** modeID for the defined wideband mode */ 202 #define SPEEX_MODEID_WB 1 203 204 /** modeID for the defined ultra-wideband mode */ 205 #define SPEEX_MODEID_UWB 2 206 207 #ifdef EPIC_48K 208 /** modeID for the Epic 48K mode */ 209 #define SPEEX_MODEID_NB_48K 1000 210 #endif 211 212 struct SpeexMode; 213 214 215 /* Prototypes for mode function pointers */ 216 217 /** Encoder state initialization function */ 218 typedef void *(*encoder_init_func)(const struct SpeexMode *mode); 219 220 /** Encoder state destruction function */ 221 typedef void (*encoder_destroy_func)(void *st); 222 223 /** Main encoding function */ 224 typedef int (*encode_func)(void *state, void *in, SpeexBits *bits); 225 226 /** Function for controlling the encoder options */ 227 typedef int (*encoder_ctl_func)(void *state, int request, void *ptr); 228 229 /** Decoder state initialization function */ 230 typedef void *(*decoder_init_func)(const struct SpeexMode *mode); 231 232 /** Decoder state destruction function */ 233 typedef void (*decoder_destroy_func)(void *st); 234 235 /** Main decoding function */ 236 typedef int (*decode_func)(void *state, SpeexBits *bits, void *out); 237 238 /** Function for controlling the decoder options */ 239 typedef int (*decoder_ctl_func)(void *state, int request, void *ptr); 240 241 242 /** Query function for a mode */ 243 typedef int (*mode_query_func)(const void *mode, int request, void *ptr); 244 245 /** Struct defining a Speex mode */ 246 typedef struct SpeexMode { 247 /** Pointer to the low-level mode data */ 248 const void *mode; 249 250 /** Pointer to the mode query function */ 251 mode_query_func query; 252 253 /** The name of the mode (you should not rely on this to identify the mode)*/ 254 const char *modeName; 255 256 /**ID of the mode*/ 257 int modeID; 258 259 /**Version number of the bitstream (incremented every time we break 260 bitstream compatibility*/ 261 int bitstream_version; 262 263 /** Pointer to encoder initialization function */ 264 encoder_init_func enc_init; 265 266 /** Pointer to encoder destruction function */ 267 encoder_destroy_func enc_destroy; 268 269 /** Pointer to frame encoding function */ 270 encode_func enc; 271 272 /** Pointer to decoder initialization function */ 273 decoder_init_func dec_init; 274 275 /** Pointer to decoder destruction function */ 276 decoder_destroy_func dec_destroy; 277 278 /** Pointer to frame decoding function */ 279 decode_func dec; 280 281 /** ioctl-like requests for encoder */ 282 encoder_ctl_func enc_ctl; 283 284 /** ioctl-like requests for decoder */ 285 decoder_ctl_func dec_ctl; 286 287 } SpeexMode; 288 289 /** 290 * Returns a handle to a newly created Speex encoder state structure. For now, 291 * the "mode" argument can be &nb_mode or &wb_mode . In the future, more modes 292 * may be added. Note that for now if you have more than one channels to 293 * encode, you need one state per channel. 294 * 295 * @param mode The mode to use (either speex_nb_mode or speex_wb.mode) 296 * @return A newly created encoder 297 */ 298 void *speex_encoder_init(const SpeexMode *mode); 299 300 /** Frees all resources associated to an existing Speex encoder state. 301 * @param state Encoder state to be destroyed */ 302 void speex_encoder_destroy(void *state); 303 304 /** Uses an existing encoder state to encode one frame of speech pointed to by 305 "in". The encoded bit-stream is saved in "bits". 306 @param state Encoder state 307 @param in Frame that will be encoded with a +-2^15 range 308 @param bits Bit-stream where the data will be written 309 @return 0 if frame needs not be transmitted (DTX only), 1 otherwise 310 */ 311 int speex_encode(void *state, float *in, SpeexBits *bits); 312 313 /** Uses an existing encoder state to encode one frame of speech pointed to by 314 "in". The encoded bit-stream is saved in "bits". 315 @param state Encoder state 316 @param in Frame that will be encoded with a +-2^15 range 317 @param bits Bit-stream where the data will be written 318 @return 0 if frame needs not be transmitted (DTX only), 1 otherwise 319 */ 320 int speex_encode_int(void *state, spx_int16_t *in, SpeexBits *bits); 321 322 /** Used like the ioctl function to control the encoder parameters 323 * 324 * @param state Encoder state 325 * @param request ioctl-type request (one of the SPEEX_* macros) 326 * @param ptr Data exchanged to-from function 327 * @return 0 if no error, -1 if request in unknown 328 */ 329 int speex_encoder_ctl(void *state, int request, void *ptr); 330 331 332 /** Returns a handle to a newly created decoder state structure. For now, 333 * the mode argument can be &nb_mode or &wb_mode . In the future, more modes 334 * may be added. Note that for now if you have more than one channels to 335 * decode, you need one state per channel. 336 * 337 * @param mode Speex mode (one of speex_nb_mode or speex_wb_mode) 338 * @return A newly created decoder state 339 */ 340 void *speex_decoder_init(const SpeexMode *mode); 341 342 /** Frees all resources associated to an existing decoder state. 343 * 344 * @param state State to be destroyed 345 */ 346 void speex_decoder_destroy(void *state); 347 348 /** Uses an existing decoder state to decode one frame of speech from 349 * bit-stream bits. The output speech is saved written to out. 350 * 351 * @param state Decoder state 352 * @param bits Bit-stream from which to decode the frame (NULL if the packet was lost) 353 * @param out Where to write the decoded frame 354 * @return return status (0 for no error, -1 for end of stream, -2 corrupt stream) 355 */ 356 int speex_decode(void *state, SpeexBits *bits, float *out); 357 358 /** Uses an existing decoder state to decode one frame of speech from 359 * bit-stream bits. The output speech is saved written to out. 360 * 361 * @param state Decoder state 362 * @param bits Bit-stream from which to decode the frame (NULL if the packet was lost) 363 * @param out Where to write the decoded frame 364 * @return return status (0 for no error, -1 for end of stream, -2 corrupt stream) 365 */ 366 int speex_decode_int(void *state, SpeexBits *bits, spx_int16_t *out); 367 368 /** Used like the ioctl function to control the encoder parameters 369 * 370 * @param state Decoder state 371 * @param request ioctl-type request (one of the SPEEX_* macros) 372 * @param ptr Data exchanged to-from function 373 * @return 0 if no error, -1 if request in unknown 374 */ 375 int speex_decoder_ctl(void *state, int request, void *ptr); 376 377 378 /** Query function for mode information 379 * 380 * @param mode Speex mode 381 * @param request ioctl-type request (one of the SPEEX_* macros) 382 * @param ptr Data exchanged to-from function 383 */ 384 int speex_mode_query(const SpeexMode *mode, int request, void *ptr); 385 386 /** Functions for controlling the behavior of libspeex 387 * @param request ioctl-type request (one of the SPEEX_LIB_* macros) 388 * @param ptr Data exchanged to-from function 389 */ 390 int speex_lib_ctl(int request, void *ptr); 391 392 /** Default narrowband mode */ 393 extern const SpeexMode speex_nb_mode; 394 395 /** Default wideband mode */ 396 extern const SpeexMode speex_wb_mode; 397 398 /** Default "ultra-wideband" mode */ 399 extern const SpeexMode speex_uwb_mode; 400 401 #ifdef EPIC_48K 402 /** 4.8 kbps narrowband mode */ 403 extern const SpeexMode speex_nb_48k_mode; 404 #endif 405 406 /** List of all modes available */ 407 extern const SpeexMode * const speex_mode_list[SPEEX_NB_MODES]; 408 409 /** Obtain one of the modes available */ 410 const SpeexMode * speex_lib_get_mode (int mode); 411 412 #ifdef __cplusplus 413 } 414 #endif 415 416 417 #endif 418