Add replacement interface for webrtc::GainConrol
The pointer-to-submodule interfaces are being removed.
This CL:
1) introduces AudioProcessing::Config::GainController1 with most config,
2) adds functions to APM for setting and getting analog gain,
3) creates a temporary GainControlConfigProxy to support the transition
to the new config.
4) Moves the lock references in GainControlForExperimentalAgc and
GainControlImpl into the GainControlConfigProxy, as it becomes the
sole AGC object with functionality exposed to the client.
Bug: webrtc:9947, webrtc:9878
Change-Id: Ic31e15e9bb26d6497a92b77874e0b6cab21ff2b2
Reviewed-on: https://webrtc-review.googlesource.com/c/src/+/126485
Commit-Queue: Sam Zackrisson <saza@webrtc.org>
Reviewed-by: Fredrik Solenberg <solenberg@webrtc.org>
Reviewed-by: Alessio Bazzica <alessiob@webrtc.org>
Cr-Commit-Position: refs/heads/master@{#27316}diff --git a/modules/audio_processing/include/audio_processing.h b/modules/audio_processing/include/audio_processing.h
index 6a0917a..1d421f5 100644
--- a/modules/audio_processing/include/audio_processing.h
+++ b/modules/audio_processing/include/audio_processing.h
@@ -239,6 +239,11 @@
// The parameters and behavior of the audio processing module are controlled
// by changing the default values in the AudioProcessing::Config struct.
// The config is applied by passing the struct to the ApplyConfig method.
+ //
+ // This config is intended to be used during setup, and to enable/disable
+ // top-level processing effects. Use during processing may cause undesired
+ // submodule resets, affecting the audio quality. Use the RuntimeSetting
+ // construct for runtime configuration.
struct Config {
// Enabled the pre-amplifier. It amplifies the capture signal
// before any other processing is done.
@@ -273,6 +278,59 @@
bool enabled = false;
} voice_detection;
+ // Enables automatic gain control (AGC) functionality.
+ // The automatic gain control (AGC) component brings the signal to an
+ // appropriate range. This is done by applying a digital gain directly and,
+ // in the analog mode, prescribing an analog gain to be applied at the audio
+ // HAL.
+ // Recommended to be enabled on the client-side.
+ struct GainController1 {
+ bool enabled = false;
+ enum Mode {
+ // Adaptive mode intended for use if an analog volume control is
+ // available on the capture device. It will require the user to provide
+ // coupling between the OS mixer controls and AGC through the
+ // stream_analog_level() functions.
+ // It consists of an analog gain prescription for the audio device and a
+ // digital compression stage.
+ kAdaptiveAnalog,
+ // Adaptive mode intended for situations in which an analog volume
+ // control is unavailable. It operates in a similar fashion to the
+ // adaptive analog mode, but with scaling instead applied in the digital
+ // domain. As with the analog mode, it additionally uses a digital
+ // compression stage.
+ kAdaptiveDigital,
+ // Fixed mode which enables only the digital compression stage also used
+ // by the two adaptive modes.
+ // It is distinguished from the adaptive modes by considering only a
+ // short time-window of the input signal. It applies a fixed gain
+ // through most of the input level range, and compresses (gradually
+ // reduces gain with increasing level) the input signal at higher
+ // levels. This mode is preferred on embedded devices where the capture
+ // signal level is predictable, so that a known gain can be applied.
+ kFixedDigital
+ };
+ Mode mode = kAdaptiveAnalog;
+ // Sets the target peak level (or envelope) of the AGC in dBFs (decibels
+ // from digital full-scale). The convention is to use positive values. For
+ // instance, passing in a value of 3 corresponds to -3 dBFs, or a target
+ // level 3 dB below full-scale. Limited to [0, 31].
+ int target_level_dbfs = 3;
+ // Sets the maximum gain the digital compression stage may apply, in dB. A
+ // higher number corresponds to greater compression, while a value of 0
+ // will leave the signal uncompressed. Limited to [0, 90].
+ // For updates after APM setup, use a RuntimeSetting instead.
+ int compression_gain_db = 9;
+ // When enabled, the compression stage will hard limit the signal to the
+ // target level. Otherwise, the signal will be compressed but not limited
+ // above the target level.
+ bool enable_limiter = true;
+ // Sets the minimum and maximum analog levels of the audio capture device.
+ // Must be set if an analog mode is used. Limited to [0, 65535].
+ int analog_level_minimum = 0;
+ int analog_level_maximum = 255;
+ } 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
@@ -332,6 +390,7 @@
enum class Type {
kNotSpecified,
kCapturePreGain,
+ kCaptureCompressionGain,
kCustomRenderProcessingRuntimeSetting
};
@@ -343,6 +402,14 @@
return {Type::kCapturePreGain, gain};
}
+ // Corresponds to Config::GainController1::compression_gain_db, but for
+ // runtime configuration.
+ static RuntimeSetting CreateCompressionGainDb(int gain_db) {
+ RTC_DCHECK_GE(gain_db, 0);
+ RTC_DCHECK_LE(gain_db, 90);
+ return {Type::kCaptureCompressionGain, static_cast<float>(gain_db)};
+ }
+
static RuntimeSetting CreateCustomRenderSetting(float payload) {
return {Type::kCustomRenderProcessingRuntimeSetting, payload};
}
@@ -489,6 +556,16 @@
const StreamConfig& output_config,
float* const* dest) = 0;
+ // This must be called prior to ProcessStream() if and only if adaptive analog
+ // gain control is enabled, to pass the current analog level from the audio
+ // HAL. Must be within the range provided in Config::GainController1.
+ virtual void set_stream_analog_level(int level) = 0;
+
+ // When an analog mode is set, this should be called after ProcessStream()
+ // to obtain the recommended new analog level for the audio HAL. It is the
+ // user's responsibility to apply this level.
+ virtual int recommended_stream_analog_level() const = 0;
+
// This must be called if and only if echo processing is enabled.
//
// Sets the |delay| in ms between ProcessReverseStream() receiving a far-end
@@ -553,6 +630,12 @@
// remote track.
virtual AudioProcessingStats GetStatistics(bool has_remote_tracks) const = 0;
+ // DEPRECATED.
+ // TODO(https://crbug.com/webrtc/9878): Remove.
+ // Configure via AudioProcessing::ApplyConfig during setup.
+ // Set runtime settings via AudioProcessing::SetRuntimeSetting.
+ // Get stats via AudioProcessing::GetStatistics.
+ //
// These provide access to the component interfaces and should never return
// NULL. The pointers will be valid for the lifetime of the APM instance.
// The memory for these objects is entirely managed internally.