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