refactor: clarify docs and clean up tests

Author: roderickvd

benches/effects.rs

@@ -57,7 +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(Default::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();

src/buffer.rs

@@ -104,8 +104,9 @@ impl Source for SamplesBuffer {
         // sample directly.
 
         let curr_channel = self.pos % self.channels().get() as usize;
-        let new_pos =
-            duration_to_float(pos) * self.sample_rate().get() as Float * self.channels().get() as Float;
+        let new_pos = duration_to_float(pos)
+            * self.sample_rate().get() as Float
+            * self.channels().get() as Float;
         // saturate pos at the end of the source
         let new_pos = new_pos as usize;
         let new_pos = new_pos.min(self.data.len());

src/math.rs

@@ -9,9 +9,9 @@ pub(crate) const NANOS_PER_SEC: u64 = 1_000_000_000;
 // Re-export float constants with appropriate precision for the Float type.
 // This centralizes all cfg gating for constants in one place.
 #[cfg(not(feature = "64bit"))]
-pub use std::f32::consts::{E, LN_2, LN_10, LOG2_10, LOG2_E, LOG10_2, LOG10_E, PI, TAU};
+pub use std::f32::consts::{E, LN_10, LN_2, LOG10_2, LOG10_E, LOG2_10, LOG2_E, PI, TAU};
 #[cfg(feature = "64bit")]
-pub use std::f64::consts::{E, LN_2, LN_10, LOG2_10, LOG2_E, LOG10_2, LOG10_E, PI, TAU};
+pub use std::f64::consts::{E, LN_10, LN_2, LOG10_2, LOG10_E, LOG2_10, LOG2_E, PI, TAU};
 
 /// Linear interpolation between two samples.
 ///
@@ -255,21 +255,21 @@ mod test {
     #[test]
     fn convert_linear_to_decibels() {
         // Test the inverse conversion function using the same reference data
-        for (wikipedia_db, linear) in DECIBELS_LINEAR_TABLE {
+        for (expected_db, linear) in DECIBELS_LINEAR_TABLE {
             let actual_db = linear_to_db(linear);
 
             // Sanity check: ensure we're reasonably close to the expected dB value from the table
             // This accounts for rounding in both the linear and dB reference values
-            let magnitude_ratio = if wikipedia_db.abs() > 10.0 * Float::EPSILON {
-                actual_db / wikipedia_db
+            let magnitude_ratio = if expected_db.abs() > 10.0 * Float::EPSILON {
+                actual_db / expected_db
             } else {
                 1.0 // Skip ratio check for values very close to 0 dB
             };
 
-            if wikipedia_db.abs() > 10.0 * Float::EPSILON {
+            if expected_db.abs() > 10.0 * Float::EPSILON {
                 assert!(
                     magnitude_ratio > 0.99 && magnitude_ratio < 1.01,
-                    "Result differs significantly from table reference for linear {linear}: expected {wikipedia_db}dB, got {actual_db}dB, ratio: {magnitude_ratio:.4}"
+                    "Result differs significantly from table reference for linear {linear}: expected {expected_db}dB, got {actual_db}dB, ratio: {magnitude_ratio:.4}"
                 );
             }
         }

src/microphone/config.rs

@@ -12,7 +12,7 @@ pub struct InputConfig {
     /// The buffersize, see a thorough explanation in MicrophoneBuilder::with_buffer_size
     pub buffer_size: cpal::BufferSize,
     /// The sample format used by the microphone.
-    /// Note we will always convert it to f32
+    /// Note we will always convert it to `Sample`
     pub sample_format: cpal::SampleFormat,
 }
 impl InputConfig {

src/source/linear_ramp.rs

@@ -90,9 +90,8 @@ where
         }
 
         if self.sample_idx.is_multiple_of(self.channels().get() as u64) {
-            let sample_duration = Duration::from_nanos(
-                NANOS_PER_SEC / self.input.sample_rate().get() as u64
-            );
+            let sample_duration =
+                Duration::from_nanos(NANOS_PER_SEC / self.input.sample_rate().get() as u64);
             self.elapsed += sample_duration;
         }
 

src/source/noise.rs

@@ -154,7 +154,7 @@ impl<R: Rng> WhiteUniform<R> {
     /// Get the standard deviation of the uniform distribution.
     ///
     /// For uniform distribution [-1.0, 1.0], std_dev = √(1/3) ≈ 0.5774.
-    pub fn std_dev(&self) -> f32 {
+    pub fn std_dev(&self) -> Sample {
         UNIFORM_VARIANCE.sqrt()
     }
 }
@@ -209,8 +209,8 @@ impl<R: Rng> WhiteTriangular<R> {
     /// Get the standard deviation of the triangular distribution.
     ///
     /// For triangular distribution [-1.0, 1.0] with mode 0.0, std_dev = 2/√6 ≈ 0.8165.
-    pub fn std_dev(&self) -> f32 {
-        2.0 / (6.0_f32).sqrt()
+    pub fn std_dev(&self) -> Sample {
+        2.0 / Sample::sqrt(6.0)
     }
 }
 
@@ -416,7 +416,7 @@ const VELVET_DEFAULT_DENSITY: NonZero<usize> = nz!(2000);
 /// Variance of uniform distribution [-1.0, 1.0].
 ///
 /// For uniform distribution U(-1, 1), the variance is (b-a)²/12 = 4/12 = 1/3.
-const UNIFORM_VARIANCE: f32 = 1.0 / 3.0;
+const UNIFORM_VARIANCE: Sample = 1.0 / 3.0;
 
 /// Pink noise generator - sounds much more natural than white noise.
 ///
@@ -645,8 +645,7 @@ where
         // Center frequency is set to 5Hz, which provides good behavior
         // while preventing excessive low-frequency buildup across common sample rates.
         let center_freq_hz = 5.0;
-        let leak_factor =
-            1.0 - ((2.0 * PI * center_freq_hz) / sample_rate.get() as Float);
+        let leak_factor = 1.0 - ((2.0 * PI * center_freq_hz) / sample_rate.get() as Float);
 
         // Calculate the scaling factor to normalize output based on leak factor.
         // This ensures consistent output level regardless of the leak factor value.
@@ -1044,15 +1043,6 @@ mod tests {
             near_zero_count > total_samples / 2,
             "Triangular distribution should favor values near zero"
         );
-
-        // Test std_dev method
-        let generator = WhiteTriangular::new(TEST_SAMPLE_RATE);
-        let expected_std_dev = 2.0 / (6.0_f32).sqrt();
-        assert!(
-            (generator.std_dev() - expected_std_dev).abs() < f32::EPSILON,
-            "Triangular std_dev should be 2/sqrt(6) ≈ 0.8165, got {}",
-            generator.std_dev()
-        );
     }
 
     #[test]

src/source/signal_generator.rs

@@ -1,8 +1,7 @@
 //! Generator sources for various periodic test waveforms.
 //!
 //! This module provides several periodic, deterministic waveforms for testing other sources and
-//! for simple additive sound synthesis. Every source is monoaural and in the codomain [-1.0f32,
-//! 1.0f32].
+//! for simple additive sound synthesis. Every source is monoaural and in the codomain [-1.0, 1.0].
 //!
 //! # Example
 //!
@@ -176,7 +175,7 @@ mod tests {
 
     #[test]
     fn square() {
-        let mut wf = SignalGenerator::new(nz!(2000), 500.0f32, Function::Square);
+        let mut wf = SignalGenerator::new(nz!(2000), 500.0, Function::Square);
         assert_eq!(wf.next(), Some(1.0));
         assert_eq!(wf.next(), Some(1.0));
         assert_eq!(wf.next(), Some(-1.0));
@@ -189,7 +188,7 @@ mod tests {
 
     #[test]
     fn triangle() {
-        let mut wf = SignalGenerator::new(nz!(8000), 1000.0f32, Function::Triangle);
+        let mut wf = SignalGenerator::new(nz!(8000), 1000.0, Function::Triangle);
         assert_eq!(wf.next(), Some(-1.0));
         assert_eq!(wf.next(), Some(-0.5));
         assert_eq!(wf.next(), Some(0.0));
@@ -210,7 +209,7 @@ mod tests {
 
     #[test]
     fn saw() {
-        let mut wf = SignalGenerator::new(nz!(200), 50.0f32, Function::Sawtooth);
+        let mut wf = SignalGenerator::new(nz!(200), 50.0, Function::Sawtooth);
         assert_eq!(wf.next(), Some(0.0));
         assert_eq!(wf.next(), Some(0.5));
         assert_eq!(wf.next(), Some(-1.0));

src/source/skip.rs

@@ -169,8 +169,8 @@ mod tests {
     use crate::buffer::SamplesBuffer;
     use crate::common::{ChannelCount, SampleRate};
     use crate::math::nz;
-    use crate::Sample;
     use crate::source::Source;
+    use crate::Sample;
     use dasp_sample::Sample as DaspSample;
 
     fn test_skip_duration_samples_left(

src/wav_output.rs

@@ -1,6 +1,7 @@
 use crate::common::assert_error_traits;
 use crate::Sample;
 use crate::Source;
+use dasp_sample::Sample as DaspSample;
 use hound::{SampleFormat, WavSpec};
 use std::io::{self, Write};
 use std::path;
@@ -77,7 +78,7 @@ pub fn wav_to_writer(
         let whole_frames = WholeFrames::new(source);
         for sample in whole_frames {
             writer
-                .write_sample(sample)
+                .write_sample(sample.to_sample::<f32>())
                 .map_err(Arc::new)
                 .map_err(ToWavError::Writing)?;
         }
@@ -131,6 +132,7 @@ impl<I: Iterator<Item = Sample>> Iterator for WholeFrames<I> {
 mod test {
     use super::wav_to_file;
     use crate::{Sample, Source};
+    use dasp_sample::Sample as DaspSample;
     use std::io::BufReader;
     use std::time::Duration;
 
@@ -152,11 +154,20 @@ mod test {
         assert_eq!(reference.sample_rate().get(), reader.spec().sample_rate);
         assert_eq!(reference.channels().get(), reader.spec().channels);
 
-        let actual_samples: Vec<Sample> = reader.samples::<Sample>().map(|x| x.unwrap()).collect();
-        let expected_samples: Vec<Sample> = reference.collect();
-        assert!(
-            expected_samples == actual_samples,
-            "wav samples do not match the source"
+        // WAV files always use f32 samples (hound limitation)
+        let actual_samples: Vec<f32> = reader.samples::<f32>().map(|x| x.unwrap()).collect();
+        let expected_samples: Vec<f32> = reference
+            .into_iter()
+            .map(|s| s.to_sample::<f32>())
+            .collect();
+
+        assert_eq!(
+            actual_samples.len(),
+            expected_samples.len(),
+            "sample counts should match"
         );
+        for (actual, expected) in actual_samples.iter().zip(expected_samples.iter()) {
+            assert_eq!(actual, expected, "wav samples do not match the source");
+        }
     }
 }

tests/channel_volume.rs

@@ -27,10 +27,7 @@ fn channel_volume_with_queue() {
     assert_output_only_on_first_two_channels(queue, 6);
 }
 
-fn assert_output_only_on_first_two_channels(
-    source: impl Source<Item = Sample>,
-    channels: usize,
-) {
+fn assert_output_only_on_first_two_channels(source: impl Source<Item = Sample>, channels: usize) {
     let mut frame_number = 0;
     let mut samples_in_frame = Vec::new();