Fixed a bunch of typos pointed to by: larry@doolittle.boa.org
[speexdsp.git] / libspeex / 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_bits.h"
40
41 #ifdef __cplusplus
42 extern "C" {
43 #endif
44
45 /* Values allowed for *ctl() requests */
46
47 /** Set enhancement on/off (decoder only) */
48 #define SPEEX_SET_ENH 0
49 /** Get enhancement state (decoder only) */
50 #define SPEEX_GET_ENH 1
51
52 /*Would be SPEEX_SET_FRAME_SIZE, but it's (currently) invalid*/
53 /** Obtain frame size used by encoder/decoder */
54 #define SPEEX_GET_FRAME_SIZE 3
55
56 /** Set quality value */
57 #define SPEEX_SET_QUALITY 4
58 /** Get current quality setting */
59 #define SPEEX_GET_QUALITY 5
60
61 /** Set sub-mode to use */
62 #define SPEEX_SET_MODE 6
63 /** Get current sub-mode in use */
64 #define SPEEX_GET_MODE 7
65
66 /** Set low-band sub-mode to use (wideband only)*/
67 #define SPEEX_SET_LOW_MODE 8
68 /** Get current low-band mode in use (wideband only)*/
69 #define SPEEX_GET_LOW_MODE 9
70
71 /** Set high-band sub-mode to use (wideband only)*/
72 #define SPEEX_SET_HIGH_MODE 10
73 /** Get current high-band mode in use (wideband only)*/
74 #define SPEEX_GET_HIGH_MODE 11
75
76 /** Set VBR on (1) or off (0) */
77 #define SPEEX_SET_VBR 12
78 /** Get VBR status (1 for on, 0 for off) */
79 #define SPEEX_GET_VBR 13
80
81 /** Set quality value for VBR encoding (0-10) */
82 #define SPEEX_SET_VBR_QUALITY 14
83 /** Get current quality value for VBR encoding (0-10) */
84 #define SPEEX_GET_VBR_QUALITY 15
85
86 /** Set complexity of the encoder (0-10) */
87 #define SPEEX_SET_COMPLEXITY 16
88 /** Get current complexity of the encoder (0-10) */
89 #define SPEEX_GET_COMPLEXITY 17
90
91 /** Set bit-rate used by the encoder (or lower) */
92 #define SPEEX_SET_BITRATE 18
93 /** Get current bit-rate used by the encoder or decoder */
94 #define SPEEX_GET_BITRATE 19
95
96 /**Define a handler function for in-band Speex request*/
97 #define SPEEX_SET_HANDLER 20
98
99 /**Define a handler function for in-band user-defined request*/
100 #define SPEEX_SET_USER_HANDLER 22
101
102 /** Set sampling rate used in bit-rate computation */
103 #define SPEEX_SET_SAMPLING_RATE 24
104 /** Get sampling rate used in bit-rate computation */
105 #define SPEEX_GET_SAMPLING_RATE 25
106
107 /** Reset the encoder/decoder memories to zero*/
108 #define SPEEX_RESET_STATE 26
109
110 /** Get VBR info (mostly used internally) */
111 #define SPEEX_GET_RELATIVE_QUALITY 29
112
113 /** Set VAD status (1 for on, 0 for off) */
114 #define SPEEX_SET_VAD 30
115
116 /** Get VAD status (1 for on, 0 for off) */
117 #define SPEEX_GET_VAD 31
118
119 /** Set Average Bit-Rate (ABR) to n bits per seconds */
120 #define SPEEX_SET_ABR 32
121 /** Get Average Bit-Rate (ABR) setting (in bps) */
122 #define SPEEX_GET_ABR 33
123
124 /** Set DTX status (1 for on, 0 for off) */
125 #define SPEEX_SET_DTX 34
126 /** Get DTX status (1 for on, 0 for off) */
127 #define SPEEX_GET_DTX 35
128
129
130 /* Used internally, not to be used in applications */
131 /** Used internally*/
132 #define SPEEX_GET_PI_GAIN 100
133 /** Used internally*/
134 #define SPEEX_GET_EXC     101
135 /** Used internally*/
136 #define SPEEX_GET_INNOV   102
137 /** Used internally*/
138 #define SPEEX_GET_DTX_STATUS   103
139
140
141 /* Preserving compatibility:*/
142 /** Equivalent to SPEEX_SET_ENH */
143 #define SPEEX_SET_PF 0
144 /** Equivalent to SPEEX_GET_ENH */
145 #define SPEEX_GET_PF 1
146
147
148 /* Values allowed for mode queries */
149 /** Query the frame size of a mode */
150 #define SPEEX_MODE_FRAME_SIZE 0
151
152 /** Query the size of an encoded frame for a particular sub-mode */
153 #define SPEEX_SUBMODE_BITS_PER_FRAME 1
154
155
156 /** Number of defined modes in Speex */
157 #define SPEEX_NB_MODES 3
158
159 struct SpeexMode;
160
161
162 /* Prototypes for mode function pointers */
163
164 /** Encoder state initialization function */
165 typedef void *(*encoder_init_func)(struct SpeexMode *mode);
166
167 /** Encoder state destruction function */
168 typedef void (*encoder_destroy_func)(void *st);
169
170 /** Main encoding function */
171 typedef int (*encode_func)(void *state, float *in, SpeexBits *bits);
172
173 /** Function for controlling the encoder options */
174 typedef int (*encoder_ctl_func)(void *state, int request, void *ptr);
175
176 /** Decoder state initialization function */
177 typedef void *(*decoder_init_func)(struct SpeexMode *mode);
178
179 /** Decoder state destruction function */
180 typedef void (*decoder_destroy_func)(void *st);
181
182 /** Main decoding function */
183 typedef int  (*decode_func)(void *state, SpeexBits *bits, float *out);
184
185 /** Function for controlling the decoder options */
186 typedef int (*decoder_ctl_func)(void *state, int request, void *ptr);
187
188
189 /** Query function for a mode */
190 typedef int (*mode_query_func)(void *mode, int request, void *ptr);
191
192 /** Struct defining a Speex mode */ 
193 typedef struct SpeexMode {
194    /** Pointer to the low-level mode data */
195    void *mode;
196
197    /** Pointer to the mode query function */
198    mode_query_func query;
199    
200    /** The name of the mode (you should not rely on this to identify the mode)*/
201    char *modeName;
202
203    /**ID of the mode*/
204    int modeID;
205
206    /**Version number of the bitstream (incremented every time we break
207     bitstream compatibility*/
208    int bitstream_version;
209
210    /** Pointer to encoder initialization function */
211    encoder_init_func enc_init;
212
213    /** Pointer to encoder destruction function */
214    encoder_destroy_func enc_destroy;
215
216    /** Pointer to frame encoding function */
217    encode_func enc;
218
219    /** Pointer to decoder initialization function */
220    decoder_init_func dec_init;
221
222    /** Pointer to decoder destruction function */
223    decoder_destroy_func dec_destroy;
224
225    /** Pointer to frame decoding function */
226    decode_func dec;
227
228    /** ioctl-like requests for encoder */
229    encoder_ctl_func enc_ctl;
230
231    /** ioctl-like requests for decoder */
232    decoder_ctl_func dec_ctl;
233
234 } SpeexMode;
235
236 /**
237  * Returns a handle to a newly created Speex encoder state structure. For now, 
238  * the "mode" argument can be &nb_mode or &wb_mode . In the future, more modes 
239  * may be added. Note that for now if you have more than one channels to 
240  * encode, you need one state per channel.
241  *
242  * @param mode The mode to use (either speex_nb_mode or speex_wb.mode) 
243  * @return A newly created encoder
244  */
245 void *speex_encoder_init(SpeexMode *mode);
246
247 /** Frees all resources associated to an existing Speex encoder state. 
248  * @param state Encoder state to be destroyed */
249 void speex_encoder_destroy(void *state);
250
251 /** Uses an existing encoder state to encode one frame of speech pointed to by
252     "in". The encoded bit-stream is saved in "bits".
253  @param state Encoder state
254  @param in Frame that will be encoded with a +-2^16 range
255  @param bits Bit-stream where the data will be written
256  */
257 int speex_encode(void *state, float *in, SpeexBits *bits);
258
259 /** Used like the ioctl function to control the encoder parameters
260  *
261  * @param state Encoder state
262  * @param request ioctl-type request (one of the SPEEX_* macros)
263  * @param ptr Data exchanged to-from function
264  * @return 0 if frame needs not be transmitted (DTX only), 1 otherwise
265  */
266 int speex_encoder_ctl(void *state, int request, void *ptr);
267
268
269 /** Returns a handle to a newly created decoder state structure. For now, 
270  * the mode argument can be &nb_mode or &wb_mode . In the future, more modes
271  * may be added.  Note that for now if you have more than one channels to
272  * decode, you need one state per channel.
273  *
274  * @param mode Speex mode (one of speex_nb_mode or speex_wb_mode)
275  * @return A newly created decoder state
276  */ 
277 void *speex_decoder_init(SpeexMode *mode);
278
279 /** Frees all resources associated to an existing decoder state.
280  *
281  * @param state State to be destroyed
282  */
283 void speex_decoder_destroy(void *state);
284
285 /** Uses an existing decoder state to decode one frame of speech from
286  * bit-stream bits. The output speech is saved written to out.
287  *
288  * @param state Decoder state
289  * @param bits Bit-stream from which to decode the frame (NULL if the packet was lost)
290  * @param out Where to write the decoded frame
291  * @return return status (0 for no error, -1 for end of stream, -2 other)
292  */
293 int speex_decode(void *state, SpeexBits *bits, float *out);
294
295 /** Used like the ioctl function to control the encoder parameters
296  *
297  * @param state Decoder state
298  * @param request ioctl-type request (one of the SPEEX_* macros)
299  * @param ptr Data exchanged to-from function
300  * @return 0 for no error, 1 if a terminator is reached, 2 for another error
301  */
302 int speex_decoder_ctl(void *state, int request, void *ptr);
303
304
305 /** Query function for mode information
306  *
307  * @param mode Speex mode
308  * @param request ioctl-type request (one of the SPEEX_* macros)
309  * @param ptr Data exchanged to-from function
310  */
311 int speex_mode_query(SpeexMode *mode, int request, void *ptr);
312
313
314 /** Default narrowband mode */
315 extern SpeexMode speex_nb_mode;
316
317 /** Default wideband mode */
318 extern SpeexMode speex_wb_mode;
319
320 /** Default "ultra-wideband" mode */
321 extern SpeexMode speex_uwb_mode;
322
323 /** List of all modes available */
324 extern SpeexMode *speex_mode_list[SPEEX_NB_MODES];
325
326 #ifdef __cplusplus
327 }
328 #endif
329
330
331 #endif