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