Originally written for Symbian, it is no longer needed since we figured
[speexdsp.git] / include / speex / speex_preprocess.h
1 /* Copyright (C) 2003 Epic Games
2    Written by Jean-Marc Valin */
3 /**
4  *  @file speex_preprocess.h
5  *  @brief Speex preprocessor. The preprocess can do noise suppression, 
6  * residual echo suppression (after using the echo canceller), automatic
7  * gain control (AGC) and voice activity detection (VAD).
8 */
9 /*
10    Redistribution and use in source and binary forms, with or without
11    modification, are permitted provided that the following conditions are
12    met:
13
14    1. Redistributions of source code must retain the above copyright notice,
15    this list of conditions and the following disclaimer.
16
17    2. Redistributions in binary form must reproduce the above copyright
18    notice, this list of conditions and the following disclaimer in the
19    documentation and/or other materials provided with the distribution.
20
21    3. The name of the author may not be used to endorse or promote products
22    derived from this software without specific prior written permission.
23
24    THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
25    IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
26    OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
27    DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
28    INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
29    (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
30    SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
31    HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
32    STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
33    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34    POSSIBILITY OF SUCH DAMAGE.
35 */
36
37 #ifndef SPEEX_PREPROCESS_H
38 #define SPEEX_PREPROCESS_H
39 /** @defgroup SpeexPreprocessState Preprocessor
40  *  This is the Speex preprocessor. The preprocess can do noise suppression, 
41  * residual echo suppression (after using the echo canceller), automatic
42  * gain control (AGC) and voice activity detection (VAD).
43  *  @{
44  */
45
46 #include "speex/speex_types.h"
47
48 #ifdef __cplusplus
49 extern "C" {
50 #endif
51
52 struct SpeexPreprocessState_;
53
54 typedef struct SpeexPreprocessState_ SpeexPreprocessState;
55
56
57 /** Creates a new preprocessing state. You MUST create one state per channel processed.
58  * @param frame_size Number of samples to process at one time (should correspond to 10-20 ms). Must be
59  * the same value as that used for the echo canceller for residual echo cancellation to work.
60  * @param sampling_rate Sampling rate used for the input.
61  * @return Newly created preprocessor state
62 */
63 SpeexPreprocessState *speex_preprocess_state_init(int frame_size, int sampling_rate);
64
65 /** Destroys a preprocessor state 
66  * @param st Preprocessor state to destroy
67 */
68 void speex_preprocess_state_destroy(SpeexPreprocessState *st);
69
70 /** Preprocess a frame 
71  * @param st Preprocessor state
72  * @param x Audio sample vector (in and out). Must be same size as specified in speex_preprocess_state_init().
73  * @return Bool value for voice activity (1 for speech, 0 for noise/silence), ONLY if VAD turned on.
74 */
75 int speex_preprocess_run(SpeexPreprocessState *st, spx_int16_t *x);
76
77 /** Preprocess a frame (deprecated, use speex_preprocess_run() instead)*/
78 int speex_preprocess(SpeexPreprocessState *st, spx_int16_t *x, spx_int32_t *echo);
79
80 /** Update preprocessor state, but do not compute the output
81  * @param st Preprocessor state
82  * @param x Audio sample vector (in only). Must be same size as specified in speex_preprocess_state_init().
83 */
84 void speex_preprocess_estimate_update(SpeexPreprocessState *st, spx_int16_t *x);
85
86 /** Used like the ioctl function to control the preprocessor parameters 
87  * @param st Preprocessor state
88  * @param request ioctl-type request (one of the SPEEX_PREPROCESS_* macros)
89  * @param ptr Data exchanged to-from function
90  * @return 0 if no error, -1 if request in unknown
91 */
92 int speex_preprocess_ctl(SpeexPreprocessState *st, int request, void *ptr);
93
94
95
96 /** Set preprocessor denoiser state */
97 #define SPEEX_PREPROCESS_SET_DENOISE 0
98 /** Get preprocessor denoiser state */
99 #define SPEEX_PREPROCESS_GET_DENOISE 1
100
101 /** Set preprocessor Automatic Gain Control state */
102 #define SPEEX_PREPROCESS_SET_AGC 2
103 /** Get preprocessor Automatic Gain Control state */
104 #define SPEEX_PREPROCESS_GET_AGC 3
105
106 /** Set preprocessor Voice Activity Detection state */
107 #define SPEEX_PREPROCESS_SET_VAD 4
108 /** Get preprocessor Voice Activity Detection state */
109 #define SPEEX_PREPROCESS_GET_VAD 5
110
111 /** Set preprocessor Automatic Gain Control level */
112 #define SPEEX_PREPROCESS_SET_AGC_LEVEL 6
113 /** Get preprocessor Automatic Gain Control level */
114 #define SPEEX_PREPROCESS_GET_AGC_LEVEL 7
115
116 /** Set preprocessor dereverb state */
117 #define SPEEX_PREPROCESS_SET_DEREVERB 8
118 /** Get preprocessor dereverb state */
119 #define SPEEX_PREPROCESS_GET_DEREVERB 9
120
121 /** Set preprocessor dereverb level */
122 #define SPEEX_PREPROCESS_SET_DEREVERB_LEVEL 10
123 /** Get preprocessor dereverb level */
124 #define SPEEX_PREPROCESS_GET_DEREVERB_LEVEL 11
125
126 /** Set preprocessor dereverb decay */
127 #define SPEEX_PREPROCESS_SET_DEREVERB_DECAY 12
128 /** Get preprocessor dereverb decay */
129 #define SPEEX_PREPROCESS_GET_DEREVERB_DECAY 13
130
131 #define SPEEX_PREPROCESS_SET_PROB_START 14
132 #define SPEEX_PREPROCESS_GET_PROB_START 15
133
134 #define SPEEX_PREPROCESS_SET_PROB_CONTINUE 16
135 #define SPEEX_PREPROCESS_GET_PROB_CONTINUE 17
136
137 /** Set maximum attenuation of the noise in dB (negative number) */
138 #define SPEEX_PREPROCESS_SET_NOISE_SUPPRESS 18
139 /** Get maximum attenuation of the noise in dB (negative number) */
140 #define SPEEX_PREPROCESS_GET_NOISE_SUPPRESS 19
141
142 /** Set maximum attenuation of the residual echo in dB (negative number) */
143 #define SPEEX_PREPROCESS_SET_ECHO_SUPPRESS 20
144 /** Get maximum attenuation of the residual echo in dB (negative number) */
145 #define SPEEX_PREPROCESS_GET_ECHO_SUPPRESS 21
146
147 /** Set maximum attenuation of the residual echo in dB when near end is active (negative number) */
148 #define SPEEX_PREPROCESS_SET_ECHO_SUPPRESS_ACTIVE 22
149 /** Get maximum attenuation of the residual echo in dB when near end is active (negative number) */
150 #define SPEEX_PREPROCESS_GET_ECHO_SUPPRESS_ACTIVE 23
151
152 /** Set the corresponding echo canceller state so that residual echo suppression can be performed (NULL for no residual echo suppression) */
153 #define SPEEX_PREPROCESS_SET_ECHO_STATE 24
154 /** Get the corresponding echo canceller state */
155 #define SPEEX_PREPROCESS_GET_ECHO_STATE 25
156
157 #ifdef __cplusplus
158 }
159 #endif
160
161 /** @}*/
162 #endif