gain_control.h (9164B)
1 /* 2 * Copyright (c) 2012 The WebRTC project authors. All Rights Reserved. 3 * 4 * Use of this source code is governed by a BSD-style license 5 * that can be found in the LICENSE file in the root of the source 6 * tree. An additional intellectual property rights grant can be found 7 * in the file PATENTS. All contributing project authors may 8 * be found in the AUTHORS file in the root of the source tree. 9 */ 10 11 #ifndef MODULES_AUDIO_PROCESSING_AGC_LEGACY_GAIN_CONTROL_H_ 12 #define MODULES_AUDIO_PROCESSING_AGC_LEGACY_GAIN_CONTROL_H_ 13 14 #include <stddef.h> 15 #include <stdint.h> 16 17 namespace webrtc { 18 19 enum { 20 kAgcModeUnchanged, 21 kAgcModeAdaptiveAnalog, 22 kAgcModeAdaptiveDigital, 23 kAgcModeFixedDigital 24 }; 25 26 enum { kAgcFalse = 0, kAgcTrue }; 27 28 typedef struct { 29 int16_t targetLevelDbfs; // default 3 (-3 dBOv) 30 int16_t compressionGaindB; // default 9 dB 31 uint8_t limiterEnable; // default kAgcTrue (on) 32 } WebRtcAgcConfig; 33 34 /* 35 * This function analyses the number of samples passed to 36 * farend and produces any error code that could arise. 37 * 38 * Input: 39 * - agcInst : AGC instance. 40 * - samples : Number of samples in input vector. 41 * 42 * Return value: 43 * : 0 - Normal operation. 44 * : -1 - Error. 45 */ 46 int WebRtcAgc_GetAddFarendError(void* state, size_t samples); 47 48 /* 49 * This function processes a 10 ms frame of far-end speech to determine 50 * if there is active speech. The length of the input speech vector must be 51 * given in samples (80 when FS=8000, and 160 when FS=16000, FS=32000 or 52 * FS=48000). 53 * 54 * Input: 55 * - agcInst : AGC instance. 56 * - inFar : Far-end input speech vector 57 * - samples : Number of samples in input vector 58 * 59 * Return value: 60 * : 0 - Normal operation. 61 * : -1 - Error 62 */ 63 int WebRtcAgc_AddFarend(void* agcInst, const int16_t* inFar, size_t samples); 64 65 /* 66 * This function processes a 10 ms frame of microphone speech to determine 67 * if there is active speech. The length of the input speech vector must be 68 * given in samples (80 when FS=8000, and 160 when FS=16000, FS=32000 or 69 * FS=48000). For very low input levels, the input signal is increased in level 70 * by multiplying and overwriting the samples in inMic[]. 71 * 72 * This function should be called before any further processing of the 73 * near-end microphone signal. 74 * 75 * Input: 76 * - agcInst : AGC instance. 77 * - inMic : Microphone input speech vector for each band 78 * - num_bands : Number of bands in input vector 79 * - samples : Number of samples in input vector 80 * 81 * Return value: 82 * : 0 - Normal operation. 83 * : -1 - Error 84 */ 85 int WebRtcAgc_AddMic(void* agcInst, 86 int16_t* const* inMic, 87 size_t num_bands, 88 size_t samples); 89 90 /* 91 * This function replaces the analog microphone with a virtual one. 92 * It is a digital gain applied to the input signal and is used in the 93 * agcAdaptiveDigital mode where no microphone level is adjustable. The length 94 * of the input speech vector must be given in samples (80 when FS=8000, and 160 95 * when FS=16000, FS=32000 or FS=48000). 96 * 97 * Input: 98 * - agcInst : AGC instance. 99 * - inMic : Microphone input speech vector for each band 100 * - num_bands : Number of bands in input vector 101 * - samples : Number of samples in input vector 102 * - micLevelIn : Input level of microphone (static) 103 * 104 * Output: 105 * - inMic : Microphone output after processing (L band) 106 * - inMic_H : Microphone output after processing (H band) 107 * - micLevelOut : Adjusted microphone level after processing 108 * 109 * Return value: 110 * : 0 - Normal operation. 111 * : -1 - Error 112 */ 113 int WebRtcAgc_VirtualMic(void* agcInst, 114 int16_t* const* inMic, 115 size_t num_bands, 116 size_t samples, 117 int32_t micLevelIn, 118 int32_t* micLevelOut); 119 120 /* 121 * This function analyses a 10 ms frame and produces the analog and digital 122 * gains required to normalize the signal. The gain adjustments are done only 123 * during active periods of speech. The length of the speech vectors must be 124 * given in samples (80 when FS=8000, and 160 when FS=16000, FS=32000 or 125 * FS=48000). The echo parameter can be used to ensure the AGC will not adjust 126 * upward in the presence of echo. 127 * 128 * This function should be called after processing the near-end microphone 129 * signal, in any case after any echo cancellation. 130 * 131 * Input: 132 * - agcInst : AGC instance 133 * - inNear : Near-end input speech vector for each band 134 * - num_bands : Number of bands in input/output vector 135 * - samples : Number of samples in input/output vector 136 * - inMicLevel : Current microphone volume level 137 * - echo : Set to 0 if the signal passed to add_mic is 138 * almost certainly free of echo; otherwise set 139 * to 1. If you have no information regarding echo 140 * set to 0. 141 * 142 * Output: 143 * - outMicLevel : Adjusted microphone volume level 144 * - saturationWarning : A returned value of 1 indicates a saturation event 145 * has occurred and the volume cannot be further 146 * reduced. Otherwise will be set to 0. 147 * - gains : Vector of gains to apply for digital normalization 148 * 149 * Return value: 150 * : 0 - Normal operation. 151 * : -1 - Error 152 */ 153 int WebRtcAgc_Analyze(void* agcInst, 154 const int16_t* const* inNear, 155 size_t num_bands, 156 size_t samples, 157 int32_t inMicLevel, 158 int32_t* outMicLevel, 159 int16_t echo, 160 uint8_t* saturationWarning, 161 int32_t gains[11]); 162 163 /* 164 * This function processes a 10 ms frame by applying precomputed digital gains. 165 * 166 * Input: 167 * - agcInst : AGC instance 168 * - gains : Vector of gains to apply for digital normalization 169 * - in_near : Near-end input speech vector for each band 170 * - num_bands : Number of bands in input/output vector 171 * 172 * Output: 173 * - out : Gain-adjusted near-end speech vector 174 * : May be the same vector as the input. 175 * 176 * Return value: 177 * : 0 - Normal operation. 178 * : -1 - Error 179 */ 180 int WebRtcAgc_Process(const void* agcInst, 181 const int32_t gains[11], 182 const int16_t* const* in_near, 183 size_t num_bands, 184 int16_t* const* out); 185 186 /* 187 * This function sets the config parameters (targetLevelDbfs, 188 * compressionGaindB and limiterEnable). 189 * 190 * Input: 191 * - agcInst : AGC instance 192 * - config : config struct 193 * 194 * Output: 195 * 196 * Return value: 197 * : 0 - Normal operation. 198 * : -1 - Error 199 */ 200 int WebRtcAgc_set_config(void* agcInst, WebRtcAgcConfig config); 201 202 /* 203 * This function returns the config parameters (targetLevelDbfs, 204 * compressionGaindB and limiterEnable). 205 * 206 * Input: 207 * - agcInst : AGC instance 208 * 209 * Output: 210 * - config : config struct 211 * 212 * Return value: 213 * : 0 - Normal operation. 214 * : -1 - Error 215 */ 216 int WebRtcAgc_get_config(void* agcInst, WebRtcAgcConfig* config); 217 218 /* 219 * This function creates and returns an AGC instance, which will contain the 220 * state information for one (duplex) channel. 221 */ 222 void* WebRtcAgc_Create(void); 223 224 /* 225 * This function frees the AGC instance created at the beginning. 226 * 227 * Input: 228 * - agcInst : AGC instance. 229 */ 230 void WebRtcAgc_Free(void* agcInst); 231 232 /* 233 * This function initializes an AGC instance. 234 * 235 * Input: 236 * - agcInst : AGC instance. 237 * - minLevel : Minimum possible mic level 238 * - maxLevel : Maximum possible mic level 239 * - agcMode : 0 - Unchanged 240 * : 1 - Adaptive Analog Automatic Gain Control -3dBOv 241 * : 2 - Adaptive Digital Automatic Gain Control -3dBOv 242 * : 3 - Fixed Digital Gain 0dB 243 * - fs : Sampling frequency 244 * 245 * Return value : 0 - Ok 246 * -1 - Error 247 */ 248 int WebRtcAgc_Init(void* agcInst, 249 int32_t minLevel, 250 int32_t maxLevel, 251 int16_t agcMode, 252 uint32_t fs); 253 254 } // namespace webrtc 255 256 #endif // MODULES_AUDIO_PROCESSING_AGC_LEGACY_GAIN_CONTROL_H_