src/third_party/webrtc/modules/audio_processing/aec/include/echo_cancellation.h

   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 "webrtc/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   int16_t nlpMode;      // default kAecNlpModerate
  39   int16_t skewMode;     // default kAecFalse
  40   int16_t metricsMode;  // default kAecFalse
  41   int delay_logging;    // default kAecFalse
  42   // float realSkew;
  43 } AecConfig;
  44
  45 typedef struct {
  46   int instant;
  47   int average;
  48   int max;
  49   int min;
  50 } AecLevel;
  51
  52 typedef struct {
  53   AecLevel rerl;
  54   AecLevel erl;
  55   AecLevel erle;
  56   AecLevel aNlp;
  57 } AecMetrics;
  58
  59 struct AecCore;
  60
  61 #ifdef __cplusplus
  62 extern "C" {
  63 #endif
  64
  65 /*
  66  * Allocates the memory needed by the AEC. The memory needs to be initialized
  67  * separately using the WebRtcAec_Init() function.
  68  *
  69  * Inputs                       Description
  70  * -------------------------------------------------------------------
  71  * void**  aecInst              Pointer to the AEC instance to be created
  72  *                              and initialized
  73  *
  74  * Outputs                      Description
  75  * -------------------------------------------------------------------
  76  * int32_t return               0: OK
  77  *                             -1: error
  78  */
  79 int32_t WebRtcAec_Create(void** aecInst);
  80
  81 /*
  82  * This function releases the memory allocated by WebRtcAec_Create().
  83  *
  84  * Inputs                       Description
  85  * -------------------------------------------------------------------
  86  * void*        aecInst         Pointer to the AEC instance
  87  *
  88  * Outputs                      Description
  89  * -------------------------------------------------------------------
  90  * int32_t      return          0: OK
  91  *                             -1: error
  92  */
  93 int32_t WebRtcAec_Free(void* aecInst);
  94
  95 /*
  96  * Initializes an AEC instance.
  97  *
  98  * Inputs                       Description
  99  * -------------------------------------------------------------------
 100  * void*          aecInst       Pointer to the AEC instance
 101  * int32_t        sampFreq      Sampling frequency of data
 102  * int32_t        scSampFreq    Soundcard sampling frequency
 103  *
 104  * Outputs                      Description
 105  * -------------------------------------------------------------------
 106  * int32_t        return        0: OK
 107  *                             -1: error
 108  */
 109 int32_t WebRtcAec_Init(void* aecInst, int32_t sampFreq, int32_t 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  * const float*   farend        In buffer containing one frame of
 118  *                              farend signal for L band
 119  * int16_t        nrOfSamples   Number of samples in farend buffer
 120  *
 121  * Outputs                      Description
 122  * -------------------------------------------------------------------
 123  * int32_t        return        0: OK
 124  *                             -1: error
 125  */
 126 int32_t WebRtcAec_BufferFarend(void* aecInst,
 127                                const float* farend,
 128                                int16_t 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  * float*        nearend        In buffer containing one frame of
 137  *                              nearend+echo signal for L band
 138  * float*        nearendH       In buffer containing one frame of
 139  *                              nearend+echo signal for H band
 140  * int16_t       nrOfSamples    Number of samples in nearend buffer
 141  * int16_t       msInSndCardBuf Delay estimate for sound card and
 142  *                              system buffers
 143  * int16_t       skew           Difference between number of samples played
 144  *                              and recorded at the soundcard (for clock skew
 145  *                              compensation)
 146  *
 147  * Outputs                      Description
 148  * -------------------------------------------------------------------
 149  * float*        out            Out buffer, one frame of processed nearend
 150  *                              for L band
 151  * float*        outH           Out buffer, one frame of processed nearend
 152  *                              for H band
 153  * int32_t       return         0: OK
 154  *                             -1: error
 155  */
 156 int32_t WebRtcAec_Process(void* aecInst,
 157                           const float* nearend,
 158                           const float* nearendH,
 159                           float* out,
 160                           float* outH,
 161                           int16_t nrOfSamples,
 162                           int16_t msInSndCardBuf,
 163                           int32_t skew);
 164
 165 /*
 166  * This function enables the user to set certain parameters on-the-fly.
 167  *
 168  * Inputs                       Description
 169  * -------------------------------------------------------------------
 170  * void*          handle        Pointer to the AEC instance
 171  * AecConfig      config        Config instance that contains all
 172  *                              properties to be set
 173  *
 174  * Outputs                      Description
 175  * -------------------------------------------------------------------
 176  * int            return         0: OK
 177  *                              -1: error
 178  */
 179 int WebRtcAec_set_config(void* handle, AecConfig config);
 180
 181 /*
 182  * Gets the current echo status of the nearend signal.
 183  *
 184  * Inputs                       Description
 185  * -------------------------------------------------------------------
 186  * void*          handle        Pointer to the AEC instance
 187  *
 188  * Outputs                      Description
 189  * -------------------------------------------------------------------
 190  * int*           status        0: Almost certainly nearend single-talk
 191  *                              1: Might not be neared single-talk
 192  * int            return         0: OK
 193  *                              -1: error
 194  */
 195 int WebRtcAec_get_echo_status(void* handle, int* status);
 196
 197 /*
 198  * Gets the current echo metrics for the session.
 199  *
 200  * Inputs                       Description
 201  * -------------------------------------------------------------------
 202  * void*          handle        Pointer to the AEC instance
 203  *
 204  * Outputs                      Description
 205  * -------------------------------------------------------------------
 206  * AecMetrics*    metrics       Struct which will be filled out with the
 207  *                              current echo metrics.
 208  * int            return         0: OK
 209  *                              -1: error
 210  */
 211 int WebRtcAec_GetMetrics(void* handle, AecMetrics* metrics);
 212
 213 /*
 214  * Gets the current delay metrics for the session.
 215  *
 216  * Inputs                       Description
 217  * -------------------------------------------------------------------
 218  * void*      handle            Pointer to the AEC instance
 219  *
 220  * Outputs                      Description
 221  * -------------------------------------------------------------------
 222  * int*       median            Delay median value.
 223  * int*       std               Delay standard deviation.
 224  *
 225  * int        return             0: OK
 226  *                              -1: error
 227  */
 228 int WebRtcAec_GetDelayMetrics(void* handle, int* median, int* std);
 229
 230 /*
 231  * Gets the last error code.
 232  *
 233  * Inputs                       Description
 234  * -------------------------------------------------------------------
 235  * void*          aecInst       Pointer to the AEC instance
 236  *
 237  * Outputs                      Description
 238  * -------------------------------------------------------------------
 239  * int32_t        return        11000-11100: error code
 240  */
 241 int32_t WebRtcAec_get_error_code(void* aecInst);
 242
 243 // Returns a pointer to the low level AEC handle.
 244 //
 245 // Input:
 246 //  - handle                    : Pointer to the AEC instance.
 247 //
 248 // Return value:
 249 //  - AecCore pointer           : NULL for error.
 250 //
 251 struct AecCore* WebRtcAec_aec_core(void* handle);
 252
 253 #ifdef __cplusplus
 254 }
 255 #endif
 256 #endif  // WEBRTC_MODULES_AUDIO_PROCESSING_AEC_INCLUDE_ECHO_CANCELLATION_H_