speex_preprocess.h revision 98913fed6520d8849fb2e246be943e04474aefa4
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 SpeexPreprocessState: The Speex 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 49extern "C" { 50#endif 51 52/** State of the preprocessor (one per channel). Should never be accessed directly. */ 53struct SpeexPreprocessState_; 54 55/** State of the preprocessor (one per channel). Should never be accessed directly. */ 56typedef struct SpeexPreprocessState_ SpeexPreprocessState; 57 58 59/** Creates a new preprocessing state. You MUST create one state per channel processed. 60 * @param frame_size Number of samples to process at one time (should correspond to 10-20 ms). Must be 61 * the same value as that used for the echo canceller for residual echo cancellation to work. 62 * @param sampling_rate Sampling rate used for the input. 63 * @return Newly created preprocessor state 64*/ 65SpeexPreprocessState *speex_preprocess_state_init(int frame_size, int sampling_rate); 66 67/** Destroys a preprocessor state 68 * @param st Preprocessor state to destroy 69*/ 70void speex_preprocess_state_destroy(SpeexPreprocessState *st); 71 72/** Preprocess a frame 73 * @param st Preprocessor state 74 * @param x Audio sample vector (in and out). Must be same size as specified in speex_preprocess_state_init(). 75 * @return Bool value for voice activity (1 for speech, 0 for noise/silence), ONLY if VAD turned on. 76*/ 77int speex_preprocess_run(SpeexPreprocessState *st, spx_int16_t *x); 78 79/** Preprocess a frame (deprecated, use speex_preprocess_run() instead)*/ 80int speex_preprocess(SpeexPreprocessState *st, spx_int16_t *x, spx_int32_t *echo); 81 82/** Update preprocessor state, but do not compute the output 83 * @param st Preprocessor state 84 * @param x Audio sample vector (in only). Must be same size as specified in speex_preprocess_state_init(). 85*/ 86void speex_preprocess_estimate_update(SpeexPreprocessState *st, spx_int16_t *x); 87 88/** Used like the ioctl function to control the preprocessor parameters 89 * @param st Preprocessor state 90 * @param request ioctl-type request (one of the SPEEX_PREPROCESS_* macros) 91 * @param ptr Data exchanged to-from function 92 * @return 0 if no error, -1 if request in unknown 93*/ 94int speex_preprocess_ctl(SpeexPreprocessState *st, int request, void *ptr); 95 96 97 98/** Set preprocessor denoiser state */ 99#define SPEEX_PREPROCESS_SET_DENOISE 0 100/** Get preprocessor denoiser state */ 101#define SPEEX_PREPROCESS_GET_DENOISE 1 102 103/** Set preprocessor Automatic Gain Control state */ 104#define SPEEX_PREPROCESS_SET_AGC 2 105/** Get preprocessor Automatic Gain Control state */ 106#define SPEEX_PREPROCESS_GET_AGC 3 107 108/** Set preprocessor Voice Activity Detection state */ 109#define SPEEX_PREPROCESS_SET_VAD 4 110/** Get preprocessor Voice Activity Detection state */ 111#define SPEEX_PREPROCESS_GET_VAD 5 112 113/** Set preprocessor Automatic Gain Control level (float) */ 114#define SPEEX_PREPROCESS_SET_AGC_LEVEL 6 115/** Get preprocessor Automatic Gain Control level (float) */ 116#define SPEEX_PREPROCESS_GET_AGC_LEVEL 7 117 118/** Set preprocessor dereverb state */ 119#define SPEEX_PREPROCESS_SET_DEREVERB 8 120/** Get preprocessor dereverb state */ 121#define SPEEX_PREPROCESS_GET_DEREVERB 9 122 123/** Set preprocessor dereverb level */ 124#define SPEEX_PREPROCESS_SET_DEREVERB_LEVEL 10 125/** Get preprocessor dereverb level */ 126#define SPEEX_PREPROCESS_GET_DEREVERB_LEVEL 11 127 128/** Set preprocessor dereverb decay */ 129#define SPEEX_PREPROCESS_SET_DEREVERB_DECAY 12 130/** Get preprocessor dereverb decay */ 131#define SPEEX_PREPROCESS_GET_DEREVERB_DECAY 13 132 133/** Set probability required for the VAD to go from silence to voice */ 134#define SPEEX_PREPROCESS_SET_PROB_START 14 135/** Get probability required for the VAD to go from silence to voice */ 136#define SPEEX_PREPROCESS_GET_PROB_START 15 137 138/** Set probability required for the VAD to stay in the voice state (integer percent) */ 139#define SPEEX_PREPROCESS_SET_PROB_CONTINUE 16 140/** Get probability required for the VAD to stay in the voice state (integer percent) */ 141#define SPEEX_PREPROCESS_GET_PROB_CONTINUE 17 142 143/** Set maximum attenuation of the noise in dB (negative number) */ 144#define SPEEX_PREPROCESS_SET_NOISE_SUPPRESS 18 145/** Get maximum attenuation of the noise in dB (negative number) */ 146#define SPEEX_PREPROCESS_GET_NOISE_SUPPRESS 19 147 148/** Set maximum attenuation of the residual echo in dB (negative number) */ 149#define SPEEX_PREPROCESS_SET_ECHO_SUPPRESS 20 150/** Get maximum attenuation of the residual echo in dB (negative number) */ 151#define SPEEX_PREPROCESS_GET_ECHO_SUPPRESS 21 152 153/** Set maximum attenuation of the residual echo in dB when near end is active (negative number) */ 154#define SPEEX_PREPROCESS_SET_ECHO_SUPPRESS_ACTIVE 22 155/** Get maximum attenuation of the residual echo in dB when near end is active (negative number) */ 156#define SPEEX_PREPROCESS_GET_ECHO_SUPPRESS_ACTIVE 23 157 158/** Set the corresponding echo canceller state so that residual echo suppression can be performed (NULL for no residual echo suppression) */ 159#define SPEEX_PREPROCESS_SET_ECHO_STATE 24 160/** Get the corresponding echo canceller state */ 161#define SPEEX_PREPROCESS_GET_ECHO_STATE 25 162 163/** Set maximal gain increase in dB/second (int32) */ 164#define SPEEX_PREPROCESS_SET_AGC_INCREMENT 26 165 166/** Get maximal gain increase in dB/second (int32) */ 167#define SPEEX_PREPROCESS_GET_AGC_INCREMENT 27 168 169/** Set maximal gain decrease in dB/second (int32) */ 170#define SPEEX_PREPROCESS_SET_AGC_DECREMENT 28 171 172/** Get maximal gain decrease in dB/second (int32) */ 173#define SPEEX_PREPROCESS_GET_AGC_DECREMENT 29 174 175/** Set maximal gain in dB (int32) */ 176#define SPEEX_PREPROCESS_SET_AGC_MAX_GAIN 30 177 178/** Get maximal gain in dB (int32) */ 179#define SPEEX_PREPROCESS_GET_AGC_MAX_GAIN 31 180 181/* Can't set loudness */ 182/** Get loudness */ 183#define SPEEX_PREPROCESS_GET_AGC_LOUDNESS 33 184 185/* Can't set gain */ 186/** Get current gain (int32 percent) */ 187#define SPEEX_PREPROCESS_GET_AGC_GAIN 35 188 189/* Can't set spectrum size */ 190/** Get spectrum size for power spectrum (int32) */ 191#define SPEEX_PREPROCESS_GET_PSD_SIZE 37 192 193/* Can't set power spectrum */ 194/** Get power spectrum (int32[] of squared values) */ 195#define SPEEX_PREPROCESS_GET_PSD 39 196 197/* Can't set noise size */ 198/** Get spectrum size for noise estimate (int32) */ 199#define SPEEX_PREPROCESS_GET_NOISE_PSD_SIZE 41 200 201/* Can't set noise estimate */ 202/** Get noise estimate (int32[] of squared values) */ 203#define SPEEX_PREPROCESS_GET_NOISE_PSD 43 204 205/* Can't set speech probability */ 206/** Get speech probability in last frame (int32). */ 207#define SPEEX_PREPROCESS_GET_PROB 45 208 209/** Set preprocessor Automatic Gain Control level (int32) */ 210#define SPEEX_PREPROCESS_SET_AGC_TARGET 46 211/** Get preprocessor Automatic Gain Control level (int32) */ 212#define SPEEX_PREPROCESS_GET_AGC_TARGET 47 213 214#ifdef __cplusplus 215} 216#endif 217 218/** @}*/ 219#endif 220