utils/iaxclient/lib/libspeex/include/speex/speex.h

   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/speex_bits.h"
  40 #include "speex/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 /** */
 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 #define SPEEX_LIB_GET_MAJOR_VERSION 1
 174 #define SPEEX_LIB_GET_MINOR_VERSION 3
 175 #define SPEEX_LIB_GET_MICRO_VERSION 5
 176 #define SPEEX_LIB_GET_EXTRA_VERSION 7
 177 #define SPEEX_LIB_GET_VERSION_STRING 9
 178
 179 /*#define SPEEX_LIB_SET_ALLOC_FUNC 10
 180 #define SPEEX_LIB_GET_ALLOC_FUNC 11
 181 #define SPEEX_LIB_SET_FREE_FUNC 12
 182 #define SPEEX_LIB_GET_FREE_FUNC 13
 183
 184 #define SPEEX_LIB_SET_WARNING_FUNC 14
 185 #define SPEEX_LIB_GET_WARNING_FUNC 15
 186 #define SPEEX_LIB_SET_ERROR_FUNC 16
 187 #define SPEEX_LIB_GET_ERROR_FUNC 17
 188 */
 189
 190 /** Number of defined modes in Speex */
 191 #define SPEEX_NB_MODES 3
 192
 193 /** modeID for the defined narrowband mode */
 194 #define SPEEX_MODEID_NB 0
 195
 196 /** modeID for the defined wideband mode */
 197 #define SPEEX_MODEID_WB 1
 198
 199 /** modeID for the defined ultra-wideband mode */
 200 #define SPEEX_MODEID_UWB 2
 201
 202 #ifdef EPIC_48K
 203 /** modeID for the Epic 48K mode */
 204 #define SPEEX_MODEID_NB_48K 1000
 205 #endif
 206
 207 struct SpeexMode;
 208
 209
 210 /* Prototypes for mode function pointers */
 211
 212 /** Encoder state initialization function */
 213 typedef void *(*encoder_init_func)(const struct SpeexMode *mode);
 214
 215 /** Encoder state destruction function */
 216 typedef void (*encoder_destroy_func)(void *st);
 217
 218 /** Main encoding function */
 219 typedef int (*encode_func)(void *state, void *in, SpeexBits *bits);
 220
 221 /** Function for controlling the encoder options */
 222 typedef int (*encoder_ctl_func)(void *state, int request, void *ptr);
 223
 224 /** Decoder state initialization function */
 225 typedef void *(*decoder_init_func)(const struct SpeexMode *mode);
 226
 227 /** Decoder state destruction function */
 228 typedef void (*decoder_destroy_func)(void *st);
 229
 230 /** Main decoding function */
 231 typedef int  (*decode_func)(void *state, SpeexBits *bits, void *out);
 232
 233 /** Function for controlling the decoder options */
 234 typedef int (*decoder_ctl_func)(void *state, int request, void *ptr);
 235
 236
 237 /** Query function for a mode */
 238 typedef int (*mode_query_func)(const void *mode, int request, void *ptr);
 239
 240 /** Struct defining a Speex mode */
 241 typedef struct SpeexMode {
 242    /** Pointer to the low-level mode data */
 243    const void *mode;
 244
 245    /** Pointer to the mode query function */
 246    mode_query_func query;
 247
 248    /** The name of the mode (you should not rely on this to identify the mode)*/
 249    const char *modeName;
 250
 251    /**ID of the mode*/
 252    int modeID;
 253
 254    /**Version number of the bitstream (incremented every time we break
 255     bitstream compatibility*/
 256    int bitstream_version;
 257
 258    /** Pointer to encoder initialization function */
 259    encoder_init_func enc_init;
 260
 261    /** Pointer to encoder destruction function */
 262    encoder_destroy_func enc_destroy;
 263
 264    /** Pointer to frame encoding function */
 265    encode_func enc;
 266
 267    /** Pointer to decoder initialization function */
 268    decoder_init_func dec_init;
 269
 270    /** Pointer to decoder destruction function */
 271    decoder_destroy_func dec_destroy;
 272
 273    /** Pointer to frame decoding function */
 274    decode_func dec;
 275
 276    /** ioctl-like requests for encoder */
 277    encoder_ctl_func enc_ctl;
 278
 279    /** ioctl-like requests for decoder */
 280    decoder_ctl_func dec_ctl;
 281
 282 } SpeexMode;
 283
 284 /**
 285  * Returns a handle to a newly created Speex encoder state structure. For now,
 286  * the "mode" argument can be &nb_mode or &wb_mode . In the future, more modes
 287  * may be added. Note that for now if you have more than one channels to
 288  * encode, you need one state per channel.
 289  *
 290  * @param mode The mode to use (either speex_nb_mode or speex_wb.mode)
 291  * @return A newly created encoder
 292  */
 293 void *speex_encoder_init(const SpeexMode *mode);
 294
 295 /** Frees all resources associated to an existing Speex encoder state.
 296  * @param state Encoder state to be destroyed */
 297 void speex_encoder_destroy(void *state);
 298
 299 /** Uses an existing encoder state to encode one frame of speech pointed to by
 300     "in". The encoded bit-stream is saved in "bits".
 301  @param state Encoder state
 302  @param in Frame that will be encoded with a +-2^15 range
 303  @param bits Bit-stream where the data will be written
 304  */
 305 int speex_encode(void *state, float *in, SpeexBits *bits);
 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
 311  @param bits Bit-stream where the data will be written
 312  */
 313 int speex_encode_int(void *state, spx_int16_t *in, SpeexBits *bits);
 314
 315 /** Used like the ioctl function to control the encoder parameters
 316  *
 317  * @param state Encoder state
 318  * @param request ioctl-type request (one of the SPEEX_* macros)
 319  * @param ptr Data exchanged to-from function
 320  * @return 0 if frame needs not be transmitted (DTX only), 1 otherwise
 321  */
 322 int speex_encoder_ctl(void *state, int request, void *ptr);
 323
 324
 325 /** Returns a handle to a newly created decoder state structure. For now,
 326  * the mode argument can be &nb_mode or &wb_mode . In the future, more modes
 327  * may be added.  Note that for now if you have more than one channels to
 328  * decode, you need one state per channel.
 329  *
 330  * @param mode Speex mode (one of speex_nb_mode or speex_wb_mode)
 331  * @return A newly created decoder state
 332  */
 333 void *speex_decoder_init(const SpeexMode *mode);
 334
 335 /** Frees all resources associated to an existing decoder state.
 336  *
 337  * @param state State to be destroyed
 338  */
 339 void speex_decoder_destroy(void *state);
 340
 341 /** Uses an existing decoder state to decode one frame of speech from
 342  * bit-stream bits. The output speech is saved written to out.
 343  *
 344  * @param state Decoder state
 345  * @param bits Bit-stream from which to decode the frame (NULL if the packet was lost)
 346  * @param out Where to write the decoded frame
 347  * @return return status (0 for no error, -1 for end of stream, -2 other)
 348  */
 349 int speex_decode(void *state, SpeexBits *bits, float *out);
 350
 351 /** Uses an existing decoder state to decode one frame of speech from
 352  * bit-stream bits. The output speech is saved written to out.
 353  *
 354  * @param state Decoder state
 355  * @param bits Bit-stream from which to decode the frame (NULL if the packet was lost)
 356  * @param out Where to write the decoded frame
 357  * @return return status (0 for no error, -1 for end of stream, -2 other)
 358  */
 359 int speex_decode_int(void *state, SpeexBits *bits, spx_int16_t *out);
 360
 361 /** Used like the ioctl function to control the encoder parameters
 362  *
 363  * @param state Decoder state
 364  * @param request ioctl-type request (one of the SPEEX_* macros)
 365  * @param ptr Data exchanged to-from function
 366  * @return 0 for no error, 1 if a terminator is reached, 2 for another error
 367  */
 368 int speex_decoder_ctl(void *state, int request, void *ptr);
 369
 370
 371 /** Query function for mode information
 372  *
 373  * @param mode Speex mode
 374  * @param request ioctl-type request (one of the SPEEX_* macros)
 375  * @param ptr Data exchanged to-from function
 376  */
 377 int speex_mode_query(const SpeexMode *mode, int request, void *ptr);
 378
 379 /** Functions for controlling the behavior of libspeex
 380  * @param request ioctl-type request (one of the SPEEX_LIB_* macros)
 381  * @param ptr Data exchanged to-from function
 382  */
 383 int speex_lib_ctl(int request, void *ptr);
 384
 385 /** Default narrowband mode */
 386 extern const SpeexMode speex_nb_mode;
 387
 388 /** Default wideband mode */
 389 extern const SpeexMode speex_wb_mode;
 390
 391 /** Default "ultra-wideband" mode */
 392 extern const SpeexMode speex_uwb_mode;
 393
 394 #ifdef EPIC_48K
 395 /** 4.8 kbps narrowband mode */
 396 extern const SpeexMode speex_nb_48k_mode;
 397 #endif
 398
 399 /** List of all modes available */
 400 extern const SpeexMode * const speex_mode_list[SPEEX_NB_MODES];
 401
 402 /** Obtain one of the modes available */
 403 const SpeexMode * speex_lib_get_mode (int mode);
 404
 405 #ifdef __cplusplus
 406 }
 407 #endif
 408
 409
 410 #endif