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