Bump to WebRTC M120 release

Some API deprecation -- ExperimentalAgc and ExperimentalNs are gone.
We're continuing to carry iSAC even though it's gone upstream, but maybe
we'll want to drop that soon.

webrtc/modules/audio_processing/capture_levels_adjuster/BUILD.gn

@@ -0,0 +1,45 @@
+# Copyright (c) 2021 The WebRTC project authors. All Rights Reserved.
+#
+# Use of this source code is governed by a BSD-style license
+# that can be found in the LICENSE file in the root of the source
+# tree. An additional intellectual property rights grant can be found
+# in the file PATENTS.  All contributing project authors may
+# be found in the AUTHORS file in the root of the source tree.
+
+import("../../../webrtc.gni")
+
+rtc_library("capture_levels_adjuster") {
+  visibility = [ "*" ]
+
+  sources = [
+    "audio_samples_scaler.cc",
+    "audio_samples_scaler.h",
+    "capture_levels_adjuster.cc",
+    "capture_levels_adjuster.h",
+  ]
+
+  defines = []
+
+  deps = [
+    "..:audio_buffer",
+    "../../../api:array_view",
+    "../../../rtc_base:checks",
+    "../../../rtc_base:safe_minmax",
+  ]
+}
+
+rtc_library("capture_levels_adjuster_unittests") {
+  testonly = true
+
+  sources = [
+    "audio_samples_scaler_unittest.cc",
+    "capture_levels_adjuster_unittest.cc",
+  ]
+  deps = [
+    ":capture_levels_adjuster",
+    "..:audioproc_test_utils",
+    "../../../rtc_base:gunit_helpers",
+    "../../../rtc_base:stringutils",
+    "../../../test:test_support",
+  ]
+}

webrtc/modules/audio_processing/capture_levels_adjuster/audio_samples_scaler.cc

@@ -0,0 +1,92 @@
+/*
+ *  Copyright (c) 2021 The WebRTC project authors. All Rights Reserved.
+ *
+ *  Use of this source code is governed by a BSD-style license
+ *  that can be found in the LICENSE file in the root of the source
+ *  tree. An additional intellectual property rights grant can be found
+ *  in the file PATENTS.  All contributing project authors may
+ *  be found in the AUTHORS file in the root of the source tree.
+ */
+#include "modules/audio_processing/capture_levels_adjuster/audio_samples_scaler.h"
+
+#include <algorithm>
+
+#include "api/array_view.h"
+#include "modules/audio_processing/audio_buffer.h"
+#include "rtc_base/checks.h"
+#include "rtc_base/numerics/safe_minmax.h"
+
+namespace webrtc {
+
+AudioSamplesScaler::AudioSamplesScaler(float initial_gain)
+    : previous_gain_(initial_gain), target_gain_(initial_gain) {}
+
+void AudioSamplesScaler::Process(AudioBuffer& audio_buffer) {
+  if (static_cast<int>(audio_buffer.num_frames()) != samples_per_channel_) {
+    // Update the members depending on audio-buffer length if needed.
+    RTC_DCHECK_GT(audio_buffer.num_frames(), 0);
+    samples_per_channel_ = static_cast<int>(audio_buffer.num_frames());
+    one_by_samples_per_channel_ = 1.f / samples_per_channel_;
+  }
+
+  if (target_gain_ == 1.f && previous_gain_ == target_gain_) {
+    // If only a gain of 1 is to be applied, do an early return without applying
+    // any gain.
+    return;
+  }
+
+  float gain = previous_gain_;
+  if (previous_gain_ == target_gain_) {
+    // Apply a non-changing gain.
+    for (size_t channel = 0; channel < audio_buffer.num_channels(); ++channel) {
+      rtc::ArrayView<float> channel_view(audio_buffer.channels()[channel],
+                                         samples_per_channel_);
+      for (float& sample : channel_view) {
+        sample *= gain;
+      }
+    }
+  } else {
+    const float increment =
+        (target_gain_ - previous_gain_) * one_by_samples_per_channel_;
+
+    if (increment > 0.f) {
+      // Apply an increasing gain.
+      for (size_t channel = 0; channel < audio_buffer.num_channels();
+           ++channel) {
+        gain = previous_gain_;
+        rtc::ArrayView<float> channel_view(audio_buffer.channels()[channel],
+                                           samples_per_channel_);
+        for (float& sample : channel_view) {
+          gain = std::min(gain + increment, target_gain_);
+          sample *= gain;
+        }
+      }
+    } else {
+      // Apply a decreasing gain.
+      for (size_t channel = 0; channel < audio_buffer.num_channels();
+           ++channel) {
+        gain = previous_gain_;
+        rtc::ArrayView<float> channel_view(audio_buffer.channels()[channel],
+                                           samples_per_channel_);
+        for (float& sample : channel_view) {
+          gain = std::max(gain + increment, target_gain_);
+          sample *= gain;
+        }
+      }
+    }
+  }
+  previous_gain_ = target_gain_;
+
+  // Saturate the samples to be in the S16 range.
+  for (size_t channel = 0; channel < audio_buffer.num_channels(); ++channel) {
+    rtc::ArrayView<float> channel_view(audio_buffer.channels()[channel],
+                                       samples_per_channel_);
+    for (float& sample : channel_view) {
+      constexpr float kMinFloatS16Value = -32768.f;
+      constexpr float kMaxFloatS16Value = 32767.f;
+      sample = rtc::SafeClamp(sample, kMinFloatS16Value, kMaxFloatS16Value);
+    }
+  }
+}
+
+}  // namespace webrtc

