1 /* 2 * Copyright (c) 2018 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 #ifndef MODULES_AUDIO_PROCESSING_AGC_GAIN_CONTROL_H_ 12 #define MODULES_AUDIO_PROCESSING_AGC_GAIN_CONTROL_H_ 13 14 namespace webrtc { 15 16 // The automatic gain control (AGC) component brings the signal to an 17 // appropriate range. This is done by applying a digital gain directly and, in 18 // the analog mode, prescribing an analog gain to be applied at the audio HAL. 19 // 20 // Recommended to be enabled on the client-side. 21 class GainControl { 22 public: 23 // When an analog mode is set, this must be called prior to `ProcessStream()` 24 // to pass the current analog level from the audio HAL. Must be within the 25 // range provided to `set_analog_level_limits()`. 26 virtual int set_stream_analog_level(int level) = 0; 27 28 // When an analog mode is set, this should be called after `ProcessStream()` 29 // to obtain the recommended new analog level for the audio HAL. It is the 30 // users responsibility to apply this level. 31 virtual int stream_analog_level() const = 0; 32 33 enum Mode { 34 // Adaptive mode intended for use if an analog volume control is available 35 // on the capture device. It will require the user to provide coupling 36 // between the OS mixer controls and AGC through the `stream_analog_level()` 37 // functions. 38 // 39 // It consists of an analog gain prescription for the audio device and a 40 // digital compression stage. 41 kAdaptiveAnalog, 42 43 // Adaptive mode intended for situations in which an analog volume control 44 // is unavailable. It operates in a similar fashion to the adaptive analog 45 // mode, but with scaling instead applied in the digital domain. As with 46 // the analog mode, it additionally uses a digital compression stage. 47 kAdaptiveDigital, 48 49 // Fixed mode which enables only the digital compression stage also used by 50 // the two adaptive modes. 51 // 52 // It is distinguished from the adaptive modes by considering only a 53 // short time-window of the input signal. It applies a fixed gain through 54 // most of the input level range, and compresses (gradually reduces gain 55 // with increasing level) the input signal at higher levels. This mode is 56 // preferred on embedded devices where the capture signal level is 57 // predictable, so that a known gain can be applied. 58 kFixedDigital 59 }; 60 61 virtual int set_mode(Mode mode) = 0; 62 virtual Mode mode() const = 0; 63 64 // Sets the target peak `level` (or envelope) of the AGC in dBFs (decibels 65 // from digital full-scale). The convention is to use positive values. For 66 // instance, passing in a value of 3 corresponds to -3 dBFs, or a target 67 // level 3 dB below full-scale. Limited to [0, 31]. 68 // 69 // TODO(ajm): use a negative value here instead, if/when VoE will similarly 70 // update its interface. 71 virtual int set_target_level_dbfs(int level) = 0; 72 virtual int target_level_dbfs() const = 0; 73 74 // Sets the maximum `gain` the digital compression stage may apply, in dB. A 75 // higher number corresponds to greater compression, while a value of 0 will 76 // leave the signal uncompressed. Limited to [0, 90]. 77 virtual int set_compression_gain_db(int gain) = 0; 78 virtual int compression_gain_db() const = 0; 79 80 // When enabled, the compression stage will hard limit the signal to the 81 // target level. Otherwise, the signal will be compressed but not limited 82 // above the target level. 83 virtual int enable_limiter(bool enable) = 0; 84 virtual bool is_limiter_enabled() const = 0; 85 86 // Sets the `minimum` and `maximum` analog levels of the audio capture device. 87 // Must be set if and only if an analog mode is used. Limited to [0, 65535]. 88 virtual int set_analog_level_limits(int minimum, int maximum) = 0; 89 virtual int analog_level_minimum() const = 0; 90 virtual int analog_level_maximum() const = 0; 91 92 // Returns true if the AGC has detected a saturation event (period where the 93 // signal reaches digital full-scale) in the current frame and the analog 94 // level cannot be reduced. 95 // 96 // This could be used as an indicator to reduce or disable analog mic gain at 97 // the audio HAL. 98 virtual bool stream_is_saturated() const = 0; 99 100 protected: ~GainControl()101 virtual ~GainControl() {} 102 }; 103 } // namespace webrtc 104 105 #endif // MODULES_AUDIO_PROCESSING_AGC_GAIN_CONTROL_H_ 106