1 /* 2 * Copyright (c) 2011 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_MAIN_INTERFACE_GAIN_CONTROL_H_ 12 #define WEBRTC_MODULES_AUDIO_PROCESSING_AGC_MAIN_INTERFACE_GAIN_CONTROL_H_ 13 14 #include "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 WebRtc_Word16 targetLevelDbfs; // default 3 (-3 dBOv) 43 WebRtc_Word16 compressionGaindB; // default 9 dB 44 WebRtc_UWord8 limiterEnable; // default kAgcTrue (on) 45 } WebRtcAgc_config_t; 46 47 #if defined(__cplusplus) 48 extern "C" 49 { 50 #endif 51 52 /* 53 * This function processes a 10/20ms frame of far-end speech to determine 54 * if there is active speech. Far-end speech length can be either 10ms or 55 * 20ms. The length of the input speech vector must be given in samples 56 * (80/160 when FS=8000, and 160/320 when FS=16000 or FS=32000). 57 * 58 * Input: 59 * - agcInst : AGC instance. 60 * - inFar : Far-end input speech vector (10 or 20ms) 61 * - samples : Number of samples in input vector 62 * 63 * Return value: 64 * : 0 - Normal operation. 65 * : -1 - Error 66 */ 67 int WebRtcAgc_AddFarend(void* agcInst, 68 const WebRtc_Word16* inFar, 69 WebRtc_Word16 samples); 70 71 /* 72 * This function processes a 10/20ms frame of microphone speech to determine 73 * if there is active speech. Microphone speech length can be either 10ms or 74 * 20ms. The length of the input speech vector must be given in samples 75 * (80/160 when FS=8000, and 160/320 when FS=16000 or FS=32000). For very low 76 * input levels, the input signal is increased in level by multiplying and 77 * overwriting the samples in inMic[]. 78 * 79 * This function should be called before any further processing of the 80 * near-end microphone signal. 81 * 82 * Input: 83 * - agcInst : AGC instance. 84 * - inMic : Microphone input speech vector (10 or 20 ms) for 85 * L band 86 * - inMic_H : Microphone input speech vector (10 or 20 ms) for 87 * H band 88 * - samples : Number of samples in input vector 89 * 90 * Return value: 91 * : 0 - Normal operation. 92 * : -1 - Error 93 */ 94 int WebRtcAgc_AddMic(void* agcInst, 95 WebRtc_Word16* inMic, 96 WebRtc_Word16* inMic_H, 97 WebRtc_Word16 samples); 98 99 /* 100 * This function replaces the analog microphone with a virtual one. 101 * It is a digital gain applied to the input signal and is used in the 102 * agcAdaptiveDigital mode where no microphone level is adjustable. 103 * Microphone speech length can be either 10ms or 20ms. The length of the 104 * input speech vector must be given in samples (80/160 when FS=8000, and 105 * 160/320 when FS=16000 or FS=32000). 106 * 107 * Input: 108 * - agcInst : AGC instance. 109 * - inMic : Microphone input speech vector for (10 or 20 ms) 110 * L band 111 * - inMic_H : Microphone input speech vector for (10 or 20 ms) 112 * H band 113 * - samples : Number of samples in input vector 114 * - micLevelIn : Input level of microphone (static) 115 * 116 * Output: 117 * - inMic : Microphone output after processing (L band) 118 * - inMic_H : Microphone output after processing (H band) 119 * - micLevelOut : Adjusted microphone level after processing 120 * 121 * Return value: 122 * : 0 - Normal operation. 123 * : -1 - Error 124 */ 125 int WebRtcAgc_VirtualMic(void* agcInst, 126 WebRtc_Word16* inMic, 127 WebRtc_Word16* inMic_H, 128 WebRtc_Word16 samples, 129 WebRtc_Word32 micLevelIn, 130 WebRtc_Word32* micLevelOut); 131 132 /* 133 * This function processes a 10/20ms frame and adjusts (normalizes) the gain 134 * both analog and digitally. The gain adjustments are done only during 135 * active periods of speech. The input speech length can be either 10ms or 136 * 20ms and the output is of the same length. The length of the speech 137 * vectors must be given in samples (80/160 when FS=8000, and 160/320 when 138 * FS=16000 or FS=32000). The echo parameter can be used to ensure the AGC will 139 * not adjust upward in the presence of echo. 140 * 141 * This function should be called after processing the near-end microphone 142 * signal, in any case after any echo cancellation. 143 * 144 * Input: 145 * - agcInst : AGC instance 146 * - inNear : Near-end input speech vector (10 or 20 ms) for 147 * L band 148 * - inNear_H : Near-end input speech vector (10 or 20 ms) for 149 * H band 150 * - samples : Number of samples in input/output vector 151 * - inMicLevel : Current microphone volume level 152 * - echo : Set to 0 if the signal passed to add_mic is 153 * almost certainly free of echo; otherwise set 154 * to 1. If you have no information regarding echo 155 * set to 0. 156 * 157 * Output: 158 * - outMicLevel : Adjusted microphone volume level 159 * - out : Gain-adjusted near-end speech vector (L band) 160 * : May be the same vector as the input. 161 * - out_H : Gain-adjusted near-end speech vector (H band) 162 * - saturationWarning : A returned value of 1 indicates a saturation event 163 * has occurred and the volume cannot be further 164 * reduced. Otherwise will be set to 0. 165 * 166 * Return value: 167 * : 0 - Normal operation. 168 * : -1 - Error 169 */ 170 int WebRtcAgc_Process(void* agcInst, 171 const WebRtc_Word16* inNear, 172 const WebRtc_Word16* inNear_H, 173 WebRtc_Word16 samples, 174 WebRtc_Word16* out, 175 WebRtc_Word16* out_H, 176 WebRtc_Word32 inMicLevel, 177 WebRtc_Word32* outMicLevel, 178 WebRtc_Word16 echo, 179 WebRtc_UWord8* saturationWarning); 180 181 /* 182 * This function sets the config parameters (targetLevelDbfs, 183 * compressionGaindB and limiterEnable). 184 * 185 * Input: 186 * - agcInst : AGC instance 187 * - config : config struct 188 * 189 * Output: 190 * 191 * Return value: 192 * : 0 - Normal operation. 193 * : -1 - Error 194 */ 195 int WebRtcAgc_set_config(void* agcInst, WebRtcAgc_config_t config); 196 197 /* 198 * This function returns the config parameters (targetLevelDbfs, 199 * compressionGaindB and limiterEnable). 200 * 201 * Input: 202 * - agcInst : AGC instance 203 * 204 * Output: 205 * - config : config struct 206 * 207 * Return value: 208 * : 0 - Normal operation. 209 * : -1 - Error 210 */ 211 int WebRtcAgc_get_config(void* agcInst, WebRtcAgc_config_t* config); 212 213 /* 214 * This function creates an AGC instance, which will contain the state 215 * information for one (duplex) channel. 216 * 217 * Return value : AGC instance if successful 218 * : 0 (i.e., a NULL pointer) if unsuccessful 219 */ 220 int WebRtcAgc_Create(void **agcInst); 221 222 /* 223 * This function frees the AGC instance created at the beginning. 224 * 225 * Input: 226 * - agcInst : AGC instance. 227 * 228 * Return value : 0 - Ok 229 * -1 - Error 230 */ 231 int WebRtcAgc_Free(void *agcInst); 232 233 /* 234 * This function initializes an AGC instance. 235 * 236 * Input: 237 * - agcInst : AGC instance. 238 * - minLevel : Minimum possible mic level 239 * - maxLevel : Maximum possible mic level 240 * - agcMode : 0 - Unchanged 241 * : 1 - Adaptive Analog Automatic Gain Control -3dBOv 242 * : 2 - Adaptive Digital Automatic Gain Control -3dBOv 243 * : 3 - Fixed Digital Gain 0dB 244 * - fs : Sampling frequency 245 * 246 * Return value : 0 - Ok 247 * -1 - Error 248 */ 249 int WebRtcAgc_Init(void *agcInst, 250 WebRtc_Word32 minLevel, 251 WebRtc_Word32 maxLevel, 252 WebRtc_Word16 agcMode, 253 WebRtc_UWord32 fs); 254 255 /* 256 * This function returns a text string containing the version. 257 * 258 * Input: 259 * - length : Length of the char array pointed to by version 260 * Output: 261 * - version : Pointer to a char array of to which the version 262 * : string will be copied. 263 * 264 * Return value : 0 - OK 265 * -1 - Error 266 */ 267 int WebRtcAgc_Version(WebRtc_Word8 *versionStr, WebRtc_Word16 length); 268 269 #if defined(__cplusplus) 270 } 271 #endif 272 273 #endif // WEBRTC_MODULES_AUDIO_PROCESSING_AGC_MAIN_INTERFACE_GAIN_CONTROL_H_ 274