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
26enum
27{
28    kAgcModeUnchanged,
29    kAgcModeAdaptiveAnalog,
30    kAgcModeAdaptiveDigital,
31    kAgcModeFixedDigital
32};
33
34enum
35{
36    kAgcFalse = 0,
37    kAgcTrue
38};
39
40typedef 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)
48extern "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 */
67int 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 */
94int 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 */
125int 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 */
170int 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 */
195int 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 */
211int 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 */
220int 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 */
231int 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 */
249int 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 */
267int 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