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