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_AEC_MAIN_INTERFACE_ECHO_CANCELLATION_H_
12#define WEBRTC_MODULES_AUDIO_PROCESSING_AEC_MAIN_INTERFACE_ECHO_CANCELLATION_H_
13
14#include "typedefs.h"
15
16// Errors
17#define AEC_UNSPECIFIED_ERROR           12000
18#define AEC_UNSUPPORTED_FUNCTION_ERROR  12001
19#define AEC_UNINITIALIZED_ERROR         12002
20#define AEC_NULL_POINTER_ERROR          12003
21#define AEC_BAD_PARAMETER_ERROR         12004
22
23// Warnings
24#define AEC_BAD_PARAMETER_WARNING       12050
25
26enum {
27    kAecNlpConservative = 0,
28    kAecNlpModerate,
29    kAecNlpAggressive
30};
31
32enum {
33    kAecFalse = 0,
34    kAecTrue
35};
36
37typedef struct {
38    WebRtc_Word16 nlpMode;        // default kAecNlpModerate
39    WebRtc_Word16 skewMode;       // default kAecFalse
40    WebRtc_Word16 metricsMode;    // default kAecFalse
41    int delay_logging;            // default kAecFalse
42    //float realSkew;
43} AecConfig;
44
45typedef struct {
46    WebRtc_Word16 instant;
47    WebRtc_Word16 average;
48    WebRtc_Word16 max;
49    WebRtc_Word16 min;
50} AecLevel;
51
52typedef struct {
53    AecLevel rerl;
54    AecLevel erl;
55    AecLevel erle;
56    AecLevel aNlp;
57} AecMetrics;
58
59#ifdef __cplusplus
60extern "C" {
61#endif
62
63/*
64 * Allocates the memory needed by the AEC. The memory needs to be initialized
65 * separately using the WebRtcAec_Init() function.
66 *
67 * Inputs                       Description
68 * -------------------------------------------------------------------
69 * void **aecInst               Pointer to the AEC instance to be created
70 *                              and initialized
71 *
72 * Outputs                      Description
73 * -------------------------------------------------------------------
74 * WebRtc_Word32 return          0: OK
75 *                              -1: error
76 */
77WebRtc_Word32 WebRtcAec_Create(void **aecInst);
78
79/*
80 * This function releases the memory allocated by WebRtcAec_Create().
81 *
82 * Inputs                       Description
83 * -------------------------------------------------------------------
84 * void         *aecInst        Pointer to the AEC instance
85 *
86 * Outputs                      Description
87 * -------------------------------------------------------------------
88 * WebRtc_Word32  return         0: OK
89 *                              -1: error
90 */
91WebRtc_Word32 WebRtcAec_Free(void *aecInst);
92
93/*
94 * Initializes an AEC instance.
95 *
96 * Inputs                       Description
97 * -------------------------------------------------------------------
98 * void           *aecInst      Pointer to the AEC instance
99 * WebRtc_Word32  sampFreq      Sampling frequency of data
100 * WebRtc_Word32  scSampFreq    Soundcard sampling frequency
101 *
102 * Outputs                      Description
103 * -------------------------------------------------------------------
104 * WebRtc_Word32 return          0: OK
105 *                              -1: error
106 */
107WebRtc_Word32 WebRtcAec_Init(void *aecInst,
108                             WebRtc_Word32 sampFreq,
109                             WebRtc_Word32 scSampFreq);
110
111/*
112 * Inserts an 80 or 160 sample block of data into the farend buffer.
113 *
114 * Inputs                       Description
115 * -------------------------------------------------------------------
116 * void           *aecInst      Pointer to the AEC instance
117 * WebRtc_Word16  *farend       In buffer containing one frame of
118 *                              farend signal for L band
119 * WebRtc_Word16  nrOfSamples   Number of samples in farend buffer
120 *
121 * Outputs                      Description
122 * -------------------------------------------------------------------
123 * WebRtc_Word32  return         0: OK
124 *                              -1: error
125 */
126WebRtc_Word32 WebRtcAec_BufferFarend(void *aecInst,
127                                     const WebRtc_Word16 *farend,
128                                     WebRtc_Word16 nrOfSamples);
129
130/*
131 * Runs the echo canceller on an 80 or 160 sample blocks of data.
132 *
133 * Inputs                       Description
134 * -------------------------------------------------------------------
135 * void          *aecInst       Pointer to the AEC instance
136 * WebRtc_Word16 *nearend       In buffer containing one frame of
137 *                              nearend+echo signal for L band
138 * WebRtc_Word16 *nearendH      In buffer containing one frame of
139 *                              nearend+echo signal for H band
140 * WebRtc_Word16 nrOfSamples    Number of samples in nearend buffer
141 * WebRtc_Word16 msInSndCardBuf Delay estimate for sound card and
142 *                              system buffers
143 * WebRtc_Word16 skew           Difference between number of samples played
144 *                              and recorded at the soundcard (for clock skew
145 *                              compensation)
146 *
147 * Outputs                      Description
148 * -------------------------------------------------------------------
149 * WebRtc_Word16  *out          Out buffer, one frame of processed nearend
150 *                              for L band
151 * WebRtc_Word16  *outH         Out buffer, one frame of processed nearend
152 *                              for H band
153 * WebRtc_Word32  return         0: OK
154 *                              -1: error
155 */
156WebRtc_Word32 WebRtcAec_Process(void *aecInst,
157                                const WebRtc_Word16 *nearend,
158                                const WebRtc_Word16 *nearendH,
159                                WebRtc_Word16 *out,
160                                WebRtc_Word16 *outH,
161                                WebRtc_Word16 nrOfSamples,
162                                WebRtc_Word16 msInSndCardBuf,
163                                WebRtc_Word32 skew);
164
165/*
166 * This function enables the user to set certain parameters on-the-fly.
167 *
168 * Inputs                       Description
169 * -------------------------------------------------------------------
170 * void           *aecInst      Pointer to the AEC instance
171 * AecConfig      config        Config instance that contains all
172 *                              properties to be set
173 *
174 * Outputs                      Description
175 * -------------------------------------------------------------------
176 * WebRtc_Word32  return         0: OK
177 *                              -1: error
178 */
179WebRtc_Word32 WebRtcAec_set_config(void *aecInst, AecConfig config);
180
181/*
182 * Gets the on-the-fly paramters.
183 *
184 * Inputs                       Description
185 * -------------------------------------------------------------------
186 * void           *aecInst      Pointer to the AEC instance
187 *
188 * Outputs                      Description
189 * -------------------------------------------------------------------
190 * AecConfig      *config       Pointer to the config instance that
191 *                              all properties will be written to
192 * WebRtc_Word32  return         0: OK
193 *                              -1: error
194 */
195WebRtc_Word32 WebRtcAec_get_config(void *aecInst, AecConfig *config);
196
197/*
198 * Gets the current echo status of the nearend signal.
199 *
200 * Inputs                       Description
201 * -------------------------------------------------------------------
202 * void           *aecInst      Pointer to the AEC instance
203 *
204 * Outputs                      Description
205 * -------------------------------------------------------------------
206 * WebRtc_Word16  *status       0: Almost certainly nearend single-talk
207 *                              1: Might not be neared single-talk
208 * WebRtc_Word32  return         0: OK
209 *                              -1: error
210 */
211WebRtc_Word32 WebRtcAec_get_echo_status(void *aecInst, WebRtc_Word16 *status);
212
213/*
214 * Gets the current echo metrics for the session.
215 *
216 * Inputs                       Description
217 * -------------------------------------------------------------------
218 * void           *aecInst      Pointer to the AEC instance
219 *
220 * Outputs                      Description
221 * -------------------------------------------------------------------
222 * AecMetrics     *metrics      Struct which will be filled out with the
223 *                              current echo metrics.
224 * WebRtc_Word32  return         0: OK
225 *                              -1: error
226 */
227WebRtc_Word32 WebRtcAec_GetMetrics(void *aecInst, AecMetrics *metrics);
228
229/*
230 * Gets the current delay metrics for the session.
231 *
232 * Inputs                       Description
233 * -------------------------------------------------------------------
234 * void*      handle            Pointer to the AEC instance
235 *
236 * Outputs                      Description
237 * -------------------------------------------------------------------
238 * int*       median            Delay median value.
239 * int*       std               Delay standard deviation.
240 *
241 * int        return             0: OK
242 *                              -1: error
243 */
244int WebRtcAec_GetDelayMetrics(void* handle, int* median, int* std);
245
246/*
247 * Gets the last error code.
248 *
249 * Inputs                       Description
250 * -------------------------------------------------------------------
251 * void           *aecInst      Pointer to the AEC instance
252 *
253 * Outputs                      Description
254 * -------------------------------------------------------------------
255 * WebRtc_Word32  return        11000-11100: error code
256 */
257WebRtc_Word32 WebRtcAec_get_error_code(void *aecInst);
258
259/*
260 * Gets a version string.
261 *
262 * Inputs                       Description
263 * -------------------------------------------------------------------
264 * char           *versionStr   Pointer to a string array
265 * WebRtc_Word16  len           The maximum length of the string
266 *
267 * Outputs                      Description
268 * -------------------------------------------------------------------
269 * WebRtc_Word8   *versionStr   Pointer to a string array
270 * WebRtc_Word32  return         0: OK
271 *                              -1: error
272 */
273WebRtc_Word32 WebRtcAec_get_version(WebRtc_Word8 *versionStr, WebRtc_Word16 len);
274
275#ifdef __cplusplus
276}
277#endif
278#endif  /* WEBRTC_MODULES_AUDIO_PROCESSING_AEC_MAIN_INTERFACE_ECHO_CANCELLATION_H_ */
279