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 "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 
26 enum {
27     kAecNlpConservative = 0,
28     kAecNlpModerate,
29     kAecNlpAggressive
30 };
31 
32 enum {
33     kAecFalse = 0,
34     kAecTrue
35 };
36 
37 typedef 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 
45 typedef struct {
46     WebRtc_Word16 instant;
47     WebRtc_Word16 average;
48     WebRtc_Word16 max;
49     WebRtc_Word16 min;
50 } AecLevel;
51 
52 typedef struct {
53     AecLevel rerl;
54     AecLevel erl;
55     AecLevel erle;
56     AecLevel aNlp;
57 } AecMetrics;
58 
59 #ifdef __cplusplus
60 extern "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  */
77 WebRtc_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  */
91 WebRtc_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  */
107 WebRtc_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  */
126 WebRtc_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  */
156 WebRtc_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  */
179 WebRtc_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  */
195 WebRtc_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  */
211 WebRtc_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  */
227 WebRtc_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  */
244 int 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  */
257 WebRtc_Word32 WebRtcAec_get_error_code(void *aecInst);
258 
259 #ifdef __cplusplus
260 }
261 #endif
262 #endif  // WEBRTC_MODULES_AUDIO_PROCESSING_AEC_INCLUDE_ECHO_CANCELLATION_H_
263