• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 
42 namespace webrtc {
43 
44 class VoiceEngine;
45 
46 // VoERxVadCallback
47 class WEBRTC_DLLEXPORT VoERxVadCallback {
48  public:
49   virtual void OnRxVad(int channel, int vadDecision) = 0;
50 
51  protected:
~VoERxVadCallback()52   virtual ~VoERxVadCallback() {}
53 };
54 
55 // VoEAudioProcessing
56 class 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:
VoEAudioProcessing()234   VoEAudioProcessing() {}
~VoEAudioProcessing()235   virtual ~VoEAudioProcessing() {}
236 };
237 
238 }  // namespace webrtc
239 
240 #endif  // WEBRTC_VOICE_ENGINE_VOE_AUDIO_PROCESSING_H
241