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