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