Added bit-rate information via speex_*_ctl calls, fixed stupid bug in
[speexdsp.git] / libspeex / speex.h
1 /* Copyright (C) 2002 Jean-Marc Valin 
2    File: modes.h
3
4    Describes the different modes of the codec
5
6    This library is free software; you can redistribute it and/or
7    modify it under the terms of the GNU Lesser General Public
8    License as published by the Free Software Foundation; either
9    version 2.1 of the License, or (at your option) any later version.
10    
11    This library is distributed in the hope that it will be useful,
12    but WITHOUT ANY WARRANTY; without even the implied warranty of
13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14    Lesser General Public License for more details.
15    
16    You should have received a copy of the GNU Lesser General Public
17    License along with this library; if not, write to the Free Software
18    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
19
20 */
21
22 #ifndef SPEEX_H
23 #define SPEEX_H
24
25 #include "speex_bits.h"
26
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30
31 /* Values allowed for *ctl() requests */
32 #define SPEEX_SET_PF 0
33 #define SPEEX_GET_PF 1
34 /*Would be SPEEX_SET_FRAME_SIZE, but it's (currently) invalid*/
35 #define SPEEX_GET_FRAME_SIZE 3
36 #define SPEEX_SET_QUALITY 4
37 #define SPEEX_GET_QUALITY 5
38 #define SPEEX_SET_MODE 6
39 #define SPEEX_GET_MODE 7
40 #define SPEEX_SET_LOW_MODE 8
41 #define SPEEX_GET_LOW_MODE 9
42 #define SPEEX_SET_HIGH_MODE 10
43 #define SPEEX_GET_HIGH_MODE 11
44 #define SPEEX_SET_VBR 12
45 #define SPEEX_GET_VBR 13
46 #define SPEEX_SET_VBR_QUALITY 14
47 #define SPEEX_GET_VBR_QUALITY 15
48 #define SPEEX_SET_COMPLEXITY 16
49 #define SPEEX_GET_COMPLEXITY 17
50 /*Would be SPEEX_SET_FRAME_SIZE, but it's (currently) invalid*/
51 #define SPEEX_GET_BITRATE 19
52
53 #define SPEEX_NB_MODES 2
54
55
56 struct SpeexMode;
57
58 /* Prototypes for mode function pointers */
59 typedef void *(*encoder_init_func)(struct SpeexMode *mode);
60 typedef void (*encoder_destroy_func)(void *st);
61 typedef void (*encode_func)(void *state, float *in, SpeexBits *bits);
62 typedef void *(*decoder_init_func)(struct SpeexMode *mode);
63 typedef void (*decoder_destroy_func)(void *st);
64 typedef void (*decode_func)(void *state, SpeexBits *bits, float *out, int lost);
65 typedef void (*encoder_ctl_func)(void *state, int request, void *ptr);
66 typedef void (*decoder_ctl_func)(void *state, int request, void *ptr);
67
68 /** Struct defining a Speex mode */ 
69 typedef struct SpeexMode {
70    /** Pointer to the low-level mode data */
71    void *mode;
72
73    /** The name of the mode (you should not rely on this to identify the mode)*/
74    char *modeName;
75
76    /**ID of the mode*/
77    int modeID;
78
79    /**Version number of the bitstream (incremented every time we break
80     bitstream compatibility*/
81    int bitstream_version;
82
83    /** Pointer to encoder initialization function */
84    encoder_init_func enc_init;
85
86    /** Pointer to encoder destruction function */
87    encoder_destroy_func enc_destroy;
88
89    /** Pointer to frame encoding function */
90    encode_func enc;
91
92    /** Pointer to decoder initialization function */
93    decoder_init_func dec_init;
94
95    /** Pointer to decoder destruction function */
96    decoder_destroy_func dec_destroy;
97
98    /** Pointer to frame decoding function */
99    decode_func dec;
100
101    /** ioctl-like requests for encoder */
102    encoder_ctl_func enc_ctl;
103
104    /** ioctl-like requests for decoder */
105    decoder_ctl_func dec_ctl;
106
107    /** Frame size used for the mode*/
108    int frame_size;
109    
110    /** Bit-rate for the mode (highest in case of VBR) */
111    int bitrate;
112
113    /** VBR info (currently 0 for constant bit-rate and 1 for VBR) */
114    int vbr;
115
116 } SpeexMode;
117
118 /**Returns a handle to a newly created Speex encoder state structure. For now, the 
119    "mode" arguent can be &nb_mode or &wb_mode . In the future, more modes may be 
120    added. Note that for now if you have more than one channels to encode, you need 
121    one state per channel.*/
122 void *speex_encoder_init(SpeexMode *mode);
123
124 /** Frees all resources associated to an existing Speex encoder state. */
125 void speex_encoder_destroy(void *state);
126
127 /** Uses an existing encoder state to encode one frame of speech pointed to by
128     "in". The encoded bit-stream is saved in "bits".*/
129 void speex_encode(void *state, float *in, SpeexBits *bits);
130
131 /** Used like the ioctl function to control the encoder parameters */
132 void speex_encoder_ctl(void *state, int request, void *ptr);
133
134
135 /** Returns a handle to a newly created decoder state structure. For now, the mode
136     arguent can be &nb_mode or &wb_mode . In the future, more modes may be added. 
137     Note that for now if you have more than one channels to decode, you need one 
138     state per channel. */ 
139 void *speex_decoder_init(SpeexMode *mode);
140
141 /** Frees all resources associated to an existing decoder state. */
142 void speex_decoder_destroy(void *state);
143
144 /** Uses an existing decoder state to decode one frame of speech from bit-stream 
145     bits. The output speech is saved written to out. */
146 void speex_decode(void *state, SpeexBits *bits, float *out, int lost);
147
148 /** Used like the ioctl function to control the encoder parameters */
149 void speex_decoder_ctl(void *state, int request, void *ptr);
150
151
152
153 /** Default narrowband mode */
154 extern SpeexMode speex_nb_mode;
155
156 /** Default wideband mode */
157 extern SpeexMode speex_wb_mode;
158
159 /** List of all modes availavle */
160 extern SpeexMode *speex_mode_list[SPEEX_NB_MODES];
161
162 #ifdef __cplusplus
163 }
164 #endif
165
166
167 #endif