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