webrtc/modules/audio_processing/capture_levels_adjuster/audio_samples_scaler.h

@@ -0,0 +1,46 @@
+/*
+ *  Copyright (c) 2021 The WebRTC project authors. All Rights Reserved.
+ *
+ *  Use of this source code is governed by a BSD-style license
+ *  that can be found in the LICENSE file in the root of the source
+ *  tree. An additional intellectual property rights grant can be found
+ *  in the file PATENTS.  All contributing project authors may
+ *  be found in the AUTHORS file in the root of the source tree.
+ */
+
+#ifndef MODULES_AUDIO_PROCESSING_CAPTURE_LEVELS_ADJUSTER_AUDIO_SAMPLES_SCALER_H_
+#define MODULES_AUDIO_PROCESSING_CAPTURE_LEVELS_ADJUSTER_AUDIO_SAMPLES_SCALER_H_
+
+#include <stddef.h>
+
+#include "modules/audio_processing/audio_buffer.h"
+
+namespace webrtc {
+
+// Handles and applies a gain to the samples in an audio buffer.
+// The gain is applied for each sample and any changes in the gain take effect
+// gradually (in a linear manner) over one frame.
+class AudioSamplesScaler {
+ public:
+  // C-tor. The supplied `initial_gain` is used immediately at the first call to
+  // Process(), i.e., in contrast to the gain supplied by SetGain(...) there is
+  // no gradual change to the `initial_gain`.
+  explicit AudioSamplesScaler(float initial_gain);
+  AudioSamplesScaler(const AudioSamplesScaler&) = delete;
+  AudioSamplesScaler& operator=(const AudioSamplesScaler&) = delete;
+
+  // Applies the specified gain to the audio in `audio_buffer`.
+  void Process(AudioBuffer& audio_buffer);
+
+  // Sets the gain to apply to each sample.
+  void SetGain(float gain) { target_gain_ = gain; }
+
+ private:
+  float previous_gain_ = 1.f;
+  float target_gain_ = 1.f;
+  int samples_per_channel_ = -1;
+  float one_by_samples_per_channel_ = -1.f;
+};
+}  // namespace webrtc
+
+#endif  // MODULES_AUDIO_PROCESSING_CAPTURE_LEVELS_ADJUSTER_AUDIO_SAMPLES_SCALER_H_

webrtc/modules/audio_processing/capture_levels_adjuster/capture_levels_adjuster.cc

