feat: add optional 64-bit sample precision (#821)

Replace hardcoded f32 types with Sample/Float type aliases throughout
the codebase for consistency. Add compile-time configurability for
sample precision via a 64bit feature flag.

Tise 64bit mode addresses precision drift in long-running signal
generators and accumulated operations, following an approach similar
to CamillaDSP's compile-time precision selection.

Author: roderickvd

.github/workflows/ci.yml

@@ -55,3 +55,10 @@ jobs:
       - run: cargo check --tests --lib --no-default-features
       # Check alternative decoders.
       - run: cargo check --tests --lib --no-default-features --features claxon,hound,minimp3,lewton
+      # Test 64-bit sample mode
+      - run: cargo test --all-targets --features 64bit
+      - run: cargo test --doc --features 64bit
+      - run: cargo test --all-targets --all-features --features 64bit
+      # Check examples compile in both modes
+      - run: cargo check --examples
+      - run: cargo check --examples --features 64bit

CHANGELOG.md

@@ -28,6 +28,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Four dithering algorithms: `TPDF`, `RPDF`, `GPDF`, and `HighPass`
   - `DitherAlgorithm` enum for algorithm selection
   - `Source::dither()` function for applying dithering
+- Added `64bit` feature to opt-in to 64-bit sample precision (`f64`).
 
 ### Fixed
 - docs.rs will now document all features, including those that are optional.

Cargo.toml

@@ -34,6 +34,8 @@ wav_output = ["dep:hound"]
 tracing = ["dep:tracing"]
 # Experimental features using atomic floating-point operations
 experimental = ["dep:atomic_float"]
+# Perform all calculations with 64-bit floats (instead of 32)
+64bit = []
 
 # Audio generation features
 #

benches/conversions.rs

@@ -1,6 +1,6 @@
-use dasp_sample::{Duplex, Sample};
+use dasp_sample::{Duplex, Sample as DaspSample};
 use divan::Bencher;
-use rodio::conversions::SampleTypeConverter;
+use rodio::{conversions::SampleTypeConverter, Sample};
 
 mod shared;
 
@@ -9,7 +9,7 @@ fn main() {
 }
 
 #[divan::bench(types = [i16, u16, f32])]
-fn from_sample<S: Duplex<f32>>(bencher: Bencher) {
+fn from_sample<S: Duplex<Sample>>(bencher: Bencher) {
     bencher
         .with_inputs(|| {
             shared::music_wav()
@@ -18,6 +18,6 @@ fn from_sample<S: Duplex<f32>>(bencher: Bencher) {
                 .into_iter()
         })
         .bench_values(|source| {
-            SampleTypeConverter::<_, rodio::Sample>::new(source).for_each(divan::black_box_drop)
+            SampleTypeConverter::<_, Sample>::new(source).for_each(divan::black_box_drop)
         })
 }

benches/effects.rs

@@ -1,7 +1,6 @@
 use std::time::Duration;
 
 use divan::Bencher;
-use rodio::source::AutomaticGainControlSettings;
 use rodio::Source;
 
 mod shared;
@@ -48,7 +47,7 @@ fn amplify(bencher: Bencher) {
 fn agc_enabled(bencher: Bencher) {
     bencher.with_inputs(music_wav).bench_values(|source| {
         source
-            .automatic_gain_control(AutomaticGainControlSettings::default())
+            .automatic_gain_control(Default::default())
             .for_each(divan::black_box_drop)
     })
 }
@@ -58,8 +57,7 @@ fn agc_enabled(bencher: Bencher) {
 fn agc_disabled(bencher: Bencher) {
     bencher.with_inputs(music_wav).bench_values(|source| {
         // Create the AGC source
-        let amplified_source =
-            source.automatic_gain_control(AutomaticGainControlSettings::default());
+        let amplified_source = source.automatic_gain_control(Default::default());
 
         // Get the control handle and disable AGC
         let agc_control = amplified_source.get_agc_control();

benches/pipeline.rs

@@ -2,7 +2,6 @@ use std::num::NonZero;
 use std::time::Duration;
 
 use divan::Bencher;
-use rodio::source::AutomaticGainControlSettings;
 use rodio::ChannelCount;
 use rodio::{source::UniformSourceIterator, Source};
 
@@ -20,7 +19,7 @@ fn long(bencher: Bencher) {
             .high_pass(300)
             .amplify(1.2)
             .speed(0.9)
-            .automatic_gain_control(AutomaticGainControlSettings::default())
+            .automatic_gain_control(Default::default())
             .delay(Duration::from_secs_f32(0.5))
             .fade_in(Duration::from_secs_f32(2.0))
             .take_duration(Duration::from_secs(10));

examples/automatic_gain_control.rs

@@ -1,4 +1,4 @@
-use rodio::source::{AutomaticGainControlSettings, Source};
+use rodio::source::Source;
 use rodio::Decoder;
 use std::error::Error;
 use std::fs::File;
@@ -16,7 +16,7 @@ fn main() -> Result<(), Box<dyn Error>> {
     let source = Decoder::try_from(file)?;
 
     // Apply automatic gain control to the source
-    let agc_source = source.automatic_gain_control(AutomaticGainControlSettings::default());
+    let agc_source = source.automatic_gain_control(Default::default());
 
     // Make it so that the source checks if automatic gain control should be
     // enabled or disabled every 5 milliseconds. We must clone `agc_enabled`,

examples/limit_settings.rs

@@ -4,6 +4,7 @@
 //! to configure audio limiting parameters.
 
 use rodio::source::{LimitSettings, SineWave, Source};
+use rodio::Sample;
 use std::time::Duration;
 
 fn main() {
@@ -39,11 +40,11 @@ fn main() {
     let limited_wave = sine_wave.limit(LimitSettings::default());
 
     // Collect some samples to demonstrate
-    let samples: Vec<f32> = limited_wave.take(100).collect();
+    let samples: Vec<Sample> = limited_wave.take(100).collect();
     println!("  Generated {} limited samples", samples.len());
 
     // Show peak reduction
-    let max_sample = samples.iter().fold(0.0f32, |acc, &x| acc.max(x.abs()));
+    let max_sample: Sample = samples.iter().fold(0.0, |acc, &x| acc.max(x.abs()));
     println!("  Peak amplitude after limiting: {max_sample:.3}");
     println!();
 
@@ -56,7 +57,7 @@ fn main() {
 
     // Apply the custom settings from Example 2
     let custom_limited = sine_wave2.limit(custom_limiting);
-    let custom_samples: Vec<f32> = custom_limited.take(50).collect();
+    let custom_samples: Vec<Sample> = custom_limited.take(50).collect();
     println!(
         "  Generated {} samples with custom settings",
         custom_samples.len()
@@ -101,7 +102,7 @@ fn main() {
     println!("Example 6: Limiting with -6dB threshold");
 
     // Create a sine wave that will definitely trigger limiting
-    const AMPLITUDE: f32 = 2.5; // High amplitude to ensure limiting occurs
+    const AMPLITUDE: Sample = 2.5; // High amplitude to ensure limiting occurs
     let test_sine = SineWave::new(440.0)
         .amplify(AMPLITUDE)
         .take_duration(Duration::from_millis(100)); // 100ms = ~4410 samples
@@ -114,24 +115,24 @@ fn main() {
         .with_release(Duration::from_millis(12)); // Moderate release
 
     let limited_sine = test_sine.limit(strict_limiting.clone());
-    let test_samples: Vec<f32> = limited_sine.take(4410).collect();
+    let test_samples: Vec<Sample> = limited_sine.take(4410).collect();
 
     // Analyze peaks at different time periods
-    let early_peak = test_samples[0..500]
+    let early_peak: Sample = test_samples[0..500]
         .iter()
-        .fold(0.0f32, |acc, &x| acc.max(x.abs()));
-    let mid_peak = test_samples[1000..1500]
+        .fold(0.0, |acc, &x| acc.max(x.abs()));
+    let mid_peak: Sample = test_samples[1000..1500]
         .iter()
-        .fold(0.0f32, |acc, &x| acc.max(x.abs()));
-    let settled_peak = test_samples[2000..]
+        .fold(0.0, |acc, &x| acc.max(x.abs()));
+    let settled_peak: Sample = test_samples[2000..]
         .iter()
-        .fold(0.0f32, |acc, &x| acc.max(x.abs()));
+        .fold(0.0, |acc, &x| acc.max(x.abs()));
 
     // With -6dB threshold, ALL samples are well below 1.0!
-    let target_linear = 10.0_f32.powf(strict_limiting.threshold / 20.0);
-    let max_settled = test_samples[2000..]
+    let target_linear = (10.0 as Sample).powf(strict_limiting.threshold / 20.0);
+    let max_settled: Sample = test_samples[2000..]
         .iter()
-        .fold(0.0f32, |acc, &x| acc.max(x.abs()));
+        .fold(0.0, |acc, &x| acc.max(x.abs()));
 
     println!(
         "  {}dB threshold limiting results:",

examples/mix_multiple_sources.rs

@@ -1,9 +1,13 @@
 use rodio::mixer;
 use rodio::source::{SineWave, Source};
+use rodio::Float;
 use std::error::Error;
 use std::num::NonZero;
 use std::time::Duration;
 
+const NOTE_DURATION: Duration = Duration::from_secs(1);
+const NOTE_AMPLITUDE: Float = 0.20;
+
 fn main() -> Result<(), Box<dyn Error>> {
     // Construct a dynamic controller and mixer, stream_handle, and sink.
     let (controller, mixer) = mixer::mixer(NonZero::new(2).unwrap(), NonZero::new(44_100).unwrap());
@@ -14,17 +18,17 @@ fn main() -> Result<(), Box<dyn Error>> {
     // notes in the key of C and in octave 4: C4, or middle C on a piano,
     // E4, G4, and A4 respectively.
     let source_c = SineWave::new(261.63)
-        .take_duration(Duration::from_secs_f32(1.))
-        .amplify(0.20);
+        .take_duration(NOTE_DURATION)
+        .amplify(NOTE_AMPLITUDE);
     let source_e = SineWave::new(329.63)
-        .take_duration(Duration::from_secs_f32(1.))
-        .amplify(0.20);
+        .take_duration(NOTE_DURATION)
+        .amplify(NOTE_AMPLITUDE);
     let source_g = SineWave::new(392.0)
-        .take_duration(Duration::from_secs_f32(1.))
-        .amplify(0.20);
+        .take_duration(NOTE_DURATION)
+        .amplify(NOTE_AMPLITUDE);
     let source_a = SineWave::new(440.0)
-        .take_duration(Duration::from_secs_f32(1.))
-        .amplify(0.20);
+        .take_duration(NOTE_DURATION)
+        .amplify(NOTE_AMPLITUDE);
 
     // Add sources C, E, G, and A to the mixer controller.
     controller.add(source_c);

examples/noise_generator.rs

@@ -3,9 +3,11 @@
 
 use std::{error::Error, thread::sleep, time::Duration};
 
-use rodio::source::{
-    noise::{Blue, Brownian, Pink, Velvet, Violet, WhiteGaussian, WhiteTriangular, WhiteUniform},
-    Source,
+use rodio::{
+    source::noise::{
+        Blue, Brownian, Pink, Velvet, Violet, WhiteGaussian, WhiteTriangular, WhiteUniform,
+    },
+    Sample, Source,
 };
 
 fn main() -> Result<(), Box<dyn Error>> {
@@ -74,7 +76,7 @@ fn main() -> Result<(), Box<dyn Error>> {
 /// Helper function to play a noise type with description
 fn play_noise<S>(stream_handle: &rodio::OutputStream, source: S, name: &str, description: &str)
 where
-    S: Source<Item = f32> + Send + 'static,
+    S: Source<Item = Sample> + Send + 'static,
 {
     println!("{} Noise", name);
     println!("   Application: {}", description);