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 <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 * -1: error 113 */ 114 int32_t WebRtcAec_BufferFarend(void* aecInst, 115 const float* farend, 116 size_t nrOfSamples); 117 118 /* 119 * Runs the echo canceller on an 80 or 160 sample blocks of data. 120 * 121 * Inputs Description 122 * ------------------------------------------------------------------- 123 * void* aecInst Pointer to the AEC instance 124 * float* const* nearend In buffer containing one frame of 125 * nearend+echo signal for each band 126 * int num_bands Number of bands in nearend buffer 127 * int16_t nrOfSamples Number of samples in nearend buffer 128 * int16_t msInSndCardBuf Delay estimate for sound card and 129 * system buffers 130 * int16_t skew Difference between number of samples played 131 * and recorded at the soundcard (for clock skew 132 * compensation) 133 * 134 * Outputs Description 135 * ------------------------------------------------------------------- 136 * float* const* out Out buffer, one frame of processed nearend 137 * for each band 138 * int32_t return 0: OK 139 * -1: error 140 */ 141 int32_t WebRtcAec_Process(void* aecInst, 142 const float* const* nearend, 143 size_t num_bands, 144 float* const* out, 145 size_t nrOfSamples, 146 int16_t msInSndCardBuf, 147 int32_t skew); 148 149 /* 150 * This function enables the user to set certain parameters on-the-fly. 151 * 152 * Inputs Description 153 * ------------------------------------------------------------------- 154 * void* handle Pointer to the AEC instance 155 * AecConfig config Config instance that contains all 156 * properties to be set 157 * 158 * Outputs Description 159 * ------------------------------------------------------------------- 160 * int return 0: OK 161 * -1: error 162 */ 163 int WebRtcAec_set_config(void* handle, AecConfig config); 164 165 /* 166 * Gets the current echo status of the nearend signal. 167 * 168 * Inputs Description 169 * ------------------------------------------------------------------- 170 * void* handle Pointer to the AEC instance 171 * 172 * Outputs Description 173 * ------------------------------------------------------------------- 174 * int* status 0: Almost certainly nearend single-talk 175 * 1: Might not be neared single-talk 176 * int return 0: OK 177 * -1: error 178 */ 179 int WebRtcAec_get_echo_status(void* handle, int* status); 180 181 /* 182 * Gets the current echo metrics for the session. 183 * 184 * Inputs Description 185 * ------------------------------------------------------------------- 186 * void* handle Pointer to the AEC instance 187 * 188 * Outputs Description 189 * ------------------------------------------------------------------- 190 * AecMetrics* metrics Struct which will be filled out with the 191 * current echo metrics. 192 * int return 0: OK 193 * -1: error 194 */ 195 int WebRtcAec_GetMetrics(void* handle, AecMetrics* metrics); 196 197 /* 198 * Gets the current delay metrics for the session. 199 * 200 * Inputs Description 201 * ------------------------------------------------------------------- 202 * void* handle Pointer to the AEC instance 203 * 204 * Outputs Description 205 * ------------------------------------------------------------------- 206 * int* median Delay median value. 207 * int* std Delay standard deviation. 208 * float* fraction_poor_delays Fraction of the delay estimates that may 209 * cause the AEC to perform poorly. 210 * 211 * int return 0: OK 212 * -1: error 213 */ 214 int WebRtcAec_GetDelayMetrics(void* handle, 215 int* median, 216 int* std, 217 float* fraction_poor_delays); 218 219 /* 220 * Gets the last error code. 221 * 222 * Inputs Description 223 * ------------------------------------------------------------------- 224 * void* aecInst Pointer to the AEC instance 225 * 226 * Outputs Description 227 * ------------------------------------------------------------------- 228 * int32_t return 11000-11100: error code 229 */ 230 int32_t WebRtcAec_get_error_code(void* aecInst); 231 232 // Returns a pointer to the low level AEC handle. 233 // 234 // Input: 235 // - handle : Pointer to the AEC instance. 236 // 237 // Return value: 238 // - AecCore pointer : NULL for error. 239 // 240 struct AecCore* WebRtcAec_aec_core(void* handle); 241 242 #ifdef __cplusplus 243 } 244 #endif 245 #endif // WEBRTC_MODULES_AUDIO_PROCESSING_AEC_INCLUDE_ECHO_CANCELLATION_H_ 246