New module for the adaptive level controlling functionality in the audio processing module

webrtc/modules/audio_processing/level_controller/gain_applier.cc

Index: webrtc/modules/audio_processing/level_controller/gain_applier.cc
diff --git a/webrtc/modules/audio_processing/level_controller/gain_applier.cc b/webrtc/modules/audio_processing/level_controller/gain_applier.cc
new file mode 100644
index 0000000000000000000000000000000000000000..89ef2f561aaeba5c2efea9b63190ea48b0d823ca
--- /dev/null
+++ b/webrtc/modules/audio_processing/level_controller/gain_applier.cc
@@ -0,0 +1,140 @@
+/*
+ *  Copyright (c) 2016 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 "webrtc/modules/audio_processing/level_controller/gain_applier.h"
+
+#include <algorithm>
+
+#include "webrtc/base/array_view.h"
+#include "webrtc/base/checks.h"
+
+#include "webrtc/modules/audio_processing/audio_buffer.h"
+#include "webrtc/modules/audio_processing/logging/apm_data_dumper.h"
+
+namespace webrtc {
+namespace {
+
+const float kMaxSampleValue = 32767.f;
+const float kMinSampleValue = -32767.f;
+
+int CountSaturations(rtc::ArrayView<const float> in) {
+  return std::count_if(in.begin(), in.end(), [](float v) {

[aleloi, 2016/06/28 09:35:52]

Probably the compiler is smart and this is not affecting performance in any way,
but the array has const floats while the lambda takes floats. If it were an
array of complex objects, I think copying would happen. What is the difference
to '[](const float & v)' ?

[peah-webrtc, 2016/06/28 22:19:37]

I'm not an expert on this, but I think it should be fine. As you say, for
complex objects there would be copies made, but a float should fit into the
registers and should be very cheap to handle.

But I guess it cannot increase the complexity to make it a const reference, and
as you point out, that solution is consistent in that the array consists of
const floats, so I'll change it to that.

Done.

[hlundin-webrtc, 2016/06/29 08:56:28]

I think that in this case it makes no difference. Passing a float or a reference
should be just as efficient. For the record, the declaration of count_if does
indeed allow const ref as well as "by value".

[peah-webrtc, 2016/06/29 09:13:53]

Acknowledged.

+    return v >= kMaxSampleValue || v <= kMinSampleValue;
+  });
+}
+
+int CountSaturations(const AudioBuffer& audio) {
+  int num_saturations = 0;
+  for (size_t k = 0; k < audio.num_channels(); ++k) {
+    num_saturations += CountSaturations(rtc::ArrayView<const float>(
+        audio.channels_const_f()[k], audio.num_frames()));
+  }
+  return num_saturations;
+}
+
+void LimitToAllowedRange(rtc::ArrayView<float> x) {
+  for (auto& v : x) {
+    v = std::max(kMinSampleValue, v);
+    v = std::min(kMaxSampleValue, v);
+  }
+}
+
+void LimitToAllowedRange(AudioBuffer* audio) {
+  for (size_t k = 0; k < audio->num_channels(); ++k) {
+    LimitToAllowedRange(
+        rtc::ArrayView<float>(audio->channels_f()[k], audio->num_frames()));
+  }
+}
+
+float ApplyIncreasingGain(float new_gain,
+                          float old_gain,
+                          float step_size,
+                          rtc::ArrayView<float> x) {
+  RTC_DCHECK_LT(0.f, step_size);
+  float gain = old_gain;
+  for (auto& v : x) {
+    gain = std::min(new_gain, gain + step_size);

[aleloi, 2016/06/28 09:35:52]

Maybe move the gain calculation outside of the loop for improved readability? Or
call ApplyConstantGain after calculating it. Same for the function below.

[peah-webrtc, 2016/06/28 22:19:37]

I'm not fully sure of what you mean, but the intention is to  adjust the gain
towards the new gain in a smooth manner to avoid discontinuities resulting in
audible distortions. In order to do that, the updating of the gain needs to be
inside the loop. Setting a new gain before the loop and applying the gain to the
whole frame could potentially cause an audible distortion.

[aleloi, 2016/06/29 14:11:18]

Acknowledged.

+    v *= gain;
+  }
+  return gain;
+}
+
+float ApplyDecreasingGain(float new_gain,
+                          float old_gain,
+                          float step_size,
+                          rtc::ArrayView<float> x) {
+  RTC_DCHECK_LT(0.f, step_size);
+  float gain = old_gain;
+  for (auto& v : x) {
+    gain = std::max(new_gain, gain - step_size);
+    v *= gain;
+  }
+  return gain;
+}
+
+float ApplyConstantGain(float gain, rtc::ArrayView<float> x) {
+  for (auto& v : x) {
+    v *= gain;
+  }
+
+  return gain;
+}
+
+float ApplyGain(float new_gain,
+                float old_gain,
+                float step_size,
+                rtc::ArrayView<float> x) {
+  if (new_gain == old_gain) {
+    return ApplyConstantGain(new_gain, x);
+  } else if (new_gain > old_gain) {
+    return ApplyIncreasingGain(new_gain, old_gain, step_size, x);
+  } else {
+    return ApplyDecreasingGain(new_gain, old_gain, step_size, x);
+  }
+}
+
+}  // namespace
+
+GainApplier::GainApplier(ApmDataDumper* data_dumper)
+    : data_dumper_(data_dumper) {}
+
+void GainApplier::Initialize(int sample_rate_hz) {
+  RTC_DCHECK(sample_rate_hz == AudioProcessing::kSampleRate8kHz ||
+             sample_rate_hz == AudioProcessing::kSampleRate16kHz ||
+             sample_rate_hz == AudioProcessing::kSampleRate32kHz ||
+             sample_rate_hz == AudioProcessing::kSampleRate48kHz);
+  old_gain_ = 1.f;
+  gain_change_step_size_ = 0.001f * (48000.f / sample_rate_hz);

[aleloi, 2016/06/28 09:35:52]

Please define a constant for 0.001f.

[peah-webrtc, 2016/06/28 22:19:37]

That definitely makes sense.

Done.

+}

[aleloi, 2016/06/28 09:35:52]

Do we need both a constructor and an Initialize() method? With just a
constructor, the object is never in a half-initialized state, and it's possible
to document that gain_change_step_size_ doesn't change. Are there any benefits
with two methods?

[peah-webrtc, 2016/06/28 22:19:37]

I definitely agree that it would be nicer to do the initialization only at
construction time. However, as the audio processing module (APM) is constructed,
the sample rate and number of channels is specified by the incoming audio stream
and therefore not known when APM is constructed. Furthermore, the audio stream
properties sample rate and number of channels can, and do, change over time.
Each time these change, a reinitialization of the APM is needed and (I guess) to
let that reinitialization have a minimal impact on the performance most of the
submodules are reinitialized without being reconstructed.

  

[aleloi, 2016/06/29 14:11:18]

Acknowledged.

+
+int GainApplier::Process(float new_gain, AudioBuffer* audio) {
+  RTC_CHECK_NE(0.f, gain_change_step_size_);
+  int num_saturations = 0;
+  if (new_gain != 1.f) {
+    float last_applied_gain = 1.f;
+    for (size_t k = 0; k < audio->num_channels(); ++k) {
+      // TODO(peah): Consider using a faster update rate downwards than upwards.
+      last_applied_gain = ApplyGain(
+          new_gain, old_gain_, gain_change_step_size_,
+          rtc::ArrayView<float>(audio->channels_f()[k], audio->num_frames()));
+    }
+    // TODO(peah): Consider the need for faster gain reduction in case of
+    // excessive saturation.
+    num_saturations = CountSaturations(*audio);
+    LimitToAllowedRange(audio);
+    old_gain_ = last_applied_gain;
+  }
+
+  data_dumper_->DumpRaw("lc_last_applied_gain", 1, &old_gain_);
+
+  return num_saturations;
+}
+
+}  // namespace webrtc