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