Completed VBR for 0.5.0 release
[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
49
50 #define SPEEX_NB_MODES 2
51
52
53 struct SpeexMode;
54
55 /* Prototypes for mode function pointers */
56 typedef void *(*encoder_init_func)(struct SpeexMode *mode);
57 typedef void (*encoder_destroy_func)(void *st);
58 typedef void (*encode_func)(void *state, float *in, SpeexBits *bits);
59 typedef void *(*decoder_init_func)(struct SpeexMode *mode);
60 typedef void (*decoder_destroy_func)(void *st);
61 typedef void (*decode_func)(void *state, SpeexBits *bits, float *out, int lost);
62 typedef void (*encoder_ctl_func)(void *state, int request, void *ptr);
63 typedef void (*decoder_ctl_func)(void *state, int request, void *ptr);
64
65 /** Struct defining a Speex mode */ 
66 typedef struct SpeexMode {
67    /** Pointer to the low-level mode data */
68    void *mode;
69
70    /** The name of the mode (you should not rely on this to identify the mode)*/
71    char *modeName;
72
73    /**ID of the mode*/
74    int modeID;
75
76    /**Version number of the bitstream (incremented every time we break
77     bitstream compatibility*/
78    int bitstream_version;
79
80    /** Pointer to encoder initialization function */
81    encoder_init_func enc_init;
82
83    /** Pointer to encoder destruction function */
84    encoder_destroy_func enc_destroy;
85
86    /** Pointer to frame encoding function */
87    encode_func enc;
88
89    /** Pointer to decoder initialization function */
90    decoder_init_func dec_init;
91
92    /** Pointer to decoder destruction function */
93    decoder_destroy_func dec_destroy;
94
95    /** Pointer to frame decoding function */
96    decode_func dec;
97
98    /** ioctl-like requests for encoder */
99    encoder_ctl_func enc_ctl;
100
101    /** ioctl-like requests for decoder */
102    decoder_ctl_func dec_ctl;
103
104    /** Frame size used for the mode*/
105    int frame_size;
106    
107    /** Bit-rate for the mode (highest in case of VBR) */
108    int bitrate;
109
110    /** VBR info (currently 0 for constant bit-rate and 1 for VBR) */
111    int vbr;
112
113 } SpeexMode;
114
115 /**Returns a handle to a newly created Speex encoder state structure. For now, the 
116    "mode" arguent can be &nb_mode or &wb_mode . In the future, more modes may be 
117    added. Note that for now if you have more than one channels to encode, you need 
118    one state per channel.*/
119 void *speex_encoder_init(SpeexMode *mode);
120
121 /** Frees all resources associated to an existing Speex encoder state. */
122 void speex_encoder_destroy(void *state);
123
124 /** Uses an existing encoder state to encode one frame of speech pointed to by
125     "in". The encoded bit-stream is saved in "bits".*/
126 void speex_encode(void *state, float *in, SpeexBits *bits);
127
128 /** Used like the ioctl function to control the encoder parameters */
129 void speex_encoder_ctl(void *state, int request, void *ptr);
130
131
132 /** Returns a handle to a newly created decoder state structure. For now, the mode
133     arguent can be &nb_mode or &wb_mode . In the future, more modes may be added. 
134     Note that for now if you have more than one channels to decode, you need one 
135     state per channel. */ 
136 void *speex_decoder_init(SpeexMode *mode);
137
138 /** Frees all resources associated to an existing decoder state. */
139 void speex_decoder_destroy(void *state);
140
141 /** Uses an existing decoder state to decode one frame of speech from bit-stream 
142     bits. The output speech is saved written to out. */
143 void speex_decode(void *state, SpeexBits *bits, float *out, int lost);
144
145 /** Used like the ioctl function to control the encoder parameters */
146 void speex_decoder_ctl(void *state, int request, void *ptr);
147
148
149
150 /** Default narrowband mode */
151 extern SpeexMode speex_nb_mode;
152
153 /** Default wideband mode */
154 extern SpeexMode speex_wb_mode;
155
156 /** List of all modes availavle */
157 extern SpeexMode *speex_mode_list[SPEEX_NB_MODES];
158
159 #ifdef __cplusplus
160 }
161 #endif
162
163
164 #endif