1 /* 2 * Copyright (c) 2013 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_AGC_MANAGER_DIRECT_H_ 12 #define MODULES_AUDIO_PROCESSING_AGC_AGC_MANAGER_DIRECT_H_ 13 14 #include <atomic> 15 #include <memory> 16 17 #include "absl/types/optional.h" 18 #include "api/array_view.h" 19 #include "modules/audio_processing/agc/agc.h" 20 #include "modules/audio_processing/agc2/clipping_predictor.h" 21 #include "modules/audio_processing/audio_buffer.h" 22 #include "modules/audio_processing/include/audio_processing.h" 23 #include "modules/audio_processing/logging/apm_data_dumper.h" 24 #include "rtc_base/gtest_prod_util.h" 25 26 namespace webrtc { 27 28 class MonoAgc; 29 class GainControl; 30 31 // Adaptive Gain Controller (AGC) that controls the input volume and a digital 32 // gain. The input volume controller recommends what volume to use, handles 33 // volume changes and clipping. In particular, it handles changes triggered by 34 // the user (e.g., volume set to zero by a HW mute button). The digital 35 // controller chooses and applies the digital compression gain. 36 // This class is not thread-safe. 37 // TODO(bugs.webrtc.org/7494): Use applied/recommended input volume naming 38 // convention. 39 class AgcManagerDirect final { 40 public: 41 // Ctor. `num_capture_channels` specifies the number of channels for the audio 42 // passed to `AnalyzePreProcess()` and `Process()`. Clamps 43 // `analog_config.startup_min_level` in the [12, 255] range. 44 AgcManagerDirect( 45 int num_capture_channels, 46 const AudioProcessing::Config::GainController1::AnalogGainController& 47 analog_config); 48 49 ~AgcManagerDirect(); 50 AgcManagerDirect(const AgcManagerDirect&) = delete; 51 AgcManagerDirect& operator=(const AgcManagerDirect&) = delete; 52 53 void Initialize(); 54 55 // Configures `gain_control` to work as a fixed digital controller so that the 56 // adaptive part is only handled by this gain controller. Must be called if 57 // `gain_control` is also used to avoid the side-effects of running two AGCs. 58 void SetupDigitalGainControl(GainControl& gain_control) const; 59 60 // Sets the applied input volume. 61 void set_stream_analog_level(int level); 62 63 // TODO(bugs.webrtc.org/7494): Add argument for the applied input volume and 64 // remove `set_stream_analog_level()`. 65 // Analyzes `audio` before `Process()` is called so that the analysis can be 66 // performed before external digital processing operations take place (e.g., 67 // echo cancellation). The analysis consists of input clipping detection and 68 // prediction (if enabled). Must be called after `set_stream_analog_level()`. 69 void AnalyzePreProcess(const AudioBuffer& audio_buffer); 70 71 // Processes `audio_buffer`. Chooses a digital compression gain and the new 72 // input volume to recommend. Must be called after `AnalyzePreProcess()`. If 73 // `speech_probability` (range [0.0f, 1.0f]) and `speech_level_dbfs` (range 74 // [-90.f, 30.0f]) are given, uses them to override the estimated RMS error. 75 // TODO(webrtc:7494): This signature is needed for testing purposes, unify 76 // the signatures when the clean-up is done. 77 void Process(const AudioBuffer& audio_buffer, 78 absl::optional<float> speech_probability, 79 absl::optional<float> speech_level_dbfs); 80 81 // Processes `audio_buffer`. Chooses a digital compression gain and the new 82 // input volume to recommend. Must be called after `AnalyzePreProcess()`. 83 void Process(const AudioBuffer& audio_buffer); 84 85 // TODO(bugs.webrtc.org/7494): Return recommended input volume and remove 86 // `recommended_analog_level()`. 87 // Returns the recommended input volume. If the input volume contoller is 88 // disabled, returns the input volume set via the latest 89 // `set_stream_analog_level()` call. Must be called after 90 // `AnalyzePreProcess()` and `Process()`. recommended_analog_level()91 int recommended_analog_level() const { return recommended_input_volume_; } 92 93 // Call when the capture stream output has been flagged to be used/not-used. 94 // If unused, the manager disregards all incoming audio. 95 void HandleCaptureOutputUsedChange(bool capture_output_used); 96 97 float voice_probability() const; 98 num_channels()99 int num_channels() const { return num_capture_channels_; } 100 101 // If available, returns the latest digital compression gain that has been 102 // chosen. 103 absl::optional<int> GetDigitalComressionGain(); 104 105 // Returns true if clipping prediction is enabled. clipping_predictor_enabled()106 bool clipping_predictor_enabled() const { return !!clipping_predictor_; } 107 108 // Returns true if clipping prediction is used to adjust the input volume. use_clipping_predictor_step()109 bool use_clipping_predictor_step() const { 110 return use_clipping_predictor_step_; 111 } 112 113 private: 114 friend class AgcManagerDirectTestHelper; 115 116 FRIEND_TEST_ALL_PREFIXES(AgcManagerDirectTest, DisableDigitalDisablesDigital); 117 FRIEND_TEST_ALL_PREFIXES(AgcManagerDirectTest, 118 AgcMinMicLevelExperimentDefault); 119 FRIEND_TEST_ALL_PREFIXES(AgcManagerDirectTest, 120 AgcMinMicLevelExperimentDisabled); 121 FRIEND_TEST_ALL_PREFIXES(AgcManagerDirectTest, 122 AgcMinMicLevelExperimentOutOfRangeAbove); 123 FRIEND_TEST_ALL_PREFIXES(AgcManagerDirectTest, 124 AgcMinMicLevelExperimentOutOfRangeBelow); 125 FRIEND_TEST_ALL_PREFIXES(AgcManagerDirectTest, 126 AgcMinMicLevelExperimentEnabled50); 127 FRIEND_TEST_ALL_PREFIXES(AgcManagerDirectTest, 128 AgcMinMicLevelExperimentEnabledAboveStartupLevel); 129 FRIEND_TEST_ALL_PREFIXES(AgcManagerDirectParametrizedTest, 130 ClippingParametersVerified); 131 FRIEND_TEST_ALL_PREFIXES(AgcManagerDirectParametrizedTest, 132 DisableClippingPredictorDoesNotLowerVolume); 133 FRIEND_TEST_ALL_PREFIXES(AgcManagerDirectParametrizedTest, 134 UsedClippingPredictionsProduceLowerAnalogLevels); 135 FRIEND_TEST_ALL_PREFIXES(AgcManagerDirectParametrizedTest, 136 UnusedClippingPredictionsProduceEqualAnalogLevels); 137 FRIEND_TEST_ALL_PREFIXES(AgcManagerDirectParametrizedTest, 138 EmptyRmsErrorOverrideHasNoEffect); 139 FRIEND_TEST_ALL_PREFIXES(AgcManagerDirectParametrizedTest, 140 NonEmptyRmsErrorOverrideHasEffect); 141 142 // Ctor that creates a single channel AGC and by injecting `agc`. 143 // `agc` will be owned by this class; hence, do not delete it. 144 AgcManagerDirect( 145 const AudioProcessing::Config::GainController1::AnalogGainController& 146 analog_config, 147 Agc* agc); 148 149 void AggregateChannelLevels(); 150 151 const bool analog_controller_enabled_; 152 153 const absl::optional<int> min_mic_level_override_; 154 std::unique_ptr<ApmDataDumper> data_dumper_; 155 static std::atomic<int> instance_counter_; 156 const int num_capture_channels_; 157 const bool disable_digital_adaptive_; 158 159 int frames_since_clipped_; 160 161 // TODO(bugs.webrtc.org/7494): Create a separate member for the applied input 162 // volume. 163 // TODO(bugs.webrtc.org/7494): Once 164 // `AudioProcessingImpl::recommended_stream_analog_level()` becomes a trivial 165 // getter, leave uninitialized. 166 // Recommended input volume. After `set_stream_analog_level()` is called it 167 // holds the observed input volume. Possibly updated by `AnalyzePreProcess()` 168 // and `Process()`; after these calls, holds the recommended input volume. 169 int recommended_input_volume_ = 0; 170 171 bool capture_output_used_; 172 int channel_controlling_gain_ = 0; 173 174 const int clipped_level_step_; 175 const float clipped_ratio_threshold_; 176 const int clipped_wait_frames_; 177 178 std::vector<std::unique_ptr<MonoAgc>> channel_agcs_; 179 std::vector<absl::optional<int>> new_compressions_to_set_; 180 181 const std::unique_ptr<ClippingPredictor> clipping_predictor_; 182 const bool use_clipping_predictor_step_; 183 float clipping_rate_log_; 184 int clipping_rate_log_counter_; 185 }; 186 187 // TODO(bugs.webrtc.org/7494): Use applied/recommended input volume naming 188 // convention. 189 class MonoAgc { 190 public: 191 MonoAgc(ApmDataDumper* data_dumper, 192 int clipped_level_min, 193 bool disable_digital_adaptive, 194 int min_mic_level); 195 ~MonoAgc(); 196 MonoAgc(const MonoAgc&) = delete; 197 MonoAgc& operator=(const MonoAgc&) = delete; 198 199 void Initialize(); 200 void HandleCaptureOutputUsedChange(bool capture_output_used); 201 202 // Sets the current input volume. set_stream_analog_level(int level)203 void set_stream_analog_level(int level) { recommended_input_volume_ = level; } 204 205 // Lowers the recommended input volume in response to clipping based on the 206 // suggested reduction `clipped_level_step`. Must be called after 207 // `set_stream_analog_level()`. 208 void HandleClipping(int clipped_level_step); 209 210 // Analyzes `audio`, requests the RMS error from AGC, updates the recommended 211 // input volume based on the estimated speech level and, if enabled, updates 212 // the (digital) compression gain to be applied by `agc_`. Must be called 213 // after `HandleClipping()`. If `rms_error_override` has a value, RMS error 214 // from AGC is overridden by it. 215 void Process(rtc::ArrayView<const int16_t> audio, 216 absl::optional<int> rms_error_override); 217 218 // Returns the recommended input volume. Must be called after `Process()`. recommended_analog_level()219 int recommended_analog_level() const { return recommended_input_volume_; } 220 voice_probability()221 float voice_probability() const { return agc_->voice_probability(); } ActivateLogging()222 void ActivateLogging() { log_to_histograms_ = true; } new_compression()223 absl::optional<int> new_compression() const { 224 return new_compression_to_set_; 225 } 226 227 // Only used for testing. set_agc(Agc * agc)228 void set_agc(Agc* agc) { agc_.reset(agc); } min_mic_level()229 int min_mic_level() const { return min_mic_level_; } 230 231 private: 232 // Sets a new input volume, after first checking that it hasn't been updated 233 // by the user, in which case no action is taken. 234 void SetLevel(int new_level); 235 236 // Set the maximum input volume the AGC is allowed to apply. Also updates the 237 // maximum compression gain to compensate. The volume must be at least 238 // `kClippedLevelMin`. 239 void SetMaxLevel(int level); 240 241 int CheckVolumeAndReset(); 242 void UpdateGain(int rms_error_db); 243 void UpdateCompressor(); 244 245 const int min_mic_level_; 246 const bool disable_digital_adaptive_; 247 std::unique_ptr<Agc> agc_; 248 int level_ = 0; 249 int max_level_; 250 int max_compression_gain_; 251 int target_compression_; 252 int compression_; 253 float compression_accumulator_; 254 bool capture_output_used_ = true; 255 bool check_volume_on_next_process_ = true; 256 bool startup_ = true; 257 258 // TODO(bugs.webrtc.org/7494): Create a separate member for the applied 259 // input volume. 260 // Recommended input volume. After `set_stream_analog_level()` is 261 // called, it holds the observed applied input volume. Possibly updated by 262 // `HandleClipping()` and `Process()`; after these calls, holds the 263 // recommended input volume. 264 int recommended_input_volume_ = 0; 265 266 absl::optional<int> new_compression_to_set_; 267 bool log_to_histograms_ = false; 268 const int clipped_level_min_; 269 270 // Frames since the last `UpdateGain()` call. 271 int frames_since_update_gain_ = 0; 272 // Set to true for the first frame after startup and reset, otherwise false. 273 bool is_first_frame_ = true; 274 }; 275 276 } // namespace webrtc 277 278 #endif // MODULES_AUDIO_PROCESSING_AGC_AGC_MANAGER_DIRECT_H_ 279