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// This sub-API supports the following functionalities:
12//
13//  - Noise Suppression (NS).
14//  - Automatic Gain Control (AGC).
15//  - Echo Control (EC).
16//  - Receiving side VAD, NS and AGC.
17//  - Measurements of instantaneous speech, noise and echo levels.
18//  - Generation of AP debug recordings.
19//  - Detection of keyboard typing which can disrupt a voice conversation.
20//
21// Usage example, omitting error checking:
22//
23//  using namespace webrtc;
24//  VoiceEngine* voe = VoiceEngine::Create();
25//  VoEBase* base = VoEBase::GetInterface();
26//  VoEAudioProcessing* ap = VoEAudioProcessing::GetInterface(voe);
27//  base->Init();
28//  ap->SetEcStatus(true, kAgcAdaptiveAnalog);
29//  ...
30//  base->Terminate();
31//  base->Release();
32//  ap->Release();
33//  VoiceEngine::Delete(voe);
34//
35#ifndef WEBRTC_VOICE_ENGINE_VOE_AUDIO_PROCESSING_H
36#define WEBRTC_VOICE_ENGINE_VOE_AUDIO_PROCESSING_H
37
38#include <stdio.h>
39
40#include "webrtc/common_types.h"
41
42namespace webrtc {
43
44class VoiceEngine;
45
46// VoERxVadCallback
47class WEBRTC_DLLEXPORT VoERxVadCallback {
48 public:
49  virtual void OnRxVad(int channel, int vadDecision) = 0;
50
51 protected:
52  virtual ~VoERxVadCallback() {}
53};
54
55// VoEAudioProcessing
56class WEBRTC_DLLEXPORT VoEAudioProcessing {
57 public:
58  // Factory for the VoEAudioProcessing sub-API. Increases an internal
59  // reference counter if successful. Returns NULL if the API is not
60  // supported or if construction fails.
61  static VoEAudioProcessing* GetInterface(VoiceEngine* voiceEngine);
62
63  // Releases the VoEAudioProcessing sub-API and decreases an internal
64  // reference counter. Returns the new reference count. This value should
65  // be zero for all sub-API:s before the VoiceEngine object can be safely
66  // deleted.
67  virtual int Release() = 0;
68
69  // Sets Noise Suppression (NS) status and mode.
70  // The NS reduces noise in the microphone signal.
71  virtual int SetNsStatus(bool enable, NsModes mode = kNsUnchanged) = 0;
72
73  // Gets the NS status and mode.
74  virtual int GetNsStatus(bool& enabled, NsModes& mode) = 0;
75
76  // Sets the Automatic Gain Control (AGC) status and mode.
77  // The AGC adjusts the microphone signal to an appropriate level.
78  virtual int SetAgcStatus(bool enable, AgcModes mode = kAgcUnchanged) = 0;
79
80  // Gets the AGC status and mode.
81  virtual int GetAgcStatus(bool& enabled, AgcModes& mode) = 0;
82
83  // Sets the AGC configuration.
84  // Should only be used in situations where the working environment
85  // is well known.
86  virtual int SetAgcConfig(AgcConfig config) = 0;
87
88  // Gets the AGC configuration.
89  virtual int GetAgcConfig(AgcConfig& config) = 0;
90
91  // Sets the Echo Control (EC) status and mode.
92  // The EC mitigates acoustic echo where a user can hear their own
93  // speech repeated back due to an acoustic coupling between the
94  // speaker and the microphone at the remote end.
95  virtual int SetEcStatus(bool enable, EcModes mode = kEcUnchanged) = 0;
96
97  // Gets the EC status and mode.
98  virtual int GetEcStatus(bool& enabled, EcModes& mode) = 0;
99
100  // Enables the compensation of clock drift between the capture and render
101  // streams by the echo canceller (i.e. only using EcMode==kEcAec). It will
102  // only be enabled if supported on the current platform; otherwise an error
103  // will be returned. Check if the platform is supported by calling
104  // |DriftCompensationSupported()|.
105  virtual int EnableDriftCompensation(bool enable) = 0;
106  virtual bool DriftCompensationEnabled() = 0;
107  static bool DriftCompensationSupported();
108
109  // Sets a delay |offset| in ms to add to the system delay reported by the
110  // OS, which is used by the AEC to synchronize far- and near-end streams.
111  // In some cases a system may introduce a delay which goes unreported by the
112  // OS, but which is known to the user. This method can be used to compensate
113  // for the unreported delay.
114  virtual void SetDelayOffsetMs(int offset) = 0;
115  virtual int DelayOffsetMs() = 0;
116
117  // Modifies settings for the AEC designed for mobile devices (AECM).
118  virtual int SetAecmMode(AecmModes mode = kAecmSpeakerphone,
119                          bool enableCNG = true) = 0;
120
121  // Gets settings for the AECM.
122  virtual int GetAecmMode(AecmModes& mode, bool& enabledCNG) = 0;
123
124  // Enables a high pass filter on the capture signal. This removes DC bias
125  // and low-frequency noise. Recommended to be enabled.
126  virtual int EnableHighPassFilter(bool enable) = 0;
127  virtual bool IsHighPassFilterEnabled() = 0;
128
129  // Sets status and mode of the receiving-side (Rx) NS.
130  // The Rx NS reduces noise in the received signal for the specified
131  // |channel|. Intended for advanced usage only.
132  virtual int SetRxNsStatus(int channel,
133                            bool enable,
134                            NsModes mode = kNsUnchanged) = 0;
135
136  // Gets status and mode of the receiving-side NS.
137  virtual int GetRxNsStatus(int channel, bool& enabled, NsModes& mode) = 0;
138
139  // Sets status and mode of the receiving-side (Rx) AGC.
140  // The Rx AGC adjusts the received signal to an appropriate level
141  // for the specified |channel|. Intended for advanced usage only.
142  virtual int SetRxAgcStatus(int channel,
143                             bool enable,
144                             AgcModes mode = kAgcUnchanged) = 0;
145
146  // Gets status and mode of the receiving-side AGC.
147  virtual int GetRxAgcStatus(int channel, bool& enabled, AgcModes& mode) = 0;
148
149  // Modifies the AGC configuration on the receiving side for the
150  // specified |channel|.
151  virtual int SetRxAgcConfig(int channel, AgcConfig config) = 0;
152
153  // Gets the AGC configuration on the receiving side.
154  virtual int GetRxAgcConfig(int channel, AgcConfig& config) = 0;
155
156  // Registers a VoERxVadCallback |observer| instance and enables Rx VAD
157  // notifications for the specified |channel|.
158  virtual int RegisterRxVadObserver(int channel,
159                                    VoERxVadCallback& observer) = 0;
160
161  // Deregisters the VoERxVadCallback |observer| and disables Rx VAD
162  // notifications for the specified |channel|.
163  virtual int DeRegisterRxVadObserver(int channel) = 0;
164
165  // Gets the VAD/DTX activity for the specified |channel|.
166  // The returned value is 1 if frames of audio contains speech
167  // and 0 if silence. The output is always 1 if VAD is disabled.
168  virtual int VoiceActivityIndicator(int channel) = 0;
169
170  // Enables or disables the possibility to retrieve echo metrics and delay
171  // logging values during an active call. The metrics are only supported in
172  // AEC.
173  virtual int SetEcMetricsStatus(bool enable) = 0;
174
175  // Gets the current EC metric status.
176  virtual int GetEcMetricsStatus(bool& enabled) = 0;
177
178  // Gets the instantaneous echo level metrics.
179  virtual int GetEchoMetrics(int& ERL, int& ERLE, int& RERL, int& A_NLP) = 0;
180
181  // Gets the EC internal |delay_median| and |delay_std| in ms between
182  // near-end and far-end. The metric |fraction_poor_delays| is the amount of
183  // delay values that potentially can break the EC. The values are aggregated
184  // over one second and the last updated metrics are returned.
185  virtual int GetEcDelayMetrics(int& delay_median,
186                                int& delay_std,
187                                float& fraction_poor_delays) = 0;
188
189  // Enables recording of Audio Processing (AP) debugging information.
190  // The file can later be used for off-line analysis of the AP performance.
191  virtual int StartDebugRecording(const char* fileNameUTF8) = 0;
192
193  // Same as above but sets and uses an existing file handle. Takes ownership
194  // of |file_handle| and passes it on to the audio processing module.
195  virtual int StartDebugRecording(FILE* file_handle) = 0;
196
197  // Disables recording of AP debugging information.
198  virtual int StopDebugRecording() = 0;
199
200  // Enables or disables detection of disturbing keyboard typing.
201  // An error notification will be given as a callback upon detection.
202  virtual int SetTypingDetectionStatus(bool enable) = 0;
203
204  // Gets the current typing detection status.
205  virtual int GetTypingDetectionStatus(bool& enabled) = 0;
206
207  // Reports the lower of:
208  // * Time in seconds since the last typing event.
209  // * Time in seconds since the typing detection was enabled.
210  // Returns error if typing detection is disabled.
211  virtual int TimeSinceLastTyping(int& seconds) = 0;
212
213  // Optional setting of typing detection parameters
214  // Parameter with value == 0 will be ignored
215  // and left with default config.
216  // TODO(niklase) Remove default argument as soon as libJingle is updated!
217  virtual int SetTypingDetectionParameters(int timeWindow,
218                                           int costPerTyping,
219                                           int reportingThreshold,
220                                           int penaltyDecay,
221                                           int typeEventDelay = 0) = 0;
222
223  // Swaps the capture-side left and right audio channels when enabled. It
224  // only has an effect when using a stereo send codec. The setting is
225  // persistent; it will be applied whenever a stereo send codec is enabled.
226  //
227  // The swap is applied only to the captured audio, and not mixed files. The
228  // swap will appear in file recordings and when accessing audio through the
229  // external media interface.
230  virtual void EnableStereoChannelSwapping(bool enable) = 0;
231  virtual bool IsStereoChannelSwappingEnabled() = 0;
232
233 protected:
234  VoEAudioProcessing() {}
235  virtual ~VoEAudioProcessing() {}
236};
237
238}  // namespace webrtc
239
240#endif  // WEBRTC_VOICE_ENGINE_VOE_AUDIO_PROCESSING_H
241