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 { 49 public: 50 virtual void OnRxVad(int channel, int vadDecision) = 0; 51 52 protected: ~VoERxVadCallback()53 virtual ~VoERxVadCallback() {} 54 }; 55 56 // VoEAudioProcessing 57 class WEBRTC_DLLEXPORT VoEAudioProcessing 58 { 59 public: 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 236 protected: VoEAudioProcessing()237 VoEAudioProcessing() {} ~VoEAudioProcessing()238 virtual ~VoEAudioProcessing() {} 239 }; 240 241 } // namespace webrtc 242 243 #endif // WEBRTC_VOICE_ENGINE_VOE_AUDIO_PROCESSING_H 244