OLD | NEW |
(Empty) | |
| 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 break
s 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 strea
m) |
| 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 strea
m) |
| 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 : spe
ex_lib_get_mode (mode)) |
| 417 #endif |
| 418 |
| 419 #ifdef __cplusplus |
| 420 } |
| 421 #endif |
| 422 |
| 423 /** @}*/ |
| 424 #endif |
OLD | NEW |