Doxygen...
[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    This library is free software; you can redistribute it and/or
8    modify it under the terms of the GNU Lesser General Public
9    License as published by the Free Software Foundation; either
10    version 2.1 of the License, or (at your option) any later version.
11    
12    This library is distributed in the hope that it will be useful,
13    but WITHOUT ANY WARRANTY; without even the implied warranty of
14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15    Lesser General Public License for more details.
16    
17    You should have received a copy of the GNU Lesser General Public
18    License along with this library; if not, write to the Free Software
19    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
20
21 */
22
23 #ifndef SPEEX_H
24 #define SPEEX_H
25
26 #include "speex_bits.h"
27
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31
32 /* Values allowed for *ctl() requests */
33
34 /** Set enhancement on/off (decoder only) */
35 #define SPEEX_SET_ENH 0
36 /** Get enhancement state (decoder only) */
37 #define SPEEX_GET_ENH 1
38
39 /*Would be SPEEX_SET_FRAME_SIZE, but it's (currently) invalid*/
40 /** Obtain frame size used by encoder/decoder */
41 #define SPEEX_GET_FRAME_SIZE 3
42
43 /** Set quality value */
44 #define SPEEX_SET_QUALITY 4
45 /** Get current quality setting */
46 #define SPEEX_GET_QUALITY 5
47
48 /** Set sub-mode to use */
49 #define SPEEX_SET_MODE 6
50 /** Get current sub-mode in use */
51 #define SPEEX_GET_MODE 7
52
53 /** Set low-band sub-mode to use (wideband only)*/
54 #define SPEEX_SET_LOW_MODE 8
55 /** Get current low-band mode in use (wideband only)*/
56 #define SPEEX_GET_LOW_MODE 9
57
58 /** Set high-band sub-mode to use (wideband only)*/
59 #define SPEEX_SET_HIGH_MODE 10
60 /** Get current high-band mode in use (wideband only)*/
61 #define SPEEX_GET_HIGH_MODE 11
62
63 /** Set VBR on (1) or off (0) */
64 #define SPEEX_SET_VBR 12
65 /** Get VBR status (1 for on, 0 for off) */
66 #define SPEEX_GET_VBR 13
67
68 /** Set quality value for VBR encoding (0-10) */
69 #define SPEEX_SET_VBR_QUALITY 14
70 /** Get current quality value for VBR encoding (0-10) */
71 #define SPEEX_GET_VBR_QUALITY 15
72
73 /** Set complexity of the encoder (0-10) */
74 #define SPEEX_SET_COMPLEXITY 16
75 /** Get current complexity of the encoder (0-10) */
76 #define SPEEX_GET_COMPLEXITY 17
77
78 /*Would be SPEEX_SET_FRAME_SIZE, but it's (currently) invalid*/
79 /** Get current bit-rate used by the encoder or decoder */
80 #define SPEEX_GET_BITRATE 19
81
82
83 /* Preserving compatibility:*/
84 /** Equivalent to SPEEX_SET_ENH */
85 #define SPEEX_SET_PF 0
86 /** Equivalent to SPEEX_GET_ENH */
87 #define SPEEX_GET_PF 1
88
89
90 /* Values allowed for mode queries */
91 /** Query the frame size of a mode */
92 #define SPEEX_MODE_FRAME_SIZE 0
93
94 /** Query the size of an encoded frame for a particular sub-mode */
95 #define SPEEX_SUBMODE_BITS_PER_FRAME 1
96
97
98 /** Number of defined modes in Speex */
99 #define SPEEX_NB_MODES 2
100
101 struct SpeexMode;
102
103
104 /* Prototypes for mode function pointers */
105
106 /** Encoder state initialization function */
107 typedef void *(*encoder_init_func)(struct SpeexMode *mode);
108
109 /** Encoder state destruction function */
110 typedef void (*encoder_destroy_func)(void *st);
111
112 /** Main encoding function */
113 typedef void (*encode_func)(void *state, float *in, SpeexBits *bits);
114
115 /** Function for controlling the encoder options */
116 typedef void (*encoder_ctl_func)(void *state, int request, void *ptr);
117
118 /** Decoder state initialization function */
119 typedef void *(*decoder_init_func)(struct SpeexMode *mode);
120
121 /** Decoder state destruction function */
122 typedef void (*decoder_destroy_func)(void *st);
123
124 /** Main decoding function */
125 typedef int  (*decode_func)(void *state, SpeexBits *bits, float *out);
126
127 /** Function for controlling the decoder options */
128 typedef void (*decoder_ctl_func)(void *state, int request, void *ptr);
129
130
131 /** Query function for a mode */
132 typedef void (*mode_query_func)(void *mode, int request, void *ptr);
133
134 /** Struct defining a Speex mode */ 
135 typedef struct SpeexMode {
136    /** Pointer to the low-level mode data */
137    void *mode;
138
139    /** Pointer to the mode query function */
140    mode_query_func query;
141    
142    /** The name of the mode (you should not rely on this to identify the mode)*/
143    char *modeName;
144
145    /**ID of the mode*/
146    int modeID;
147
148    /**Version number of the bitstream (incremented every time we break
149     bitstream compatibility*/
150    int bitstream_version;
151
152    /** Pointer to encoder initialization function */
153    encoder_init_func enc_init;
154
155    /** Pointer to encoder destruction function */
156    encoder_destroy_func enc_destroy;
157
158    /** Pointer to frame encoding function */
159    encode_func enc;
160
161    /** Pointer to decoder initialization function */
162    decoder_init_func dec_init;
163
164    /** Pointer to decoder destruction function */
165    decoder_destroy_func dec_destroy;
166
167    /** Pointer to frame decoding function */
168    decode_func dec;
169
170    /** ioctl-like requests for encoder */
171    encoder_ctl_func enc_ctl;
172
173    /** ioctl-like requests for decoder */
174    decoder_ctl_func dec_ctl;
175
176 } SpeexMode;
177
178 /**
179  * Returns a handle to a newly created Speex encoder state structure. For now, 
180  * the "mode" arguent can be &nb_mode or &wb_mode . In the future, more modes 
181  * may be added. Note that for now if you have more than one channels to 
182  * encode, you need one state per channel.
183  *
184  * @param mode The mode to use (either speex_nb_mode or speex_wb.mode) 
185  * @return A newly created encoder
186  */
187 void *speex_encoder_init(SpeexMode *mode);
188
189 /** Frees all resources associated to an existing Speex encoder state. 
190  * @param state Encoder state to be destroyed */
191 void speex_encoder_destroy(void *state);
192
193 /** Uses an existing encoder state to encode one frame of speech pointed to by
194     "in". The encoded bit-stream is saved in "bits".
195  @param state Encoder state
196  @param in Frame that will be encoded with a +-2^16 range
197  @param bits Bit-stream where the data will be written
198  */
199 void speex_encode(void *state, float *in, SpeexBits *bits);
200
201 /** Used like the ioctl function to control the encoder parameters
202  *
203  * @param state Encoder state
204  * @param request ioctl-type request (one of the SPEEX_* macros)
205  * @param ptr Data exchanged to-from function
206  */
207 void speex_encoder_ctl(void *state, int request, void *ptr);
208
209
210 /** Returns a handle to a newly created decoder state structure. For now, 
211  * the mode arguent can be &nb_mode or &wb_mode . In the future, more modes
212  * may be added.  Note that for now if you have more than one channels to
213  * decode, you need one state per channel.
214  *
215  * @param mode Speex mode (one of speex_nb_mode or speex_wb_mode)
216  * @return A newly created decoder state
217  */ 
218 void *speex_decoder_init(SpeexMode *mode);
219
220 /** Frees all resources associated to an existing decoder state.
221  *
222  * @param state State to be destroyed
223  */
224 void speex_decoder_destroy(void *state);
225
226 /** Uses an existing decoder state to decode one frame of speech from
227  * bit-stream bits. The output speech is saved written to out.
228  *
229  * @param state Decoder state
230  * @param bits Bit-stream from which to decode the frame (NULL if the packet was lost)
231  * @param out Where to write the decoded frame
232  * @return return status (0 for no error, -1 for end of stream, -2 other)
233  */
234 int speex_decode(void *state, SpeexBits *bits, float *out);
235
236 /** Used like the ioctl function to control the encoder parameters
237  *
238  * @param state Decoder state
239  * @param request ioctl-type request (one of the SPEEX_* macros)
240  * @param ptr Data exchanged to-from function
241  */
242 void speex_decoder_ctl(void *state, int request, void *ptr);
243
244
245 /** Query function for mode information
246  *
247  * @param mode Speex mode
248  * @param request ioctl-type request (one of the SPEEX_* macros)
249  * @param ptr Data exchanged to-from function
250  */
251 void speex_mode_query(SpeexMode *mode, int request, void *ptr);
252
253
254 /** Default narrowband mode */
255 extern SpeexMode speex_nb_mode;
256
257 /** Default wideband mode */
258 extern SpeexMode speex_wb_mode;
259
260 /** List of all modes availavle */
261 extern SpeexMode *speex_mode_list[SPEEX_NB_MODES];
262
263 #ifdef __cplusplus
264 }
265 #endif
266
267
268 #endif