AGC2: move fixed digital controller before limiter

Currently the fixed digital gain is applied after the input volume
controller and before the adaptive digital one. This CL moves its
application after the adaptive digital controller and before the
limiter.

Reasons:
- This change is safe: no production config where both adaptive and
  fixed digital controllers are jointly used
- More predictable behavior: when the fixed digital controller is
  used after the adaptive digital controller it is easier to describe
  the overall behavior - i.e., the fixed digital combined with the
  limiter can be used for digital compression
- Allow to remove an unwanted temporal dependency: in a follow-up CL
  the input volume controller will use the latest speech level
  estimation instead of that from the previously analyzed frame; this
  CL makes that change easier.

Bug: webrtc:7494
Change-Id: I2e9869081e0eba1e4f30f11ea93a973ca7fea28c
Reviewed-on: https://webrtc-review.googlesource.com/c/src/+/286340
Reviewed-by: Hanna Silen <silen@webrtc.org>
Commit-Queue: Alessio Bazzica <alessiob@webrtc.org>
Cr-Commit-Position: refs/heads/main@{#38813}

2 files changed, 36 insertions, 18 deletions

diff --git a/modules/audio_processing/gain_controller2.cc b/modules/audio_processing/gain_controller2.cc
index 2a9c8620b7..174647c956 100644
--- a/modules/audio_processing/gain_controller2.cc
+++ b/modules/audio_processing/gain_controller2.cc
@@ -187,12 +187,14 @@ void GainController2::Process(absl::optional<float> speech_probability,
     }
   }
 
-  fixed_gain_applier_.ApplyGain(float_frame);
   if (adaptive_digital_controller_) {
     RTC_DCHECK(speech_probability.has_value());
     adaptive_digital_controller_->Process(
         float_frame, speech_probability.value(), limiter_.LastAudioLevel());
   }
+
+  fixed_gain_applier_.ApplyGain(float_frame);
+
   limiter_.Process(float_frame);
 
   // Periodically log limiter stats.
diff --git a/modules/audio_processing/include/audio_processing.h b/modules/audio_processing/include/audio_processing.h
index 9935167750..c5c6070e6b 100644
--- a/modules/audio_processing/include/audio_processing.h
+++ b/modules/audio_processing/include/audio_processing.h
@@ -328,22 +328,35 @@ class RTC_EXPORT AudioProcessing : public rtc::RefCountInterface {
       } analog_gain_controller;
     } gain_controller1;
 
-    // Enables the next generation AGC functionality. This feature replaces the
-    // standard methods of gain control in the previous AGC. Enabling this
-    // submodule enables an adaptive digital AGC followed by a limiter. By
-    // setting `fixed_gain_db`, the limiter can be turned into a compressor that
-    // first applies a fixed gain. The adaptive digital AGC can be turned off by
-    // setting |adaptive_digital_mode=false|.
+    // Parameters for AGC2, an Automatic Gain Control (AGC) sub-module which
+    // replaces the AGC sub-module parametrized by `gain_controller1`.
+    // AGC2 brings the captured audio signal to the desired level by combining
+    // three different controllers (namely, input volume controller, adapative
+    // digital controller and fixed digital controller) and a limiter.
+    // TODO(bugs.webrtc.org:7494): Name `GainController` when AGC1 removed.
     struct RTC_EXPORT GainController2 {
       bool operator==(const GainController2& rhs) const;
       bool operator!=(const GainController2& rhs) const {
         return !(*this == rhs);
       }
 
+      // AGC2 must be created if and only if `enabled` is true.
       bool enabled = false;
-      struct FixedDigital {
-        float gain_db = 0.0f;
-      } fixed_digital;
+
+      // Parameters for the input volume controller, which adjusts the input
+      // volume applied when the audio is captured (e.g., microphone volume on
+      // a soundcard, input volume on HAL).
+      struct InputVolumeController {
+        bool operator==(const InputVolumeController& rhs) const;
+        bool operator!=(const InputVolumeController& rhs) const {
+          return !(*this == rhs);
+        }
+        bool enabled = false;
+      } input_volume_controller;
+
+      // Parameters for the adaptive digital controller, which adjusts and
+      // applies a digital gain after echo cancellation and after noise
+      // suppression.
       struct RTC_EXPORT AdaptiveDigital {
         bool operator==(const AdaptiveDigital& rhs) const;
         bool operator!=(const AdaptiveDigital& rhs) const {
@@ -351,6 +364,7 @@ class RTC_EXPORT AudioProcessing : public rtc::RefCountInterface {
         }
 
         bool enabled = false;
+        // TODO(bugs.webrtc.org/7494): Remove `dry_run`.
         // When true, the adaptive digital controller runs but the signal is not
         // modified.
         bool dry_run = false;
@@ -359,20 +373,22 @@ class RTC_EXPORT AudioProcessing : public rtc::RefCountInterface {
         // `max_output_noise_level_dbfs`.
         float max_gain_db = 30.0f;
         float initial_gain_db = 8.0f;
+        // TODO(bugs.webrtc.org/7494): Hard-code and remove parameter below.
         int vad_reset_period_ms = 1500;
+        // TODO(bugs.webrtc.org/7494): Hard-code and remove parameter below.
         int adjacent_speech_frames_threshold = 12;
         float max_gain_change_db_per_second = 3.0f;
         float max_output_noise_level_dbfs = -50.0f;
       } adaptive_digital;
 
-      // Enables input volume control in AGC2.
-      struct InputVolumeController {
-        bool operator==(const InputVolumeController& rhs) const;
-        bool operator!=(const InputVolumeController& rhs) const {
-          return !(*this == rhs);
-        }
-        bool enabled = false;
-      } input_volume_controller;
+      // Parameters for the fixed digital controller, which applies a fixed
+      // digital gain after the adaptive digital controller and before the
+      // limiter.
+      struct FixedDigital {
+        // By setting `gain_db` to a value greater than zero, the limiter can be
+        // turned into a compressor that first applies a fixed gain.
+        float gain_db = 0.0f;
+      } fixed_digital;
     } gain_controller2;
 
     std::string ToString() const;