@@ -0,0 +1,96 @@
+/*
+ *  Copyright (c) 2021 The WebRTC project authors. All Rights Reserved.
+ *
+ *  Use of this source code is governed by a BSD-style license
+ *  that can be found in the LICENSE file in the root of the source
+ *  tree. An additional intellectual property rights grant can be found
+ *  in the file PATENTS.  All contributing project authors may
+ *  be found in the AUTHORS file in the root of the source tree.
+ */
+#include "modules/audio_processing/capture_levels_adjuster/capture_levels_adjuster.h"
+
+#include "modules/audio_processing/audio_buffer.h"
+#include "rtc_base/checks.h"
+#include "rtc_base/numerics/safe_minmax.h"
+
+namespace webrtc {
+
+namespace {
+
+constexpr int kMinAnalogMicGainLevel = 0;
+constexpr int kMaxAnalogMicGainLevel = 255;
+
+float ComputeLevelBasedGain(int emulated_analog_mic_gain_level) {
+  static_assert(
+      kMinAnalogMicGainLevel == 0,
+      "The minimum gain level must be 0 for the maths below to work.");
+  static_assert(kMaxAnalogMicGainLevel > 0,
+                "The minimum gain level must be larger than 0 for the maths "
+                "below to work.");
+  constexpr float kGainToLevelMultiplier = 1.f / kMaxAnalogMicGainLevel;
+
+  RTC_DCHECK_GE(emulated_analog_mic_gain_level, kMinAnalogMicGainLevel);
+  RTC_DCHECK_LE(emulated_analog_mic_gain_level, kMaxAnalogMicGainLevel);
+  return kGainToLevelMultiplier * emulated_analog_mic_gain_level;
+}
+
+float ComputePreGain(float pre_gain,
+                     int emulated_analog_mic_gain_level,
+                     bool emulated_analog_mic_gain_enabled) {
+  return emulated_analog_mic_gain_enabled
+             ? pre_gain * ComputeLevelBasedGain(emulated_analog_mic_gain_level)
+             : pre_gain;
+}
+
+}  // namespace
+
+CaptureLevelsAdjuster::CaptureLevelsAdjuster(
+    bool emulated_analog_mic_gain_enabled,
+    int emulated_analog_mic_gain_level,
+    float pre_gain,
+    float post_gain)
+    : emulated_analog_mic_gain_enabled_(emulated_analog_mic_gain_enabled),
+      emulated_analog_mic_gain_level_(emulated_analog_mic_gain_level),
+      pre_gain_(pre_gain),
+      pre_adjustment_gain_(ComputePreGain(pre_gain_,
+                                          emulated_analog_mic_gain_level_,
+                                          emulated_analog_mic_gain_enabled_)),
+      pre_scaler_(pre_adjustment_gain_),
+      post_scaler_(post_gain) {}
+
+void CaptureLevelsAdjuster::ApplyPreLevelAdjustment(AudioBuffer& audio_buffer) {
+  pre_scaler_.Process(audio_buffer);
+}
+
+void CaptureLevelsAdjuster::ApplyPostLevelAdjustment(
+    AudioBuffer& audio_buffer) {
+  post_scaler_.Process(audio_buffer);
+}
+
+void CaptureLevelsAdjuster::SetPreGain(float pre_gain) {
+  pre_gain_ = pre_gain;
+  UpdatePreAdjustmentGain();
+}
+
+void CaptureLevelsAdjuster::SetPostGain(float post_gain) {
+  post_scaler_.SetGain(post_gain);
+}
+
+void CaptureLevelsAdjuster::SetAnalogMicGainLevel(int level) {
+  RTC_DCHECK_GE(level, kMinAnalogMicGainLevel);
+  RTC_DCHECK_LE(level, kMaxAnalogMicGainLevel);
+  int clamped_level =
+      rtc::SafeClamp(level, kMinAnalogMicGainLevel, kMaxAnalogMicGainLevel);
+
+  emulated_analog_mic_gain_level_ = clamped_level;
+  UpdatePreAdjustmentGain();
+}
+
+void CaptureLevelsAdjuster::UpdatePreAdjustmentGain() {
+  pre_adjustment_gain_ =
+      ComputePreGain(pre_gain_, emulated_analog_mic_gain_level_,
+                     emulated_analog_mic_gain_enabled_);
+  pre_scaler_.SetGain(pre_adjustment_gain_);
+}
+
+}  // namespace webrtc

webrtc/modules/audio_processing/capture_levels_adjuster/capture_levels_adjuster.h

