blob: d5c703e46b47c0e9760f1e6df6199e679dd22b45 [file] [log] [blame]
niklase@google.com470e71d2011-07-07 08:21:25 +00001/*
andrew@webrtc.orgb9d7d932012-01-25 19:21:13 +00002 * Copyright (c) 2012 The WebRTC project authors. All Rights Reserved.
niklase@google.com470e71d2011-07-07 08:21:25 +00003 *
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
Mirko Bonadei92ea95e2017-09-15 06:47:31 +020011#ifndef MODULES_AUDIO_PROCESSING_AEC_ECHO_CANCELLATION_H_
12#define MODULES_AUDIO_PROCESSING_AEC_ECHO_CANCELLATION_H_
niklase@google.com470e71d2011-07-07 08:21:25 +000013
peah44c8a372016-05-05 13:34:29 -070014#include <memory>
15
Peter Kastingdce40cf2015-08-24 14:52:23 -070016#include <stddef.h>
17
peah44c8a372016-05-05 13:34:29 -070018extern "C" {
Mirko Bonadei92ea95e2017-09-15 06:47:31 +020019#include "common_audio/ring_buffer.h"
peah44c8a372016-05-05 13:34:29 -070020}
Mirko Bonadei92ea95e2017-09-15 06:47:31 +020021#include "modules/audio_processing/aec/aec_core.h"
Mirko Bonadei71207422017-09-15 13:58:09 +020022#include "typedefs.h" // NOLINT(build/include)
niklase@google.com470e71d2011-07-07 08:21:25 +000023
peah50e21bd2016-03-05 08:39:21 -080024namespace webrtc {
25
niklase@google.com470e71d2011-07-07 08:21:25 +000026// Errors
andrew@webrtc.org13b2d462013-10-08 23:41:42 +000027#define AEC_UNSPECIFIED_ERROR 12000
28#define AEC_UNSUPPORTED_FUNCTION_ERROR 12001
29#define AEC_UNINITIALIZED_ERROR 12002
30#define AEC_NULL_POINTER_ERROR 12003
31#define AEC_BAD_PARAMETER_ERROR 12004
niklase@google.com470e71d2011-07-07 08:21:25 +000032
33// Warnings
andrew@webrtc.org13b2d462013-10-08 23:41:42 +000034#define AEC_BAD_PARAMETER_WARNING 12050
niklase@google.com470e71d2011-07-07 08:21:25 +000035
peahff63ed22016-01-29 07:46:13 -080036enum { kAecNlpConservative = 0, kAecNlpModerate, kAecNlpAggressive };
niklase@google.com470e71d2011-07-07 08:21:25 +000037
peahff63ed22016-01-29 07:46:13 -080038enum { kAecFalse = 0, kAecTrue };
niklase@google.com470e71d2011-07-07 08:21:25 +000039
40typedef struct {
andrew@webrtc.org13b2d462013-10-08 23:41:42 +000041 int16_t nlpMode; // default kAecNlpModerate
42 int16_t skewMode; // default kAecFalse
43 int16_t metricsMode; // default kAecFalse
44 int delay_logging; // default kAecFalse
45 // float realSkew;
niklase@google.com470e71d2011-07-07 08:21:25 +000046} AecConfig;
47
48typedef struct {
bjornv@webrtc.orgb4cd3422013-02-15 18:40:34 +000049 int instant;
50 int average;
51 int max;
52 int min;
niklase@google.com470e71d2011-07-07 08:21:25 +000053} AecLevel;
54
55typedef struct {
andrew@webrtc.org13b2d462013-10-08 23:41:42 +000056 AecLevel rerl;
57 AecLevel erl;
58 AecLevel erle;
59 AecLevel aNlp;
minyue50453372016-04-07 06:36:43 -070060 float divergent_filter_fraction;
niklase@google.com470e71d2011-07-07 08:21:25 +000061} AecMetrics;
62
bjornv@webrtc.org132c15d2013-02-27 21:03:41 +000063struct AecCore;
64
peah44c8a372016-05-05 13:34:29 -070065class ApmDataDumper;
66
67typedef struct Aec {
kwiberg83ffe452016-08-29 14:46:07 -070068 Aec();
69 ~Aec();
70
peah44c8a372016-05-05 13:34:29 -070071 std::unique_ptr<ApmDataDumper> data_dumper;
72
73 int delayCtr;
74 int sampFreq;
75 int splitSampFreq;
76 int scSampFreq;
77 float sampFactor; // scSampRate / sampFreq
78 short skewMode;
79 int bufSizeStart;
80 int knownDelay;
81 int rate_factor;
82
83 short initFlag; // indicates if AEC has been initialized
84
85 // Variables used for averaging far end buffer size
86 short counter;
87 int sum;
88 short firstVal;
89 short checkBufSizeCtr;
90
91 // Variables used for delay shifts
92 short msInSndCardBuf;
93 short filtDelay; // Filtered delay estimate.
94 int timeForDelayChange;
95 int startup_phase;
96 int checkBuffSize;
97 short lastDelayDiff;
98
99 // Structures
100 void* resampler;
101
102 int skewFrCtr;
103 int resample; // if the skew is small enough we don't resample
104 int highSkewCtr;
105 float skew;
106
107 RingBuffer* far_pre_buf; // Time domain far-end pre-buffer.
108
109 int farend_started;
110
111 // Aec instance counter.
112 static int instance_count;
113 AecCore* aec;
114} Aec;
115
niklase@google.com470e71d2011-07-07 08:21:25 +0000116/*
117 * Allocates the memory needed by the AEC. The memory needs to be initialized
Bjorn Volcker9345e862015-06-10 21:43:36 +0200118 * separately using the WebRtcAec_Init() function. Returns a pointer to the
119 * object or NULL on error.
niklase@google.com470e71d2011-07-07 08:21:25 +0000120 */
Bjorn Volcker9345e862015-06-10 21:43:36 +0200121void* WebRtcAec_Create();
niklase@google.com470e71d2011-07-07 08:21:25 +0000122
123/*
124 * This function releases the memory allocated by WebRtcAec_Create().
125 *
126 * Inputs Description
127 * -------------------------------------------------------------------
kwiberg@webrtc.org924e81f2014-05-12 09:55:19 +0000128 * void* aecInst Pointer to the AEC instance
niklase@google.com470e71d2011-07-07 08:21:25 +0000129 */
Bjorn Volckerf6a99e62015-04-10 07:56:57 +0200130void WebRtcAec_Free(void* aecInst);
niklase@google.com470e71d2011-07-07 08:21:25 +0000131
132/*
133 * Initializes an AEC instance.
134 *
135 * Inputs Description
136 * -------------------------------------------------------------------
kwiberg@webrtc.org924e81f2014-05-12 09:55:19 +0000137 * void* aecInst Pointer to the AEC instance
pbos@webrtc.orgb7192b82013-04-10 07:50:54 +0000138 * int32_t sampFreq Sampling frequency of data
139 * int32_t scSampFreq Soundcard sampling frequency
niklase@google.com470e71d2011-07-07 08:21:25 +0000140 *
141 * Outputs Description
142 * -------------------------------------------------------------------
pbos@webrtc.orgb7192b82013-04-10 07:50:54 +0000143 * int32_t return 0: OK
144 * -1: error
niklase@google.com470e71d2011-07-07 08:21:25 +0000145 */
andrew@webrtc.org13b2d462013-10-08 23:41:42 +0000146int32_t WebRtcAec_Init(void* aecInst, int32_t sampFreq, int32_t scSampFreq);
niklase@google.com470e71d2011-07-07 08:21:25 +0000147
148/*
149 * Inserts an 80 or 160 sample block of data into the farend buffer.
150 *
151 * Inputs Description
152 * -------------------------------------------------------------------
kwiberg@webrtc.org924e81f2014-05-12 09:55:19 +0000153 * void* aecInst Pointer to the AEC instance
kwiberg@webrtc.org38214d52014-07-03 09:47:33 +0000154 * const float* farend In buffer containing one frame of
niklase@google.com470e71d2011-07-07 08:21:25 +0000155 * farend signal for L band
pbos@webrtc.orgb7192b82013-04-10 07:50:54 +0000156 * int16_t nrOfSamples Number of samples in farend buffer
niklase@google.com470e71d2011-07-07 08:21:25 +0000157 *
158 * Outputs Description
159 * -------------------------------------------------------------------
pbos@webrtc.orgb7192b82013-04-10 07:50:54 +0000160 * int32_t return 0: OK
peahc12be392015-11-09 23:53:50 -0800161 * 12000-12050: error code
niklase@google.com470e71d2011-07-07 08:21:25 +0000162 */
andrew@webrtc.org13b2d462013-10-08 23:41:42 +0000163int32_t WebRtcAec_BufferFarend(void* aecInst,
kwiberg@webrtc.org38214d52014-07-03 09:47:33 +0000164 const float* farend,
Peter Kastingdce40cf2015-08-24 14:52:23 -0700165 size_t nrOfSamples);
niklase@google.com470e71d2011-07-07 08:21:25 +0000166
167/*
peahc12be392015-11-09 23:53:50 -0800168 * Reports any errors that would arise if buffering a farend buffer
169 *
170 * Inputs Description
171 * -------------------------------------------------------------------
172 * void* aecInst Pointer to the AEC instance
173 * const float* farend In buffer containing one frame of
174 * farend signal for L band
175 * int16_t nrOfSamples Number of samples in farend buffer
176 *
177 * Outputs Description
178 * -------------------------------------------------------------------
179 * int32_t return 0: OK
180 * 12000-12050: error code
181 */
182int32_t WebRtcAec_GetBufferFarendError(void* aecInst,
183 const float* farend,
184 size_t nrOfSamples);
185
186/*
niklase@google.com470e71d2011-07-07 08:21:25 +0000187 * Runs the echo canceller on an 80 or 160 sample blocks of data.
188 *
189 * Inputs Description
190 * -------------------------------------------------------------------
kwiberg@webrtc.org924e81f2014-05-12 09:55:19 +0000191 * void* aecInst Pointer to the AEC instance
aluebs@webrtc.orgc78d81a2015-01-21 19:10:55 +0000192 * float* const* nearend In buffer containing one frame of
193 * nearend+echo signal for each band
194 * int num_bands Number of bands in nearend buffer
pbos@webrtc.orgb7192b82013-04-10 07:50:54 +0000195 * int16_t nrOfSamples Number of samples in nearend buffer
196 * int16_t msInSndCardBuf Delay estimate for sound card and
niklase@google.com470e71d2011-07-07 08:21:25 +0000197 * system buffers
pbos@webrtc.orgb7192b82013-04-10 07:50:54 +0000198 * int16_t skew Difference between number of samples played
niklase@google.com470e71d2011-07-07 08:21:25 +0000199 * and recorded at the soundcard (for clock skew
200 * compensation)
201 *
202 * Outputs Description
203 * -------------------------------------------------------------------
aluebs@webrtc.orgc78d81a2015-01-21 19:10:55 +0000204 * float* const* out Out buffer, one frame of processed nearend
205 * for each band
pbos@webrtc.orgb7192b82013-04-10 07:50:54 +0000206 * int32_t return 0: OK
peahc12be392015-11-09 23:53:50 -0800207 * 12000-12050: error code
niklase@google.com470e71d2011-07-07 08:21:25 +0000208 */
andrew@webrtc.org13b2d462013-10-08 23:41:42 +0000209int32_t WebRtcAec_Process(void* aecInst,
aluebs@webrtc.orgc78d81a2015-01-21 19:10:55 +0000210 const float* const* nearend,
Peter Kastingdce40cf2015-08-24 14:52:23 -0700211 size_t num_bands,
aluebs@webrtc.orgc78d81a2015-01-21 19:10:55 +0000212 float* const* out,
Peter Kastingdce40cf2015-08-24 14:52:23 -0700213 size_t nrOfSamples,
pbos@webrtc.orgb7192b82013-04-10 07:50:54 +0000214 int16_t msInSndCardBuf,
215 int32_t skew);
niklase@google.com470e71d2011-07-07 08:21:25 +0000216
217/*
218 * This function enables the user to set certain parameters on-the-fly.
219 *
220 * Inputs Description
221 * -------------------------------------------------------------------
kwiberg@webrtc.org924e81f2014-05-12 09:55:19 +0000222 * void* handle Pointer to the AEC instance
niklase@google.com470e71d2011-07-07 08:21:25 +0000223 * AecConfig config Config instance that contains all
224 * properties to be set
225 *
226 * Outputs Description
227 * -------------------------------------------------------------------
peahc12be392015-11-09 23:53:50 -0800228 * int return 0: OK
229 * 12000-12050: error code
niklase@google.com470e71d2011-07-07 08:21:25 +0000230 */
bjornv@webrtc.org47b274d2013-02-20 17:09:47 +0000231int WebRtcAec_set_config(void* handle, AecConfig config);
niklase@google.com470e71d2011-07-07 08:21:25 +0000232
233/*
niklase@google.com470e71d2011-07-07 08:21:25 +0000234 * Gets the current echo status of the nearend signal.
235 *
236 * Inputs Description
237 * -------------------------------------------------------------------
kwiberg@webrtc.org924e81f2014-05-12 09:55:19 +0000238 * void* handle Pointer to the AEC instance
niklase@google.com470e71d2011-07-07 08:21:25 +0000239 *
240 * Outputs Description
241 * -------------------------------------------------------------------
kwiberg@webrtc.org924e81f2014-05-12 09:55:19 +0000242 * int* status 0: Almost certainly nearend single-talk
niklase@google.com470e71d2011-07-07 08:21:25 +0000243 * 1: Might not be neared single-talk
peahc12be392015-11-09 23:53:50 -0800244 * int return 0: OK
245 * 12000-12050: error code
niklase@google.com470e71d2011-07-07 08:21:25 +0000246 */
bjornv@webrtc.org21a2fc92013-02-15 17:01:03 +0000247int WebRtcAec_get_echo_status(void* handle, int* status);
niklase@google.com470e71d2011-07-07 08:21:25 +0000248
249/*
250 * Gets the current echo metrics for the session.
251 *
252 * Inputs Description
253 * -------------------------------------------------------------------
kwiberg@webrtc.org924e81f2014-05-12 09:55:19 +0000254 * void* handle Pointer to the AEC instance
niklase@google.com470e71d2011-07-07 08:21:25 +0000255 *
256 * Outputs Description
257 * -------------------------------------------------------------------
kwiberg@webrtc.org924e81f2014-05-12 09:55:19 +0000258 * AecMetrics* metrics Struct which will be filled out with the
niklase@google.com470e71d2011-07-07 08:21:25 +0000259 * current echo metrics.
peahc12be392015-11-09 23:53:50 -0800260 * int return 0: OK
261 * 12000-12050: error code
niklase@google.com470e71d2011-07-07 08:21:25 +0000262 */
bjornv@webrtc.orgb4cd3422013-02-15 18:40:34 +0000263int WebRtcAec_GetMetrics(void* handle, AecMetrics* metrics);
niklase@google.com470e71d2011-07-07 08:21:25 +0000264
265/*
bjornv@google.com1ba3dbe2011-10-03 08:18:10 +0000266 * Gets the current delay metrics for the session.
267 *
268 * Inputs Description
269 * -------------------------------------------------------------------
bjornv@webrtc.orgb1786db2015-02-03 06:06:26 +0000270 * void* handle Pointer to the AEC instance
bjornv@google.com1ba3dbe2011-10-03 08:18:10 +0000271 *
272 * Outputs Description
273 * -------------------------------------------------------------------
bjornv@webrtc.orgb1786db2015-02-03 06:06:26 +0000274 * int* median Delay median value.
275 * int* std Delay standard deviation.
276 * float* fraction_poor_delays Fraction of the delay estimates that may
277 * cause the AEC to perform poorly.
bjornv@google.com1ba3dbe2011-10-03 08:18:10 +0000278 *
peahc12be392015-11-09 23:53:50 -0800279 * int return 0: OK
280 * 12000-12050: error code
bjornv@google.com1ba3dbe2011-10-03 08:18:10 +0000281 */
bjornv@webrtc.orgb1786db2015-02-03 06:06:26 +0000282int WebRtcAec_GetDelayMetrics(void* handle,
283 int* median,
284 int* std,
285 float* fraction_poor_delays);
bjornv@google.com1ba3dbe2011-10-03 08:18:10 +0000286
bjornv@webrtc.org132c15d2013-02-27 21:03:41 +0000287// Returns a pointer to the low level AEC handle.
288//
289// Input:
290// - handle : Pointer to the AEC instance.
291//
292// Return value:
293// - AecCore pointer : NULL for error.
294//
295struct AecCore* WebRtcAec_aec_core(void* handle);
296
peah50e21bd2016-03-05 08:39:21 -0800297} // namespace webrtc
298
Mirko Bonadei92ea95e2017-09-15 06:47:31 +0200299#endif // MODULES_AUDIO_PROCESSING_AEC_ECHO_CANCELLATION_H_