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