Add Automatic Gain Control

CHANGELOG.md

@@ -8,17 +8,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
-- Support for *ALAC/AIFF* 
+- Support for *ALAC/AIFF*
+- Add `automatic_gain_control` source for dynamic audio level adjustment.
 - New sources:
     - `fade_out` fades an input out using a linear gain fade.
     - `linear_gain_ramp` applies a linear gain change to a sound over a
       given duration. `fade_out` is implemented as a `linear_gain_ramp` and
-      `fade_in` has been refactored to use the `linear_gain_ramp` 
+      `fade_in` has been refactored to use the `linear_gain_ramp`
       implementation.
 
 ### Fixed
 - `Sink.try_seek` now updates `controls.position` before returning. Calls to `Sink.get_pos`
-  done immediately after a seek will now return the correct value.  
+  done immediately after a seek will now return the correct value.
 
 ### Changed
 - `SamplesBuffer` is now `Clone`
@@ -44,15 +45,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `Source` trait is now also implemented for `Box<dyn Source>` and `&mut Source`
 - `fn new_vorbis` is now also available when the `symphonia-vorbis` feature is enabled
 
-### Added 
+### Added
 - Adds a new method `try_seek` to all sources. It returns either an error or
   seeks to the given position. A few sources are "unsupported" they return the
   error `Unsupported`.
 - Adds `SpatialSink::clear()` bringing it in line with `Sink`
 
 ### Fixed
 - channel upscaling now follows the 'WAVEFORMATEXTENSIBLE' format and no longer
-  repeats the last source channel on all extra output channels. 
+  repeats the last source channel on all extra output channels.
   Stereo content playing on a 5.1 speaker set will now only use the front left
   and front right speaker instead of repeating the right sample on all speakers
   except the front left one.

benches/effects.rs

@@ -46,3 +46,41 @@ fn amplify(bencher: Bencher) {
         .with_inputs(|| TestSource::music_wav().to_f32s())
         .bench_values(|source| source.amplify(0.8).for_each(divan::black_box_drop))
 }
+
+#[divan::bench]
+fn agc_enabled(bencher: Bencher) {
+    bencher
+        .with_inputs(|| TestSource::music_wav().to_f32s())
+        .bench_values(|source| {
+            source
+                .automatic_gain_control(
+                    1.0,   // target_level
+                    4.0,   // attack_time (in seconds)
+                    0.005, // release_time (in seconds)
+                    5.0,   // absolute_max_gain
+                )
+                .for_each(divan::black_box_drop)
+        })
+}
+
+#[divan::bench]
+fn agc_disabled(bencher: Bencher) {
+    bencher
+        .with_inputs(|| TestSource::music_wav().to_f32s())
+        .bench_values(|source| {
+            // Create the AGC source
+            let amplified_source = source.automatic_gain_control(
+                1.0,   // target_level
+                4.0,   // attack_time (in seconds)
+                0.005, // release_time (in seconds)
+                5.0,   // absolute_max_gain
+            );
+
+            // Get the control handle and disable AGC
+            let agc_control = amplified_source.get_agc_control();
+            agc_control.store(false, std::sync::atomic::Ordering::Relaxed);
+
+            // Process the audio stream with AGC disabled
+            amplified_source.for_each(divan::black_box_drop)
+        })
+}

src/conversions/sample.rs

@@ -80,6 +80,9 @@ pub trait Sample: CpalSample {
     /// Multiplies the value of this sample by the given amount.
     fn amplify(self, value: f32) -> Self;
 
+    /// Converts the sample to an f32 value.
+    fn to_f32(self) -> f32;
+
     /// Calls `saturating_add` on the sample.
     fn saturating_add(self, other: Self) -> Self;
 
@@ -102,6 +105,12 @@ impl Sample for u16 {
         ((self as f32) * value) as u16
     }
 
+    #[inline]
+    fn to_f32(self) -> f32 {
+        // Convert u16 to f32 in the range [-1.0, 1.0]
+        (self as f32 - 32768.0) / 32768.0
+    }
+
     #[inline]
     fn saturating_add(self, other: u16) -> u16 {
         self.saturating_add(other)
@@ -125,6 +134,12 @@ impl Sample for i16 {
         ((self as f32) * value) as i16
     }
 
+    #[inline]
+    fn to_f32(self) -> f32 {
+        // Convert i16 to f32 in the range [-1.0, 1.0]
+        self as f32 / 32768.0
+    }
+
     #[inline]
     fn saturating_add(self, other: i16) -> i16 {
         self.saturating_add(other)
@@ -147,6 +162,12 @@ impl Sample for f32 {
         self * value
     }
 
+    #[inline]
+    fn to_f32(self) -> f32 {
+        // f32 is already in the correct format
+        self
+    }
+
     #[inline]
     fn saturating_add(self, other: f32) -> f32 {
         self + other