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_AEC_INCLUDE_ECHO_CANCELLATION_H_
12#define WEBRTC_MODULES_AUDIO_PROCESSING_AEC_INCLUDE_ECHO_CANCELLATION_H_
13
14#include "webrtc/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  int16_t nlpMode;      // default kAecNlpModerate
39  int16_t skewMode;     // default kAecFalse
40  int16_t metricsMode;  // default kAecFalse
41  int delay_logging;    // default kAecFalse
42  // float realSkew;
43} AecConfig;
44
45typedef struct {
46  int instant;
47  int average;
48  int max;
49  int min;
50} AecLevel;
51
52typedef struct {
53  AecLevel rerl;
54  AecLevel erl;
55  AecLevel erle;
56  AecLevel aNlp;
57} AecMetrics;
58
59struct AecCore;
60
61#ifdef __cplusplus
62extern "C" {
63#endif
64
65/*
66 * Allocates the memory needed by the AEC. The memory needs to be initialized
67 * separately using the WebRtcAec_Init() function.
68 *
69 * Inputs                       Description
70 * -------------------------------------------------------------------
71 * void**  aecInst              Pointer to the AEC instance to be created
72 *                              and initialized
73 *
74 * Outputs                      Description
75 * -------------------------------------------------------------------
76 * int32_t return               0: OK
77 *                             -1: error
78 */
79int32_t WebRtcAec_Create(void** aecInst);
80
81/*
82 * This function releases the memory allocated by WebRtcAec_Create().
83 *
84 * Inputs                       Description
85 * -------------------------------------------------------------------
86 * void*        aecInst         Pointer to the AEC instance
87 *
88 * Outputs                      Description
89 * -------------------------------------------------------------------
90 * int32_t      return          0: OK
91 *                             -1: error
92 */
93int32_t WebRtcAec_Free(void* aecInst);
94
95/*
96 * Initializes an AEC instance.
97 *
98 * Inputs                       Description
99 * -------------------------------------------------------------------
100 * void*          aecInst       Pointer to the AEC instance
101 * int32_t        sampFreq      Sampling frequency of data
102 * int32_t        scSampFreq    Soundcard sampling frequency
103 *
104 * Outputs                      Description
105 * -------------------------------------------------------------------
106 * int32_t        return        0: OK
107 *                             -1: error
108 */
109int32_t WebRtcAec_Init(void* aecInst, int32_t sampFreq, int32_t 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 * const float*   farend        In buffer containing one frame of
118 *                              farend signal for L band
119 * int16_t        nrOfSamples   Number of samples in farend buffer
120 *
121 * Outputs                      Description
122 * -------------------------------------------------------------------
123 * int32_t        return        0: OK
124 *                             -1: error
125 */
126int32_t WebRtcAec_BufferFarend(void* aecInst,
127                               const float* farend,
128                               int16_t 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 * float*        nearend        In buffer containing one frame of
137 *                              nearend+echo signal for L band
138 * float*        nearendH       In buffer containing one frame of
139 *                              nearend+echo signal for H band
140 * int16_t       nrOfSamples    Number of samples in nearend buffer
141 * int16_t       msInSndCardBuf Delay estimate for sound card and
142 *                              system buffers
143 * int16_t       skew           Difference between number of samples played
144 *                              and recorded at the soundcard (for clock skew
145 *                              compensation)
146 *
147 * Outputs                      Description
148 * -------------------------------------------------------------------
149 * float*        out            Out buffer, one frame of processed nearend
150 *                              for L band
151 * float*        outH           Out buffer, one frame of processed nearend
152 *                              for H band
153 * int32_t       return         0: OK
154 *                             -1: error
155 */
156int32_t WebRtcAec_Process(void* aecInst,
157                          const float* nearend,
158                          const float* nearendH,
159                          float* out,
160                          float* outH,
161                          int16_t nrOfSamples,
162                          int16_t msInSndCardBuf,
163                          int32_t skew);
164
165/*
166 * This function enables the user to set certain parameters on-the-fly.
167 *
168 * Inputs                       Description
169 * -------------------------------------------------------------------
170 * void*          handle        Pointer to the AEC instance
171 * AecConfig      config        Config instance that contains all
172 *                              properties to be set
173 *
174 * Outputs                      Description
175 * -------------------------------------------------------------------
176 * int            return         0: OK
177 *                              -1: error
178 */
179int WebRtcAec_set_config(void* handle, AecConfig config);
180
181/*
182 * Gets the current echo status of the nearend signal.
183 *
184 * Inputs                       Description
185 * -------------------------------------------------------------------
186 * void*          handle        Pointer to the AEC instance
187 *
188 * Outputs                      Description
189 * -------------------------------------------------------------------
190 * int*           status        0: Almost certainly nearend single-talk
191 *                              1: Might not be neared single-talk
192 * int            return         0: OK
193 *                              -1: error
194 */
195int WebRtcAec_get_echo_status(void* handle, int* status);
196
197/*
198 * Gets the current echo metrics for the session.
199 *
200 * Inputs                       Description
201 * -------------------------------------------------------------------
202 * void*          handle        Pointer to the AEC instance
203 *
204 * Outputs                      Description
205 * -------------------------------------------------------------------
206 * AecMetrics*    metrics       Struct which will be filled out with the
207 *                              current echo metrics.
208 * int            return         0: OK
209 *                              -1: error
210 */
211int WebRtcAec_GetMetrics(void* handle, AecMetrics* metrics);
212
213/*
214 * Gets the current delay metrics for the session.
215 *
216 * Inputs                       Description
217 * -------------------------------------------------------------------
218 * void*      handle            Pointer to the AEC instance
219 *
220 * Outputs                      Description
221 * -------------------------------------------------------------------
222 * int*       median            Delay median value.
223 * int*       std               Delay standard deviation.
224 *
225 * int        return             0: OK
226 *                              -1: error
227 */
228int WebRtcAec_GetDelayMetrics(void* handle, int* median, int* std);
229
230/*
231 * Gets the last error code.
232 *
233 * Inputs                       Description
234 * -------------------------------------------------------------------
235 * void*          aecInst       Pointer to the AEC instance
236 *
237 * Outputs                      Description
238 * -------------------------------------------------------------------
239 * int32_t        return        11000-11100: error code
240 */
241int32_t WebRtcAec_get_error_code(void* aecInst);
242
243// Returns a pointer to the low level AEC handle.
244//
245// Input:
246//  - handle                    : Pointer to the AEC instance.
247//
248// Return value:
249//  - AecCore pointer           : NULL for error.
250//
251struct AecCore* WebRtcAec_aec_core(void* handle);
252
253#ifdef __cplusplus
254}
255#endif
256#endif  // WEBRTC_MODULES_AUDIO_PROCESSING_AEC_INCLUDE_ECHO_CANCELLATION_H_
257