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
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    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)
48extern "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 */
64int 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 */
81int 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 */
105int 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 */
133int 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 */
174int 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 */
198int 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 */
214int 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 */
220void* WebRtcAgc_Create();
221
222/*
223 * This function frees the AGC instance created at the beginning.
224 *
225 * Input:
226 *      - agcInst           : AGC instance.
227 */
228void 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 */
246int 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