andrew@webrtc.org | b015cbe | 2012-10-22 18:19:23 +0000 | [diff] [blame] | 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 | |
pbos@webrtc.org | 471ae72 | 2013-05-21 13:52:32 +0000 | [diff] [blame^] | 38 | #include "webrtc/common_types.h" |
andrew@webrtc.org | b015cbe | 2012-10-22 18:19:23 +0000 | [diff] [blame] | 39 | |
| 40 | namespace webrtc { |
| 41 | |
| 42 | class VoiceEngine; |
| 43 | |
| 44 | // VoERxVadCallback |
| 45 | class WEBRTC_DLLEXPORT VoERxVadCallback |
| 46 | { |
| 47 | public: |
| 48 | virtual void OnRxVad(int channel, int vadDecision) = 0; |
| 49 | |
| 50 | protected: |
| 51 | virtual ~VoERxVadCallback() {} |
| 52 | }; |
| 53 | |
| 54 | // VoEAudioProcessing |
| 55 | class WEBRTC_DLLEXPORT VoEAudioProcessing |
| 56 | { |
| 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. |
pbos@webrtc.org | ca7a9a2 | 2013-05-14 08:31:39 +0000 | [diff] [blame] | 86 | virtual int SetAgcConfig(AgcConfig config) = 0; |
andrew@webrtc.org | b015cbe | 2012-10-22 18:19:23 +0000 | [diff] [blame] | 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, |
| 138 | bool& enabled, |
| 139 | NsModes& mode) = 0; |
| 140 | |
| 141 | // Sets status and mode of the receiving-side (Rx) AGC. |
| 142 | // The Rx AGC adjusts the received signal to an appropriate level |
| 143 | // for the specified |channel|. Intended for advanced usage only. |
| 144 | virtual int SetRxAgcStatus(int channel, |
| 145 | bool enable, |
| 146 | AgcModes mode = kAgcUnchanged) = 0; |
| 147 | |
| 148 | // Gets status and mode of the receiving-side AGC. |
| 149 | virtual int GetRxAgcStatus(int channel, |
| 150 | bool& enabled, |
| 151 | AgcModes& mode) = 0; |
| 152 | |
| 153 | // Modifies the AGC configuration on the receiving side for the |
| 154 | // specified |channel|. |
pbos@webrtc.org | ca7a9a2 | 2013-05-14 08:31:39 +0000 | [diff] [blame] | 155 | virtual int SetRxAgcConfig(int channel, AgcConfig config) = 0; |
andrew@webrtc.org | b015cbe | 2012-10-22 18:19:23 +0000 | [diff] [blame] | 156 | |
| 157 | // Gets the AGC configuration on the receiving side. |
| 158 | virtual int GetRxAgcConfig(int channel, AgcConfig& config) = 0; |
| 159 | |
| 160 | // Registers a VoERxVadCallback |observer| instance and enables Rx VAD |
| 161 | // notifications for the specified |channel|. |
| 162 | virtual int RegisterRxVadObserver(int channel, |
| 163 | VoERxVadCallback &observer) = 0; |
| 164 | |
| 165 | // Deregisters the VoERxVadCallback |observer| and disables Rx VAD |
| 166 | // notifications for the specified |channel|. |
| 167 | virtual int DeRegisterRxVadObserver(int channel) = 0; |
| 168 | |
| 169 | // Gets the VAD/DTX activity for the specified |channel|. |
| 170 | // The returned value is 1 if frames of audio contains speech |
| 171 | // and 0 if silence. The output is always 1 if VAD is disabled. |
| 172 | virtual int VoiceActivityIndicator(int channel) = 0; |
| 173 | |
| 174 | // Enables or disables the possibility to retrieve echo metrics and delay |
| 175 | // logging values during an active call. The metrics are only supported in |
| 176 | // AEC. |
| 177 | virtual int SetEcMetricsStatus(bool enable) = 0; |
| 178 | |
| 179 | // Gets the current EC metric status. |
| 180 | virtual int GetEcMetricsStatus(bool& enabled) = 0; |
| 181 | |
| 182 | // Gets the instantaneous echo level metrics. |
| 183 | virtual int GetEchoMetrics(int& ERL, int& ERLE, int& RERL, int& A_NLP) = 0; |
| 184 | |
| 185 | // Gets the EC internal |delay_median| and |delay_std| in ms between |
| 186 | // near-end and far-end. The values are calculated over the time period |
| 187 | // since the last GetEcDelayMetrics() call. |
| 188 | virtual int GetEcDelayMetrics(int& delay_median, int& delay_std) = 0; |
| 189 | |
| 190 | // Enables recording of Audio Processing (AP) debugging information. |
| 191 | // The file can later be used for off-line analysis of the AP performance. |
| 192 | virtual int StartDebugRecording(const char* fileNameUTF8) = 0; |
| 193 | |
| 194 | // Disables recording of AP debugging information. |
| 195 | virtual int StopDebugRecording() = 0; |
| 196 | |
| 197 | // Enables or disables detection of disturbing keyboard typing. |
| 198 | // An error notification will be given as a callback upon detection. |
| 199 | virtual int SetTypingDetectionStatus(bool enable) = 0; |
| 200 | |
| 201 | // Gets the current typing detection status. |
| 202 | virtual int GetTypingDetectionStatus(bool& enabled) = 0; |
| 203 | |
| 204 | // Reports the lower of: |
| 205 | // * Time in seconds since the last typing event. |
| 206 | // * Time in seconds since the typing detection was enabled. |
| 207 | // Returns error if typing detection is disabled. |
| 208 | virtual int TimeSinceLastTyping(int &seconds) = 0; |
| 209 | |
| 210 | // Optional setting of typing detection parameters |
| 211 | // Parameter with value == 0 will be ignored |
| 212 | // and left with default config. |
| 213 | // TODO(niklase) Remove default argument as soon as libJingle is updated! |
| 214 | virtual int SetTypingDetectionParameters(int timeWindow, |
| 215 | int costPerTyping, |
| 216 | int reportingThreshold, |
| 217 | int penaltyDecay, |
| 218 | int typeEventDelay = 0) = 0; |
| 219 | |
| 220 | // Swaps the capture-side left and right audio channels when enabled. It |
| 221 | // only has an effect when using a stereo send codec. The setting is |
| 222 | // persistent; it will be applied whenever a stereo send codec is enabled. |
| 223 | // |
| 224 | // The swap is applied only to the captured audio, and not mixed files. The |
| 225 | // swap will appear in file recordings and when accessing audio through the |
| 226 | // external media interface. |
| 227 | virtual void EnableStereoChannelSwapping(bool enable) = 0; |
| 228 | virtual bool IsStereoChannelSwappingEnabled() = 0; |
| 229 | |
| 230 | protected: |
| 231 | VoEAudioProcessing() {} |
| 232 | virtual ~VoEAudioProcessing() {} |
| 233 | }; |
| 234 | |
| 235 | } // namespace webrtc |
| 236 | |
| 237 | #endif // WEBRTC_VOICE_ENGINE_VOE_AUDIO_PROCESSING_H |