speex_preprocess.h

00001 /* Copyright (C) 2003 Epic Games
00002    Written by Jean-Marc Valin */
00003 /**
00004  *  @file speex_preprocess.h
00005  *  @brief Speex preprocessor. The preprocess can do noise suppression, 
00006  * residual echo suppression (after using the echo canceller), automatic
00007  * gain control (AGC) and voice activity detection (VAD).
00008 */
00009 /*
00010    Redistribution and use in source and binary forms, with or without
00011    modification, are permitted provided that the following conditions are
00012    met:
00013 
00014    1. Redistributions of source code must retain the above copyright notice,
00015    this list of conditions and the following disclaimer.
00016 
00017    2. Redistributions in binary form must reproduce the above copyright
00018    notice, this list of conditions and the following disclaimer in the
00019    documentation and/or other materials provided with the distribution.
00020 
00021    3. The name of the author may not be used to endorse or promote products
00022    derived from this software without specific prior written permission.
00023 
00024    THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
00025    IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
00026    OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00027    DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
00028    INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00029    (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
00030    SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
00031    HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
00032    STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
00033    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00034    POSSIBILITY OF SUCH DAMAGE.
00035 */
00036 
00037 #ifndef SPEEX_PREPROCESS_H
00038 #define SPEEX_PREPROCESS_H
00039 /** @defgroup SpeexPreprocessState SpeexPreprocessState: The Speex preprocessor
00040  *  This is the Speex preprocessor. The preprocess can do noise suppression, 
00041  * residual echo suppression (after using the echo canceller), automatic
00042  * gain control (AGC) and voice activity detection (VAD).
00043  *  @{
00044  */
00045 
00046 #include "speex/speex_types.h"
00047 
00048 #ifdef __cplusplus
00049 extern "C" {
00050 #endif
00051    
00052 /** State of the preprocessor (one per channel). Should never be accessed directly. */
00053 struct SpeexPreprocessState_;
00054 
00055 /** State of the preprocessor (one per channel). Should never be accessed directly. */
00056 typedef struct SpeexPreprocessState_ SpeexPreprocessState;
00057 
00058 
00059 /** Creates a new preprocessing state. You MUST create one state per channel processed.
00060  * @param frame_size Number of samples to process at one time (should correspond to 10-20 ms). Must be
00061  * the same value as that used for the echo canceller for residual echo cancellation to work.
00062  * @param sampling_rate Sampling rate used for the input.
00063  * @return Newly created preprocessor state
00064 */
00065 SpeexPreprocessState *speex_preprocess_state_init(int frame_size, int sampling_rate);
00066 
00067 /** Destroys a preprocessor state 
00068  * @param st Preprocessor state to destroy
00069 */
00070 void speex_preprocess_state_destroy(SpeexPreprocessState *st);
00071 
00072 /** Preprocess a frame 
00073  * @param st Preprocessor state
00074  * @param x Audio sample vector (in and out). Must be same size as specified in speex_preprocess_state_init().
00075  * @return Bool value for voice activity (1 for speech, 0 for noise/silence), ONLY if VAD turned on.
00076 */
00077 int speex_preprocess_run(SpeexPreprocessState *st, spx_int16_t *x);
00078 
00079 /** Preprocess a frame (deprecated, use speex_preprocess_run() instead)*/
00080 int speex_preprocess(SpeexPreprocessState *st, spx_int16_t *x, spx_int32_t *echo);
00081 
00082 /** Update preprocessor state, but do not compute the output
00083  * @param st Preprocessor state
00084  * @param x Audio sample vector (in only). Must be same size as specified in speex_preprocess_state_init().
00085 */
00086 void speex_preprocess_estimate_update(SpeexPreprocessState *st, spx_int16_t *x);
00087 
00088 /** Used like the ioctl function to control the preprocessor parameters 
00089  * @param st Preprocessor state
00090  * @param request ioctl-type request (one of the SPEEX_PREPROCESS_* macros)
00091  * @param ptr Data exchanged to-from function
00092  * @return 0 if no error, -1 if request in unknown
00093 */
00094 int speex_preprocess_ctl(SpeexPreprocessState *st, int request, void *ptr);
00095 
00096 
00097 
00098 /** Set preprocessor denoiser state */
00099 #define SPEEX_PREPROCESS_SET_DENOISE 0
00100 /** Get preprocessor denoiser state */
00101 #define SPEEX_PREPROCESS_GET_DENOISE 1
00102 
00103 /** Set preprocessor Automatic Gain Control state */
00104 #define SPEEX_PREPROCESS_SET_AGC 2
00105 /** Get preprocessor Automatic Gain Control state */
00106 #define SPEEX_PREPROCESS_GET_AGC 3
00107 
00108 /** Set preprocessor Voice Activity Detection state */
00109 #define SPEEX_PREPROCESS_SET_VAD 4
00110 /** Get preprocessor Voice Activity Detection state */
00111 #define SPEEX_PREPROCESS_GET_VAD 5
00112 
00113 /** Set preprocessor Automatic Gain Control level */
00114 #define SPEEX_PREPROCESS_SET_AGC_LEVEL 6
00115 /** Get preprocessor Automatic Gain Control level */
00116 #define SPEEX_PREPROCESS_GET_AGC_LEVEL 7
00117 
00118 /** Set preprocessor dereverb state */
00119 #define SPEEX_PREPROCESS_SET_DEREVERB 8
00120 /** Get preprocessor dereverb state */
00121 #define SPEEX_PREPROCESS_GET_DEREVERB 9
00122 
00123 /** Set preprocessor dereverb level */
00124 #define SPEEX_PREPROCESS_SET_DEREVERB_LEVEL 10
00125 /** Get preprocessor dereverb level */
00126 #define SPEEX_PREPROCESS_GET_DEREVERB_LEVEL 11
00127 
00128 /** Set preprocessor dereverb decay */
00129 #define SPEEX_PREPROCESS_SET_DEREVERB_DECAY 12
00130 /** Get preprocessor dereverb decay */
00131 #define SPEEX_PREPROCESS_GET_DEREVERB_DECAY 13
00132 
00133 /** Set probability required for the VAD to go from silence to voice */
00134 #define SPEEX_PREPROCESS_SET_PROB_START 14
00135 /** Get probability required for the VAD to go from silence to voice */
00136 #define SPEEX_PREPROCESS_GET_PROB_START 15
00137 
00138 /** Set probability required for the VAD to stay in the voice state (integer percent) */
00139 #define SPEEX_PREPROCESS_SET_PROB_CONTINUE 16
00140 /** Get probability required for the VAD to stay in the voice state (integer percent) */
00141 #define SPEEX_PREPROCESS_GET_PROB_CONTINUE 17
00142 
00143 /** Set maximum attenuation of the noise in dB (negative number) */
00144 #define SPEEX_PREPROCESS_SET_NOISE_SUPPRESS 18
00145 /** Get maximum attenuation of the noise in dB (negative number) */
00146 #define SPEEX_PREPROCESS_GET_NOISE_SUPPRESS 19
00147 
00148 /** Set maximum attenuation of the residual echo in dB (negative number) */
00149 #define SPEEX_PREPROCESS_SET_ECHO_SUPPRESS 20
00150 /** Get maximum attenuation of the residual echo in dB (negative number) */
00151 #define SPEEX_PREPROCESS_GET_ECHO_SUPPRESS 21
00152 
00153 /** Set maximum attenuation of the residual echo in dB when near end is active (negative number) */
00154 #define SPEEX_PREPROCESS_SET_ECHO_SUPPRESS_ACTIVE 22
00155 /** Get maximum attenuation of the residual echo in dB when near end is active (negative number) */
00156 #define SPEEX_PREPROCESS_GET_ECHO_SUPPRESS_ACTIVE 23
00157 
00158 /** Set the corresponding echo canceller state so that residual echo suppression can be performed (NULL for no residual echo suppression) */
00159 #define SPEEX_PREPROCESS_SET_ECHO_STATE 24
00160 /** Get the corresponding echo canceller state */
00161 #define SPEEX_PREPROCESS_GET_ECHO_STATE 25
00162 
00163 /** Set maximal gain increase in dB/second (int32) */
00164 #define SPEEX_PREPROCESS_SET_AGC_INCREMENT 26
00165 
00166 /** Get maximal gain increase in dB/second (int32) */
00167 #define SPEEX_PREPROCESS_GET_AGC_INCREMENT 27
00168 
00169 /** Set maximal gain decrease in dB/second (int32) */
00170 #define SPEEX_PREPROCESS_SET_AGC_DECREMENT 28
00171 
00172 /** Get maximal gain decrease in dB/second (int32) */
00173 #define SPEEX_PREPROCESS_GET_AGC_DECREMENT 29
00174 
00175 /** Set maximal gain in dB (int32) */
00176 #define SPEEX_PREPROCESS_SET_AGC_MAX_GAIN 30
00177 
00178 /** Get maximal gain in dB (int32) */
00179 #define SPEEX_PREPROCESS_GET_AGC_MAX_GAIN 31
00180 
00181 #ifdef __cplusplus
00182 }
00183 #endif
00184 
00185 /** @}*/
00186 #endif