@@ -0,0 +1,88 @@
+/*
+ *  Copyright (c) 2021 The WebRTC project authors. All Rights Reserved.
+ *
+ *  Use of this source code is governed by a BSD-style license
+ *  that can be found in the LICENSE file in the root of the source
+ *  tree. An additional intellectual property rights grant can be found
+ *  in the file PATENTS.  All contributing project authors may
+ *  be found in the AUTHORS file in the root of the source tree.
+ */
+#ifndef MODULES_AUDIO_PROCESSING_CAPTURE_LEVELS_ADJUSTER_CAPTURE_LEVELS_ADJUSTER_H_
+#define MODULES_AUDIO_PROCESSING_CAPTURE_LEVELS_ADJUSTER_CAPTURE_LEVELS_ADJUSTER_H_
+
+#include <stddef.h>
+
+#include "modules/audio_processing/audio_buffer.h"
+#include "modules/audio_processing/capture_levels_adjuster/audio_samples_scaler.h"
+
+namespace webrtc {
+
+// Adjusts the level of the capture signal before and after all capture-side
+// processing is done using a combination of explicitly specified gains
+// and an emulated analog gain functionality where a specified analog level
+// results in an additional gain. The pre-adjustment is achieved by combining
+// the gain value `pre_gain` and the level `emulated_analog_mic_gain_level` to
+// form a combined gain of `pre_gain`*`emulated_analog_mic_gain_level`/255 which
+// is multiplied to each sample. The intention of the
+// `emulated_analog_mic_gain_level` is to be controlled by the analog AGC
+// functionality and to produce an emulated analog mic gain equal to
+// `emulated_analog_mic_gain_level`/255. The post level adjustment is achieved
+// by multiplying each sample with the value of `post_gain`. Any changes in the
+// gains take are done smoothly over one frame and the scaled samples are
+// clamped to fit into the allowed S16 sample range.
+class CaptureLevelsAdjuster {
+ public:
+  // C-tor. The values for the level and the gains must fulfill
+  // 0 <= emulated_analog_mic_gain_level <= 255.
+  // 0.f <= pre_gain.
+  // 0.f <= post_gain.
+  CaptureLevelsAdjuster(bool emulated_analog_mic_gain_enabled,
+                        int emulated_analog_mic_gain_level,
+                        float pre_gain,
+                        float post_gain);
+  CaptureLevelsAdjuster(const CaptureLevelsAdjuster&) = delete;
+  CaptureLevelsAdjuster& operator=(const CaptureLevelsAdjuster&) = delete;
+
+  // Adjusts the level of the signal. This should be called before any of the
+  // other processing is performed.
+  void ApplyPreLevelAdjustment(AudioBuffer& audio_buffer);
+
+  // Adjusts the level of the signal. This should be called after all of the
+  // other processing have been performed.
+  void ApplyPostLevelAdjustment(AudioBuffer& audio_buffer);
+
+  // Sets the gain to apply to each sample before any of the other processing is
+  // performed.
+  void SetPreGain(float pre_gain);
+
+  // Returns the total pre-adjustment gain applied, comprising both the pre_gain
+  // as well as the gain from the emulated analog mic, to each sample before any
+  // of the other processing is performed.
+  float GetPreAdjustmentGain() const { return pre_adjustment_gain_; }
+
+  // Sets the gain to apply to each sample after all of the other processing
+  // have been performed.
+  void SetPostGain(float post_gain);
+
+  // Sets the analog gain level to use for the emulated analog gain.
+  // `level` must be in the range [0...255].
+  void SetAnalogMicGainLevel(int level);
+
+  // Returns the current analog gain level used for the emulated analog gain.
+  int GetAnalogMicGainLevel() const { return emulated_analog_mic_gain_level_; }
+
+ private:
+  // Updates the value of `pre_adjustment_gain_` based on the supplied values
+  // for `pre_gain` and `emulated_analog_mic_gain_level_`.
+  void UpdatePreAdjustmentGain();
+
+  const bool emulated_analog_mic_gain_enabled_;
+  int emulated_analog_mic_gain_level_;
+  float pre_gain_;
+  float pre_adjustment_gain_;
+  AudioSamplesScaler pre_scaler_;
+  AudioSamplesScaler post_scaler_;
+};
+}  // namespace webrtc
+
+#endif  // MODULES_AUDIO_PROCESSING_CAPTURE_LEVELS_ADJUSTER_CAPTURE_LEVELS_ADJUSTER_H_