• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 
28 enum {
29   kAecNlpConservative = 0,
30   kAecNlpModerate,
31   kAecNlpAggressive
32 };
33 
34 enum {
35   kAecFalse = 0,
36   kAecTrue
37 };
38 
39 typedef 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 
47 typedef struct {
48   int instant;
49   int average;
50   int max;
51   int min;
52 } AecLevel;
53 
54 typedef struct {
55   AecLevel rerl;
56   AecLevel erl;
57   AecLevel erle;
58   AecLevel aNlp;
59 } AecMetrics;
60 
61 struct AecCore;
62 
63 #ifdef __cplusplus
64 extern "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  */
72 void* 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  */
81 void 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  */
97 int32_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  */
114 int32_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  */
133 int32_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  */
160 int32_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  */
182 int 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  */
198 int 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  */
214 int 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  */
233 int 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 //
246 struct AecCore* WebRtcAec_aec_core(void* handle);
247 
248 #ifdef __cplusplus
249 }
250 #endif
251 #endif  // WEBRTC_MODULES_AUDIO_PROCESSING_AEC_ECHO_CANCELLATION_H_
252