1/*
2 *  Copyright (c) 2011 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_AECM_MAIN_INTERFACE_ECHO_CONTROL_MOBILE_H_
12#define WEBRTC_MODULES_AUDIO_PROCESSING_AECM_MAIN_INTERFACE_ECHO_CONTROL_MOBILE_H_
13
14#include "typedefs.h"
15
16enum {
17    AecmFalse = 0,
18    AecmTrue
19};
20
21// Errors
22#define AECM_UNSPECIFIED_ERROR           12000
23#define AECM_UNSUPPORTED_FUNCTION_ERROR  12001
24#define AECM_UNINITIALIZED_ERROR         12002
25#define AECM_NULL_POINTER_ERROR          12003
26#define AECM_BAD_PARAMETER_ERROR         12004
27
28// Warnings
29#define AECM_BAD_PARAMETER_WARNING       12100
30
31typedef struct {
32    WebRtc_Word16 cngMode;            // AECM_FALSE, AECM_TRUE (default)
33    WebRtc_Word16 echoMode;           // 0, 1, 2, 3 (default), 4
34} AecmConfig;
35
36#ifdef __cplusplus
37extern "C" {
38#endif
39
40/*
41 * Allocates the memory needed by the AECM. The memory needs to be
42 * initialized separately using the WebRtcAecm_Init() function.
43 *
44 * Inputs                           Description
45 * -------------------------------------------------------------------
46 * void **aecmInst                  Pointer to the AECM instance to be
47 *                                  created and initialized
48 *
49 * Outputs                          Description
50 * -------------------------------------------------------------------
51 * WebRtc_Word32 return             0: OK
52 *                                 -1: error
53 */
54WebRtc_Word32 WebRtcAecm_Create(void **aecmInst);
55
56/*
57 * This function releases the memory allocated by WebRtcAecm_Create()
58 *
59 * Inputs                       Description
60 * -------------------------------------------------------------------
61 * void *aecmInst               Pointer to the AECM instance
62 *
63 * Outputs                      Description
64 * -------------------------------------------------------------------
65 * WebRtc_Word32  return        0: OK
66 *                             -1: error
67 */
68WebRtc_Word32 WebRtcAecm_Free(void *aecmInst);
69
70/*
71 * Initializes an AECM instance.
72 *
73 * Inputs                       Description
74 * -------------------------------------------------------------------
75 * void           *aecmInst     Pointer to the AECM instance
76 * WebRtc_Word32  sampFreq      Sampling frequency of data
77 *
78 * Outputs                      Description
79 * -------------------------------------------------------------------
80 * WebRtc_Word32  return        0: OK
81 *                             -1: error
82 */
83WebRtc_Word32 WebRtcAecm_Init(void* aecmInst,
84                              WebRtc_Word32 sampFreq);
85
86/*
87 * Inserts an 80 or 160 sample block of data into the farend buffer.
88 *
89 * Inputs                       Description
90 * -------------------------------------------------------------------
91 * void           *aecmInst     Pointer to the AECM instance
92 * WebRtc_Word16  *farend       In buffer containing one frame of
93 *                              farend signal
94 * WebRtc_Word16  nrOfSamples   Number of samples in farend buffer
95 *
96 * Outputs                      Description
97 * -------------------------------------------------------------------
98 * WebRtc_Word32  return        0: OK
99 *                             -1: error
100 */
101WebRtc_Word32 WebRtcAecm_BufferFarend(void* aecmInst,
102                                      const WebRtc_Word16* farend,
103                                      WebRtc_Word16 nrOfSamples);
104
105/*
106 * Runs the AECM on an 80 or 160 sample blocks of data.
107 *
108 * Inputs                       Description
109 * -------------------------------------------------------------------
110 * void           *aecmInst      Pointer to the AECM instance
111 * WebRtc_Word16  *nearendNoisy  In buffer containing one frame of
112 *                               reference nearend+echo signal. If
113 *                               noise reduction is active, provide
114 *                               the noisy signal here.
115 * WebRtc_Word16  *nearendClean  In buffer containing one frame of
116 *                               nearend+echo signal. If noise
117 *                               reduction is active, provide the
118 *                               clean signal here. Otherwise pass a
119 *                               NULL pointer.
120 * WebRtc_Word16  nrOfSamples    Number of samples in nearend buffer
121 * WebRtc_Word16  msInSndCardBuf Delay estimate for sound card and
122 *                               system buffers
123 *
124 * Outputs                      Description
125 * -------------------------------------------------------------------
126 * WebRtc_Word16  *out          Out buffer, one frame of processed nearend
127 * WebRtc_Word32  return        0: OK
128 *                             -1: error
129 */
130WebRtc_Word32 WebRtcAecm_Process(void* aecmInst,
131                                 const WebRtc_Word16* nearendNoisy,
132                                 const WebRtc_Word16* nearendClean,
133                                 WebRtc_Word16* out,
134                                 WebRtc_Word16 nrOfSamples,
135                                 WebRtc_Word16 msInSndCardBuf);
136
137/*
138 * This function enables the user to set certain parameters on-the-fly
139 *
140 * Inputs                       Description
141 * -------------------------------------------------------------------
142 * void     *aecmInst           Pointer to the AECM instance
143 * AecmConfig config            Config instance that contains all
144 *                              properties to be set
145 *
146 * Outputs                      Description
147 * -------------------------------------------------------------------
148 * WebRtc_Word32  return        0: OK
149 *                             -1: error
150 */
151WebRtc_Word32 WebRtcAecm_set_config(void* aecmInst,
152                                    AecmConfig config);
153
154/*
155 * This function enables the user to set certain parameters on-the-fly
156 *
157 * Inputs                       Description
158 * -------------------------------------------------------------------
159 * void *aecmInst               Pointer to the AECM instance
160 *
161 * Outputs                      Description
162 * -------------------------------------------------------------------
163 * AecmConfig  *config          Pointer to the config instance that
164 *                              all properties will be written to
165 * WebRtc_Word32  return        0: OK
166 *                             -1: error
167 */
168WebRtc_Word32 WebRtcAecm_get_config(void *aecmInst,
169                                    AecmConfig *config);
170
171/*
172 * This function enables the user to set the echo path on-the-fly.
173 *
174 * Inputs                       Description
175 * -------------------------------------------------------------------
176 * void*        aecmInst        Pointer to the AECM instance
177 * void*        echo_path       Pointer to the echo path to be set
178 * size_t       size_bytes      Size in bytes of the echo path
179 *
180 * Outputs                      Description
181 * -------------------------------------------------------------------
182 * WebRtc_Word32  return        0: OK
183 *                             -1: error
184 */
185WebRtc_Word32 WebRtcAecm_InitEchoPath(void* aecmInst,
186                                      const void* echo_path,
187                                      size_t size_bytes);
188
189/*
190 * This function enables the user to get the currently used echo path
191 * on-the-fly
192 *
193 * Inputs                       Description
194 * -------------------------------------------------------------------
195 * void*        aecmInst        Pointer to the AECM instance
196 * void*        echo_path       Pointer to echo path
197 * size_t       size_bytes      Size in bytes of the echo path
198 *
199 * Outputs                      Description
200 * -------------------------------------------------------------------
201 * WebRtc_Word32  return        0: OK
202 *                             -1: error
203 */
204WebRtc_Word32 WebRtcAecm_GetEchoPath(void* aecmInst,
205                                     void* echo_path,
206                                     size_t size_bytes);
207
208/*
209 * This function enables the user to get the echo path size in bytes
210 *
211 * Outputs                      Description
212 * -------------------------------------------------------------------
213 * size_t       return           : size in bytes
214 */
215size_t WebRtcAecm_echo_path_size_bytes();
216
217/*
218 * Gets the last error code.
219 *
220 * Inputs                       Description
221 * -------------------------------------------------------------------
222 * void         *aecmInst       Pointer to the AECM instance
223 *
224 * Outputs                      Description
225 * -------------------------------------------------------------------
226 * WebRtc_Word32  return        11000-11100: error code
227 */
228WebRtc_Word32 WebRtcAecm_get_error_code(void *aecmInst);
229
230/*
231 * Gets a version string
232 *
233 * Inputs                       Description
234 * -------------------------------------------------------------------
235 * char           *versionStr   Pointer to a string array
236 * WebRtc_Word16  len           The maximum length of the string
237 *
238 * Outputs                      Description
239 * -------------------------------------------------------------------
240 * WebRtc_Word8   *versionStr   Pointer to a string array
241 * WebRtc_Word32  return        0: OK
242 *                             -1: error
243 */
244WebRtc_Word32 WebRtcAecm_get_version(WebRtc_Word8 *versionStr,
245                                     WebRtc_Word16 len);
246
247#ifdef __cplusplus
248}
249#endif
250#endif /* WEBRTC_MODULES_AUDIO_PROCESSING_AECM_MAIN_INTERFACE_ECHO_CONTROL_MOBILE_H_ */
251