From f6698d6c14e7d2a39fe50b2539617bd9faa03066 Mon Sep 17 00:00:00 2001
From: Roderick van Domburg <roderick@vandomburg.net>
Date: Fri, 3 Jan 2025 11:40:00 +0100
Subject: [PATCH 01/18] Switch decoder output from i16 to f32 samples

This change improves audio quality in two ways:
1. Having decoders output `f32` samples directly instead of converting to `i16`
2. Properly handling high bit-depth FLAC and WAV files (20/24/32-bit) without downsampling

Benefits include:
- Eliminates unnecessary quantization error from `i16` conversion
- Better matches the rodio pipeline which already uses `f32` internally
- Preserves greater-than-i16 precision from formats like WAV and FLAC
- More natural for decoders like Vorbis/MP3 that operate in floating point

Breaking change - decoder output type changes from `i16` to `f32`.

Changes:
- Updated decoders to output `f32`
- Updated `wav_test.rs` and `flac_test.rs` assertions to check for non-zero `f32` samples
- Updated benchmarks to use `f32` samples and removed unnecessary `f32` conversions

Fixes RustAudio/rodio#364
---
 CHANGELOG.md             |  1 +
 benches/conversions.rs   |  2 +-
 benches/resampler.rs     |  8 ++--
 benches/shared.rs        |  2 +-
 src/decoder/flac.rs      | 21 ++++++----
 src/decoder/mod.rs       | 13 +++---
 src/decoder/mp3.rs       |  7 ++--
 src/decoder/symphonia.rs | 12 +++---
 src/decoder/vorbis.rs    | 38 +++++++++++------
 src/decoder/wav.rs       | 89 +++++++++++++++-------------------------
 tests/flac_test.rs       |  4 +-
 tests/mp4a_test.rs       |  2 +-
 tests/seek.rs            |  4 +-
 tests/wav_test.rs        | 12 +++---
 14 files changed, 109 insertions(+), 106 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ea4de731..4fcdf718 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -26,6 +26,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Breaking: `Sink::try_new` renamed to `connect_new` and does not return error anymore.
             `Sink::new_idle` was renamed to `new`.
 - Breaking: In the `Source` trait, the method `current_frame_len()` was renamed to `current_span_len()`.
+- Breaking: `Decoder` now outputs `f32` samples instead of `i16`.
 - The term 'frame' was renamed to 'span' in the crate and documentation.
 
 ### Fixed
diff --git a/benches/conversions.rs b/benches/conversions.rs
index 9bebb974..1610191b 100644
--- a/benches/conversions.rs
+++ b/benches/conversions.rs
@@ -10,7 +10,7 @@ fn main() {
 }
 
 #[divan::bench(types = [i16, u16, f32])]
-fn from_i16_to<T: rodio::Sample + FromSample<i16>>(bencher: Bencher) {
+fn from_f32_to<T: rodio::Sample + FromSample<f32>>(bencher: Bencher) {
     bencher
         .with_inputs(|| TestSource::music_wav())
         .bench_values(|source| {
diff --git a/benches/resampler.rs b/benches/resampler.rs
index 22ddbf15..7d4609fa 100644
--- a/benches/resampler.rs
+++ b/benches/resampler.rs
@@ -13,11 +13,11 @@ fn main() {
 fn no_resampling(bencher: Bencher) {
     bencher
         .with_inputs(|| {
-            let source = TestSource::<i16>::music_wav();
+            let source = TestSource::<f32>::music_wav();
             (source.channels(), source.sample_rate(), source)
         })
         .bench_values(|(channels, sample_rate, source)| {
-            UniformSourceIterator::<_, i16>::new(source, channels, sample_rate)
+            UniformSourceIterator::<_, f32>::new(source, channels, sample_rate)
                 .for_each(divan::black_box_drop)
         })
 }
@@ -32,11 +32,11 @@ const COMMON_SAMPLE_RATES: [u32; 12] = [
 fn resample_to(bencher: Bencher, target_sample_rate: u32) {
     bencher
         .with_inputs(|| {
-            let source = TestSource::<i16>::music_wav();
+            let source = TestSource::<f32>::music_wav();
             (source.channels(), source)
         })
         .bench_values(|(channels, source)| {
-            UniformSourceIterator::<_, i16>::new(source, channels, target_sample_rate)
+            UniformSourceIterator::<_, f32>::new(source, channels, target_sample_rate)
                 .for_each(divan::black_box_drop)
         })
 }
diff --git a/benches/shared.rs b/benches/shared.rs
index 8cab969d..a99e9ad9 100644
--- a/benches/shared.rs
+++ b/benches/shared.rs
@@ -43,7 +43,7 @@ impl<T: rodio::Sample> Source for TestSource<T> {
     }
 }
 
-impl TestSource<i16> {
+impl TestSource<f32> {
     pub fn music_wav() -> Self {
         let data = include_bytes!("../assets/music.wav");
         let cursor = Cursor::new(data);
diff --git a/src/decoder/flac.rs b/src/decoder/flac.rs
index 9773f9d8..83ab235a 100644
--- a/src/decoder/flac.rs
+++ b/src/decoder/flac.rs
@@ -1,4 +1,3 @@
-use std::cmp::Ordering;
 use std::io::{Read, Seek, SeekFrom};
 use std::mem;
 use std::time::Duration;
@@ -7,7 +6,11 @@ use crate::source::SeekError;
 use crate::Source;
 
 use crate::common::{ChannelCount, SampleRate};
+
 use claxon::FlacReader;
+use cpal::Sample;
+
+use super::DecoderFormat;
 
 /// Decoder for the Flac format.
 pub struct FlacDecoder<R>
@@ -94,10 +97,10 @@ impl<R> Iterator for FlacDecoder<R>
 where
     R: Read + Seek,
 {
-    type Item = i16;
+    type Item = DecoderFormat;
 
     #[inline]
-    fn next(&mut self) -> Option<i16> {
+    fn next(&mut self) -> Option<Self::Item> {
         loop {
             if self.current_block_off < self.current_block.len() {
                 // Read from current block.
@@ -106,10 +109,14 @@ where
                     + self.current_block_off / self.channels as usize;
                 let raw_val = self.current_block[real_offset];
                 self.current_block_off += 1;
-                let real_val = match self.bits_per_sample.cmp(&16) {
-                    Ordering::Less => (raw_val << (16 - self.bits_per_sample)) as i16,
-                    Ordering::Equal => raw_val as i16,
-                    Ordering::Greater => (raw_val >> (self.bits_per_sample - 16)) as i16,
+                let real_val = match self.bits_per_sample {
+                    8 => (raw_val as i8).to_sample::<Self::Item>(),
+                    12 => (raw_val << 20).to_sample::<Self::Item>(),
+                    16 => (raw_val as i16).to_sample::<Self::Item>(),
+                    20 => (raw_val << 12).to_sample::<Self::Item>(),
+                    24 => (raw_val << 8).to_sample::<Self::Item>(),
+                    32 => raw_val.to_sample::<Self::Item>(),
+                    _ => panic!("Unimplemented flac spec: {} bits", self.bits_per_sample),
                 };
                 return Some(real_val);
             }
diff --git a/src/decoder/mod.rs b/src/decoder/mod.rs
index ad1e61d7..74dbb7eb 100644
--- a/src/decoder/mod.rs
+++ b/src/decoder/mod.rs
@@ -31,6 +31,9 @@ mod vorbis;
 #[cfg(all(feature = "wav", not(feature = "symphonia-wav")))]
 mod wav;
 
+/// Output format of the decoders.
+pub type DecoderFormat = f32;
+
 /// Source of audio samples from decoding a file.
 ///
 /// Supports MP3, WAV, Vorbis and Flac.
@@ -68,7 +71,7 @@ where
 
 impl<R: Read + Seek> DecoderImpl<R> {
     #[inline]
-    fn next(&mut self) -> Option<i16> {
+    fn next(&mut self) -> Option<DecoderFormat> {
         match self {
             #[cfg(all(feature = "wav", not(feature = "symphonia-wav")))]
             DecoderImpl::Wav(source) => source.next(),
@@ -396,10 +399,10 @@ impl<R> Iterator for Decoder<R>
 where
     R: Read + Seek,
 {
-    type Item = i16;
+    type Item = DecoderFormat;
 
     #[inline]
-    fn next(&mut self) -> Option<i16> {
+    fn next(&mut self) -> Option<Self::Item> {
         self.0.next()
     }
 
@@ -442,10 +445,10 @@ impl<R> Iterator for LoopedDecoder<R>
 where
     R: Read + Seek,
 {
-    type Item = i16;
+    type Item = DecoderFormat;
 
     #[inline]
-    fn next(&mut self) -> Option<i16> {
+    fn next(&mut self) -> Option<Self::Item> {
         if let Some(sample) = self.0.next() {
             Some(sample)
         } else {
diff --git a/src/decoder/mp3.rs b/src/decoder/mp3.rs
index f85605c7..99d69a63 100644
--- a/src/decoder/mp3.rs
+++ b/src/decoder/mp3.rs
@@ -1,6 +1,7 @@
 use std::io::{Read, Seek, SeekFrom};
 use std::time::Duration;
 
+use super::DecoderFormat;
 use crate::source::SeekError;
 use crate::Source;
 
@@ -34,7 +35,7 @@ where
         // .expect("should be able to allocate memory, perform IO");
         // let current_span = decoder.decode_frame()
         let current_span = decoder.next_frame()
-            // the reader makes enough data available therefore 
+            // the reader makes enough data available therefore
             // if we crash here the invariant broken is:
             .expect("data should not corrupt");
 
@@ -92,9 +93,9 @@ impl<R> Iterator for Mp3Decoder<R>
 where
     R: Read + Seek,
 {
-    type Item = i16;
+    type Item = DecoderFormat;
 
-    fn next(&mut self) -> Option<i16> {
+    fn next(&mut self) -> Option<Self::Item> {
         if self.current_span_offset == self.current_span_len().unwrap() {
             if let Ok(span) = self.decoder.next_frame() {
                 // if let Ok(span) = self.decoder.decode_frame() {
diff --git a/src/decoder/symphonia.rs b/src/decoder/symphonia.rs
index c466e6ee..9b010d11 100644
--- a/src/decoder/symphonia.rs
+++ b/src/decoder/symphonia.rs
@@ -14,7 +14,7 @@ use symphonia::{
     default::get_probe,
 };
 
-use super::DecoderError;
+use super::{DecoderError, DecoderFormat};
 use crate::common::{ChannelCount, SampleRate};
 use crate::{source, Source};
 
@@ -28,7 +28,7 @@ pub(crate) struct SymphoniaDecoder {
     current_span_offset: usize,
     format: Box<dyn FormatReader>,
     total_duration: Option<Time>,
-    buffer: SampleBuffer<i16>,
+    buffer: SampleBuffer<DecoderFormat>,
     spec: SignalSpec,
 }
 
@@ -144,9 +144,9 @@ impl SymphoniaDecoder {
     }
 
     #[inline]
-    fn get_buffer(decoded: AudioBufferRef, spec: &SignalSpec) -> SampleBuffer<i16> {
+    fn get_buffer(decoded: AudioBufferRef, spec: &SignalSpec) -> SampleBuffer<DecoderFormat> {
         let duration = units::Duration::from(decoded.capacity() as u64);
-        let mut buffer = SampleBuffer::<i16>::new(duration, *spec);
+        let mut buffer = SampleBuffer::<DecoderFormat>::new(duration, *spec);
         buffer.copy_interleaved_ref(decoded);
         buffer
     }
@@ -316,10 +316,10 @@ fn time_to_duration(time: Time) -> Duration {
 }
 
 impl Iterator for SymphoniaDecoder {
-    type Item = i16;
+    type Item = DecoderFormat;
 
     #[inline]
-    fn next(&mut self) -> Option<i16> {
+    fn next(&mut self) -> Option<Self::Item> {
         if self.current_span_offset >= self.buffer.len() {
             let packet = self.format.next_packet().ok()?;
             let mut decoded = self.decoder.decode(&packet);
diff --git a/src/decoder/vorbis.rs b/src/decoder/vorbis.rs
index 2e936171..253199ae 100644
--- a/src/decoder/vorbis.rs
+++ b/src/decoder/vorbis.rs
@@ -6,6 +6,9 @@ use crate::Source;
 
 use crate::common::{ChannelCount, SampleRate};
 use lewton::inside_ogg::OggStreamReader;
+use lewton::samples::InterleavedSamples;
+
+use super::DecoderFormat;
 
 /// Decoder for an OGG file that contains Vorbis sound format.
 pub struct VorbisDecoder<R>
@@ -13,7 +16,7 @@ where
     R: Read + Seek,
 {
     stream_reader: OggStreamReader<R>,
-    current_data: Vec<i16>,
+    current_data: Vec<DecoderFormat>,
     next: usize,
 }
 
@@ -31,15 +34,18 @@ where
         Ok(Self::from_stream_reader(stream_reader))
     }
     pub fn from_stream_reader(mut stream_reader: OggStreamReader<R>) -> Self {
-        let mut data = match stream_reader.read_dec_packet_itl() {
-            Ok(Some(d)) => d,
-            _ => Vec::new(),
-        };
+        let mut data =
+            match stream_reader.read_dec_packet_generic::<InterleavedSamples<DecoderFormat>>() {
+                Ok(Some(d)) => d.samples,
+                _ => Vec::new(),
+            };
 
         // The first packet is always empty, therefore
         // we need to read the second frame to get some data
-        if let Ok(Some(mut d)) = stream_reader.read_dec_packet_itl() {
-            data.append(&mut d);
+        if let Ok(Some(mut d)) =
+            stream_reader.read_dec_packet_generic::<InterleavedSamples<DecoderFormat>>()
+        {
+            data.append(&mut d.samples);
         }
 
         VorbisDecoder {
@@ -98,22 +104,28 @@ impl<R> Iterator for VorbisDecoder<R>
 where
     R: Read + Seek,
 {
-    type Item = i16;
+    type Item = DecoderFormat;
 
     #[inline]
-    fn next(&mut self) -> Option<i16> {
+    fn next(&mut self) -> Option<Self::Item> {
         if let Some(sample) = self.current_data.get(self.next).copied() {
             self.next += 1;
             if self.current_data.is_empty() {
-                if let Ok(Some(data)) = self.stream_reader.read_dec_packet_itl() {
-                    self.current_data = data;
+                if let Ok(Some(data)) = self
+                    .stream_reader
+                    .read_dec_packet_generic::<InterleavedSamples<DecoderFormat>>()
+                {
+                    self.current_data = data.samples;
                     self.next = 0;
                 }
             }
             Some(sample)
         } else {
-            if let Ok(Some(data)) = self.stream_reader.read_dec_packet_itl() {
-                self.current_data = data;
+            if let Ok(Some(data)) = self
+                .stream_reader
+                .read_dec_packet_generic::<InterleavedSamples<DecoderFormat>>()
+            {
+                self.current_data = data.samples;
                 self.next = 0;
             }
             let sample = self.current_data.get(self.next).copied();
diff --git a/src/decoder/wav.rs b/src/decoder/wav.rs
index 76c27150..91e2ae1b 100644
--- a/src/decoder/wav.rs
+++ b/src/decoder/wav.rs
@@ -5,8 +5,12 @@ use crate::source::SeekError;
 use crate::Source;
 
 use crate::common::{ChannelCount, SampleRate};
+
+use cpal::Sample;
 use hound::{SampleFormat, WavReader};
 
+use super::DecoderFormat;
+
 /// Decoder for the WAV format.
 pub struct WavDecoder<R>
 where
@@ -65,32 +69,38 @@ impl<R> Iterator for SamplesIterator<R>
 where
     R: Read + Seek,
 {
-    type Item = i16;
+    type Item = DecoderFormat;
 
     #[inline]
-    fn next(&mut self) -> Option<i16> {
+    fn next(&mut self) -> Option<Self::Item> {
+        self.samples_read += 1;
         let spec = self.reader.spec();
         match (spec.sample_format, spec.bits_per_sample) {
-            (SampleFormat::Float, 32) => self.reader.samples().next().map(|value| {
-                self.samples_read += 1;
-                f32_to_i16(value.unwrap_or(0.0))
-            }),
-            (SampleFormat::Int, 8) => self.reader.samples().next().map(|value| {
-                self.samples_read += 1;
-                i8_to_i16(value.unwrap_or(0))
-            }),
-            (SampleFormat::Int, 16) => self.reader.samples().next().map(|value| {
-                self.samples_read += 1;
-                value.unwrap_or(0)
-            }),
-            (SampleFormat::Int, 24) => self.reader.samples().next().map(|value| {
-                self.samples_read += 1;
-                i24_to_i16(value.unwrap_or(0))
-            }),
-            (SampleFormat::Int, 32) => self.reader.samples().next().map(|value| {
-                self.samples_read += 1;
-                i32_to_i16(value.unwrap_or(0))
-            }),
+            (SampleFormat::Float, 32) => self
+                .reader
+                .samples()
+                .next()
+                .map(|value| value.unwrap_or(0.0)),
+            (SampleFormat::Int, 8) => self
+                .reader
+                .samples()
+                .next()
+                .map(|value| (value.unwrap_or(0) as i8).to_sample::<Self::Item>()),
+            (SampleFormat::Int, 16) => self
+                .reader
+                .samples()
+                .next()
+                .map(|value| (value.unwrap_or(0) as i16).to_sample::<Self::Item>()),
+            (SampleFormat::Int, 24) => self
+                .reader
+                .samples()
+                .next()
+                .map(|value| (value.unwrap_or(0) << 8).to_sample::<Self::Item>()),
+            (SampleFormat::Int, 32) => self
+                .reader
+                .samples()
+                .next()
+                .map(|value| value.unwrap_or(0).to_sample::<Self::Item>()),
             (sample_format, bits_per_sample) => {
                 panic!("Unimplemented wav spec: {sample_format:?}, {bits_per_sample}")
             }
@@ -159,10 +169,10 @@ impl<R> Iterator for WavDecoder<R>
 where
     R: Read + Seek,
 {
-    type Item = i16;
+    type Item = DecoderFormat;
 
     #[inline]
-    fn next(&mut self) -> Option<i16> {
+    fn next(&mut self) -> Option<Self::Item> {
         self.reader.next()
     }
 
@@ -189,34 +199,3 @@ where
     data.seek(SeekFrom::Start(stream_pos)).unwrap();
     true
 }
-
-/// Returns a 32 bit WAV float as an i16. WAV floats are typically in the range of
-/// [-1.0, 1.0] while i16s are in the range [-32768, 32767]. Note that this
-/// function definitely causes precision loss but hopefully this isn't too
-/// audiable when actually playing?
-fn f32_to_i16(f: f32) -> i16 {
-    // prefer to clip the input rather than be excessively loud.
-    (f.clamp(-1.0, 1.0) * i16::MAX as f32) as i16
-}
-
-/// Returns an 8-bit WAV int as an i16. This scales the sample value by a factor
-/// of 256.
-fn i8_to_i16(i: i8) -> i16 {
-    i as i16 * 256
-}
-
-/// Returns a 24 bit WAV int as an i16. Note that this is a 24 bit integer, not a
-/// 32 bit one. 24 bit ints are in the range [−8,388,608, 8,388,607] while i16s
-/// are in the range [-32768, 32767]. Note that this function definitely causes
-/// precision loss but hopefully this isn't too audiable when actually playing?
-fn i24_to_i16(i: i32) -> i16 {
-    (i >> 8) as i16
-}
-
-/// Returns a 32 bit WAV int as an i16. 32 bit ints are in the range
-/// [-2,147,483,648, 2,147,483,647] while i16s are in the range [-32768, 32767].
-/// Note that this function definitely causes precision loss but hopefully this
-/// isn't too audiable when actually playing?
-fn i32_to_i16(i: i32) -> i16 {
-    (i >> 16) as i16
-}
diff --git a/tests/flac_test.rs b/tests/flac_test.rs
index 3f0e7169..72d804f0 100644
--- a/tests/flac_test.rs
+++ b/tests/flac_test.rs
@@ -12,7 +12,7 @@ fn test_flac_encodings() {
     let file = std::fs::File::open("assets/audacity16bit_level5.flac").unwrap();
     let mut decoder = rodio::Decoder::new(BufReader::new(file)).unwrap();
     // File is not just silence
-    assert!(decoder.any(|x| x != 0));
+    assert!(decoder.any(|x| x != 0.0));
     // Symphonia does not expose functionality to get the duration so this check must be disabled
     #[cfg(all(feature = "flac", not(feature = "symphonia-flac")))]
     assert_eq!(decoder.total_duration(), Some(Duration::from_secs(3))); // duration is calculated correctly
@@ -21,7 +21,7 @@ fn test_flac_encodings() {
     for level in &[0, 5, 8] {
         let file = std::fs::File::open(format!("assets/audacity24bit_level{level}.flac")).unwrap();
         let mut decoder = rodio::Decoder::new(BufReader::new(file)).unwrap();
-        assert!(decoder.any(|x| x != 0));
+        assert!(decoder.any(|x| x != 0.0));
         #[cfg(all(feature = "flac", not(feature = "symphonia-flac")))]
         assert_eq!(decoder.total_duration(), Some(Duration::from_secs(3)));
     }
diff --git a/tests/mp4a_test.rs b/tests/mp4a_test.rs
index 35213289..96b17c07 100644
--- a/tests/mp4a_test.rs
+++ b/tests/mp4a_test.rs
@@ -10,5 +10,5 @@ fn test_mp4a_encodings() {
     // http://creativecommons.org/licenses/by/3.0/
     let file = std::fs::File::open("assets/monkeys.mp4a").unwrap();
     let mut decoder = rodio::Decoder::new(BufReader::new(file)).unwrap();
-    assert!(decoder.any(|x| x != 0)); // Assert not all zeros
+    assert!(decoder.any(|x| x != 0.0)); // Assert not all zeros
 }
diff --git a/tests/seek.rs b/tests/seek.rs
index ff401219..59738ded 100644
--- a/tests/seek.rs
+++ b/tests/seek.rs
@@ -145,7 +145,7 @@ fn seek_does_not_break_channel_order(
         let channel0 = 0 + channel_offset;
         assert!(
             is_silent(&samples, source.channels(), channel0),
-            "channel0 should be silent, 
+            "channel0 should be silent,
     channel0 starts at idx: {channel0}
     seek: {beep_start:?} + {offset:?}
     samples: {samples:?}"
@@ -153,7 +153,7 @@ fn seek_does_not_break_channel_order(
         let channel1 = (1 + channel_offset) % 2;
         assert!(
             !is_silent(&samples, source.channels(), channel1),
-            "channel1 should not be silent, 
+            "channel1 should not be silent,
     channel1; starts at idx: {channel1}
     seek: {beep_start:?} + {offset:?}
     samples: {samples:?}"
diff --git a/tests/wav_test.rs b/tests/wav_test.rs
index bcb34804..5a8770ad 100644
--- a/tests/wav_test.rs
+++ b/tests/wav_test.rs
@@ -6,30 +6,30 @@ fn test_wav_encodings() {
     // 16 bit wav file exported from Audacity (1 channel)
     let file = std::fs::File::open("assets/audacity16bit.wav").unwrap();
     let mut decoder = rodio::Decoder::new(BufReader::new(file)).unwrap();
-    assert!(decoder.any(|x| x != 0)); // Assert not all zeros
+    assert!(decoder.any(|x| x != 0.0)); // Assert not all zeros
 
     // 16 bit wav file exported from LMMS (2 channels)
     let file = std::fs::File::open("assets/lmms16bit.wav").unwrap();
     let mut decoder = rodio::Decoder::new(BufReader::new(file)).unwrap();
-    assert!(decoder.any(|x| x != 0));
+    assert!(decoder.any(|x| x != 0.0));
 
     // 24 bit wav file exported from LMMS (2 channels)
     let file = std::fs::File::open("assets/lmms24bit.wav").unwrap();
     let mut decoder = rodio::Decoder::new(BufReader::new(file)).unwrap();
-    assert!(decoder.any(|x| x != 0));
+    assert!(decoder.any(|x| x != 0.0));
 
     // 32 bit wav file exported from Audacity (1 channel)
     let file = std::fs::File::open("assets/audacity32bit.wav").unwrap();
     let mut decoder = rodio::Decoder::new(BufReader::new(file)).unwrap();
-    assert!(decoder.any(|x| x != 0));
+    assert!(decoder.any(|x| x != 0.0));
 
     // 32 bit wav file exported from LMMS (2 channels)
     let file = std::fs::File::open("assets/lmms32bit.wav").unwrap();
     let mut decoder = rodio::Decoder::new(BufReader::new(file)).unwrap();
-    assert!(decoder.any(|x| x != 0));
+    assert!(decoder.any(|x| x != 0.0));
 
     // 32 bit signed integer wav file exported from Audacity (1 channel).
     let file = std::fs::File::open("assets/audacity32bit_int.wav").unwrap();
     let mut decoder = rodio::Decoder::new(BufReader::new(file)).unwrap();
-    assert!(decoder.any(|x| x != 0));
+    assert!(decoder.any(|x| x != 0.0));
 }

From d3a42b5b886240b02fbaeda864c7437c1daa5e69 Mon Sep 17 00:00:00 2001
From: Roderick van Domburg <roderick@vandomburg.net>
Date: Mon, 6 Jan 2025 00:38:23 +0100
Subject: [PATCH 02/18] Address review comments, unifying sample handling
 across audio decoders

Refactoring of sample type handling and conversion:
- Rename DecoderFormat to DecoderSample for clarity
- Use dasp_sample's Sample and ToSample traits consistently
- Implement default Sample trait methods using dasp_sample
- Standardize bit depth handling across decoders:
  - FLAC & WAV: handle unsupported samples gracefully
  - Unified approach for 8/12/16/20/24/32-bit across formats
- Clean up redundant Sample implementations using trait defaults

This change makes sample handling more consistent across different
audio formats while improving handling of edge cases in bit depths.
---
 src/conversions/sample.rs | 64 +++++-----------------------
 src/decoder/flac.rs       | 28 +++++++-----
 src/decoder/mod.rs        |  8 ++--
 src/decoder/symphonia.rs  | 10 ++---
 src/decoder/vorbis.rs     | 14 +++---
 src/decoder/wav.rs        | 90 ++++++++++++++++++++++++---------------
 6 files changed, 100 insertions(+), 114 deletions(-)

diff --git a/src/conversions/sample.rs b/src/conversions/sample.rs
index f1534285..0162c3b6 100644
--- a/src/conversions/sample.rs
+++ b/src/conversions/sample.rs
@@ -1,4 +1,4 @@
-use dasp_sample::{FromSample, Sample as DaspSample};
+use dasp_sample::{FromSample, Sample as DaspSample, ToSample};
 use std::marker::PhantomData;
 
 /// Converts the samples data type to `O`.
@@ -71,7 +71,7 @@ where
 ///
 /// You can implement this trait on your own type as well if you wish so.
 ///
-pub trait Sample: DaspSample {
+pub trait Sample: DaspSample + ToSample<f32> {
     /// Linear interpolation between two samples.
     ///
     /// The result should be equivalent to
@@ -81,16 +81,22 @@ pub trait Sample: DaspSample {
     fn lerp(first: Self, second: Self, numerator: u32, denominator: u32) -> Self;
 
     /// Multiplies the value of this sample by the given amount.
-    fn amplify(self, value: f32) -> Self;
+    fn amplify(self, value: f32) -> Self {
+        self.mul_amp(value.to_sample())
+    }
 
     /// Converts the sample to a f32 value.
-    fn to_f32(self) -> f32;
+    fn to_f32(self) -> f32 {
+        self.to_sample()
+    }
 
     /// Calls `saturating_add` on the sample.
     fn saturating_add(self, other: Self) -> Self;
 
     /// Returns the value corresponding to the absence of sound.
-    fn zero_value() -> Self;
+    fn zero_value() -> Self {
+        Self::EQUILIBRIUM
+    }
 }
 
 impl Sample for u16 {
@@ -103,26 +109,10 @@ impl Sample for u16 {
         (a + (b - a) * n / d) as u16
     }
 
-    #[inline]
-    fn amplify(self, value: f32) -> 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)
     }
-
-    #[inline]
-    fn zero_value() -> u16 {
-        32768
-    }
 }
 
 impl Sample for i16 {
@@ -132,26 +122,10 @@ impl Sample for i16 {
             as i16
     }
 
-    #[inline]
-    fn amplify(self, value: f32) -> 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)
     }
-
-    #[inline]
-    fn zero_value() -> i16 {
-        0
-    }
 }
 
 impl Sample for f32 {
@@ -160,26 +134,10 @@ impl Sample for f32 {
         first + (second - first) * numerator as f32 / denominator as f32
     }
 
-    #[inline]
-    fn amplify(self, value: f32) -> 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
     }
-
-    #[inline]
-    fn zero_value() -> f32 {
-        0.0
-    }
 }
 
 #[cfg(test)]
diff --git a/src/decoder/flac.rs b/src/decoder/flac.rs
index 83ab235a..b9eadb44 100644
--- a/src/decoder/flac.rs
+++ b/src/decoder/flac.rs
@@ -8,9 +8,10 @@ use crate::Source;
 use crate::common::{ChannelCount, SampleRate};
 
 use claxon::FlacReader;
-use cpal::Sample;
+use cpal::I24;
+use dasp_sample::Sample;
 
-use super::DecoderFormat;
+use super::DecoderSample;
 
 /// Decoder for the Flac format.
 pub struct FlacDecoder<R>
@@ -97,7 +98,7 @@ impl<R> Iterator for FlacDecoder<R>
 where
     R: Read + Seek,
 {
-    type Item = DecoderFormat;
+    type Item = DecoderSample;
 
     #[inline]
     fn next(&mut self) -> Option<Self::Item> {
@@ -109,14 +110,19 @@ where
                     + self.current_block_off / self.channels as usize;
                 let raw_val = self.current_block[real_offset];
                 self.current_block_off += 1;
-                let real_val = match self.bits_per_sample {
-                    8 => (raw_val as i8).to_sample::<Self::Item>(),
-                    12 => (raw_val << 20).to_sample::<Self::Item>(),
-                    16 => (raw_val as i16).to_sample::<Self::Item>(),
-                    20 => (raw_val << 12).to_sample::<Self::Item>(),
-                    24 => (raw_val << 8).to_sample::<Self::Item>(),
-                    32 => raw_val.to_sample::<Self::Item>(),
-                    _ => panic!("Unimplemented flac spec: {} bits", self.bits_per_sample),
+                let bits = self.bits_per_sample;
+                let real_val = match bits {
+                    8 => (raw_val as i8).to_sample(),
+                    16 => (raw_val as i16).to_sample(),
+                    24 => I24::new(raw_val).unwrap_or(Sample::EQUILIBRIUM).to_sample(),
+                    32 => raw_val.to_sample(),
+                    _ => {
+                        // FLAC also supports 12 and 20 bits per sample. We use bit
+                        // shifts to convert them to 32 bits, because:
+                        // - I12 does not exist as a type
+                        // - I20 exists but does not have `ToSample` implemented
+                        (raw_val << (32 - bits)).to_sample()
+                    }
                 };
                 return Some(real_val);
             }
diff --git a/src/decoder/mod.rs b/src/decoder/mod.rs
index 74dbb7eb..dbf9695c 100644
--- a/src/decoder/mod.rs
+++ b/src/decoder/mod.rs
@@ -32,7 +32,7 @@ mod vorbis;
 mod wav;
 
 /// Output format of the decoders.
-pub type DecoderFormat = f32;
+pub type DecoderSample = f32;
 
 /// Source of audio samples from decoding a file.
 ///
@@ -71,7 +71,7 @@ where
 
 impl<R: Read + Seek> DecoderImpl<R> {
     #[inline]
-    fn next(&mut self) -> Option<DecoderFormat> {
+    fn next(&mut self) -> Option<DecoderSample> {
         match self {
             #[cfg(all(feature = "wav", not(feature = "symphonia-wav")))]
             DecoderImpl::Wav(source) => source.next(),
@@ -399,7 +399,7 @@ impl<R> Iterator for Decoder<R>
 where
     R: Read + Seek,
 {
-    type Item = DecoderFormat;
+    type Item = DecoderSample;
 
     #[inline]
     fn next(&mut self) -> Option<Self::Item> {
@@ -445,7 +445,7 @@ impl<R> Iterator for LoopedDecoder<R>
 where
     R: Read + Seek,
 {
-    type Item = DecoderFormat;
+    type Item = DecoderSample;
 
     #[inline]
     fn next(&mut self) -> Option<Self::Item> {
diff --git a/src/decoder/symphonia.rs b/src/decoder/symphonia.rs
index 9b010d11..fc4547a2 100644
--- a/src/decoder/symphonia.rs
+++ b/src/decoder/symphonia.rs
@@ -14,7 +14,7 @@ use symphonia::{
     default::get_probe,
 };
 
-use super::{DecoderError, DecoderFormat};
+use super::{DecoderError, DecoderSample};
 use crate::common::{ChannelCount, SampleRate};
 use crate::{source, Source};
 
@@ -28,7 +28,7 @@ pub(crate) struct SymphoniaDecoder {
     current_span_offset: usize,
     format: Box<dyn FormatReader>,
     total_duration: Option<Time>,
-    buffer: SampleBuffer<DecoderFormat>,
+    buffer: SampleBuffer<DecoderSample>,
     spec: SignalSpec,
 }
 
@@ -144,9 +144,9 @@ impl SymphoniaDecoder {
     }
 
     #[inline]
-    fn get_buffer(decoded: AudioBufferRef, spec: &SignalSpec) -> SampleBuffer<DecoderFormat> {
+    fn get_buffer(decoded: AudioBufferRef, spec: &SignalSpec) -> SampleBuffer<DecoderSample> {
         let duration = units::Duration::from(decoded.capacity() as u64);
-        let mut buffer = SampleBuffer::<DecoderFormat>::new(duration, *spec);
+        let mut buffer = SampleBuffer::<DecoderSample>::new(duration, *spec);
         buffer.copy_interleaved_ref(decoded);
         buffer
     }
@@ -316,7 +316,7 @@ fn time_to_duration(time: Time) -> Duration {
 }
 
 impl Iterator for SymphoniaDecoder {
-    type Item = DecoderFormat;
+    type Item = DecoderSample;
 
     #[inline]
     fn next(&mut self) -> Option<Self::Item> {
diff --git a/src/decoder/vorbis.rs b/src/decoder/vorbis.rs
index 253199ae..135ff80a 100644
--- a/src/decoder/vorbis.rs
+++ b/src/decoder/vorbis.rs
@@ -8,7 +8,7 @@ use crate::common::{ChannelCount, SampleRate};
 use lewton::inside_ogg::OggStreamReader;
 use lewton::samples::InterleavedSamples;
 
-use super::DecoderFormat;
+use super::DecoderSample;
 
 /// Decoder for an OGG file that contains Vorbis sound format.
 pub struct VorbisDecoder<R>
@@ -16,7 +16,7 @@ where
     R: Read + Seek,
 {
     stream_reader: OggStreamReader<R>,
-    current_data: Vec<DecoderFormat>,
+    current_data: Vec<DecoderSample>,
     next: usize,
 }
 
@@ -35,7 +35,7 @@ where
     }
     pub fn from_stream_reader(mut stream_reader: OggStreamReader<R>) -> Self {
         let mut data =
-            match stream_reader.read_dec_packet_generic::<InterleavedSamples<DecoderFormat>>() {
+            match stream_reader.read_dec_packet_generic::<InterleavedSamples<DecoderSample>>() {
                 Ok(Some(d)) => d.samples,
                 _ => Vec::new(),
             };
@@ -43,7 +43,7 @@ where
         // The first packet is always empty, therefore
         // we need to read the second frame to get some data
         if let Ok(Some(mut d)) =
-            stream_reader.read_dec_packet_generic::<InterleavedSamples<DecoderFormat>>()
+            stream_reader.read_dec_packet_generic::<InterleavedSamples<DecoderSample>>()
         {
             data.append(&mut d.samples);
         }
@@ -104,7 +104,7 @@ impl<R> Iterator for VorbisDecoder<R>
 where
     R: Read + Seek,
 {
-    type Item = DecoderFormat;
+    type Item = DecoderSample;
 
     #[inline]
     fn next(&mut self) -> Option<Self::Item> {
@@ -113,7 +113,7 @@ where
             if self.current_data.is_empty() {
                 if let Ok(Some(data)) = self
                     .stream_reader
-                    .read_dec_packet_generic::<InterleavedSamples<DecoderFormat>>()
+                    .read_dec_packet_generic::<InterleavedSamples<DecoderSample>>()
                 {
                     self.current_data = data.samples;
                     self.next = 0;
@@ -123,7 +123,7 @@ where
         } else {
             if let Ok(Some(data)) = self
                 .stream_reader
-                .read_dec_packet_generic::<InterleavedSamples<DecoderFormat>>()
+                .read_dec_packet_generic::<InterleavedSamples<DecoderSample>>()
             {
                 self.current_data = data.samples;
                 self.next = 0;
diff --git a/src/decoder/wav.rs b/src/decoder/wav.rs
index 91e2ae1b..0a020767 100644
--- a/src/decoder/wav.rs
+++ b/src/decoder/wav.rs
@@ -6,10 +6,10 @@ use crate::Source;
 
 use crate::common::{ChannelCount, SampleRate};
 
-use cpal::Sample;
+use dasp_sample::{Sample, I24};
 use hound::{SampleFormat, WavReader};
 
-use super::DecoderFormat;
+use super::DecoderSample;
 
 /// Decoder for the WAV format.
 pub struct WavDecoder<R>
@@ -69,42 +69,64 @@ impl<R> Iterator for SamplesIterator<R>
 where
     R: Read + Seek,
 {
-    type Item = DecoderFormat;
+    type Item = DecoderSample;
 
     #[inline]
     fn next(&mut self) -> Option<Self::Item> {
         self.samples_read += 1;
         let spec = self.reader.spec();
-        match (spec.sample_format, spec.bits_per_sample) {
-            (SampleFormat::Float, 32) => self
-                .reader
-                .samples()
-                .next()
-                .map(|value| value.unwrap_or(0.0)),
-            (SampleFormat::Int, 8) => self
-                .reader
-                .samples()
-                .next()
-                .map(|value| (value.unwrap_or(0) as i8).to_sample::<Self::Item>()),
-            (SampleFormat::Int, 16) => self
-                .reader
-                .samples()
-                .next()
-                .map(|value| (value.unwrap_or(0) as i16).to_sample::<Self::Item>()),
-            (SampleFormat::Int, 24) => self
-                .reader
-                .samples()
-                .next()
-                .map(|value| (value.unwrap_or(0) << 8).to_sample::<Self::Item>()),
-            (SampleFormat::Int, 32) => self
-                .reader
-                .samples()
-                .next()
-                .map(|value| value.unwrap_or(0).to_sample::<Self::Item>()),
-            (sample_format, bits_per_sample) => {
-                panic!("Unimplemented wav spec: {sample_format:?}, {bits_per_sample}")
-            }
-        }
+        let next_sample: Option<Self::Item> =
+            match (spec.sample_format, spec.bits_per_sample as u32) {
+                (SampleFormat::Float, bits) => {
+                    if bits == 32 {
+                        self.reader.samples().next().and_then(|value| value.ok())
+                    } else {
+                        // > 32 bits we cannot handle, so we'll just return equilibrium
+                        // and let the iterator continue
+                        Some(Self::Item::EQUILIBRIUM)
+                    }
+                }
+
+                (SampleFormat::Int, bits) => {
+                    let next_i32 = self.reader.samples().next();
+                    match bits {
+                        8 => next_i32.and_then(|value| {
+                            value
+                                .ok()
+                                .map(|value| (value as i8).to_sample::<Self::Item>())
+                        }),
+                        16 => next_i32.and_then(|value| {
+                            value
+                                .ok()
+                                .map(|value| (value as i16).to_sample::<Self::Item>())
+                        }),
+                        24 => next_i32.and_then(|value| {
+                            value
+                                .ok()
+                                .and_then(I24::new)
+                                .map(|value| value.to_sample::<Self::Item>())
+                        }),
+                        32 => next_i32.and_then(|value| {
+                            value.ok().map(|value| value.to_sample::<Self::Item>())
+                        }),
+                        _ => {
+                            // Unofficial WAV integer bit depth, try to handle it anyway
+                            next_i32.and_then(|value| {
+                                value.ok().map(|value| {
+                                    if bits <= 32 {
+                                        (value << (32 - bits)).to_sample::<Self::Item>()
+                                    } else {
+                                        // > 32 bits we cannot handle, so we'll just return
+                                        // equilibrium and let the iterator continue
+                                        Self::Item::EQUILIBRIUM
+                                    }
+                                })
+                            })
+                        }
+                    }
+                }
+            };
+        next_sample
     }
 
     #[inline]
@@ -169,7 +191,7 @@ impl<R> Iterator for WavDecoder<R>
 where
     R: Read + Seek,
 {
-    type Item = DecoderFormat;
+    type Item = DecoderSample;
 
     #[inline]
     fn next(&mut self) -> Option<Self::Item> {

From cac804b6a5a7a8df8985e005dbd9488420c70171 Mon Sep 17 00:00:00 2001
From: Roderick van Domburg <roderick@vandomburg.net>
Date: Mon, 6 Jan 2025 21:01:52 +0100
Subject: [PATCH 03/18] Fix WAV sample conversion on f32 samples

- Fix broken playback of float WAV samples
- Simplify bit depth handling by using hound's native conversions where possible
- Maintain fallback handling for non-standard bit depths
---
 src/decoder/wav.rs | 70 ++++++++++++++++++++++------------------------
 1 file changed, 33 insertions(+), 37 deletions(-)

diff --git a/src/decoder/wav.rs b/src/decoder/wav.rs
index 0a020767..562e8fa2 100644
--- a/src/decoder/wav.rs
+++ b/src/decoder/wav.rs
@@ -79,7 +79,8 @@ where
             match (spec.sample_format, spec.bits_per_sample as u32) {
                 (SampleFormat::Float, bits) => {
                     if bits == 32 {
-                        self.reader.samples().next().and_then(|value| value.ok())
+                        let next_f32: Option<Result<f32, _>> = self.reader.samples().next();
+                        next_f32.and_then(|value| value.ok().map(|value| value.to_sample()))
                     } else {
                         // > 32 bits we cannot handle, so we'll just return equilibrium
                         // and let the iterator continue
@@ -87,43 +88,38 @@ where
                     }
                 }
 
+                (SampleFormat::Int, 8) => {
+                    let next_i8: Option<Result<i8, _>> = self.reader.samples().next();
+                    next_i8.and_then(|value| value.ok().map(|value| value.to_sample()))
+                }
+                (SampleFormat::Int, 16) => {
+                    let next_i16: Option<Result<i16, _>> = self.reader.samples().next();
+                    next_i16.and_then(|value| value.ok().map(|value| value.to_sample()))
+                }
+                (SampleFormat::Int, 24) => {
+                    let next_i24_in_i32: Option<Result<i32, _>> = self.reader.samples().next();
+                    next_i24_in_i32.and_then(|value| {
+                        value.ok().and_then(I24::new).map(|value| value.to_sample())
+                    })
+                }
+                (SampleFormat::Int, 32) => {
+                    let next_i32: Option<Result<i32, _>> = self.reader.samples().next();
+                    next_i32.and_then(|value| value.ok().map(|value| value.to_sample()))
+                }
                 (SampleFormat::Int, bits) => {
-                    let next_i32 = self.reader.samples().next();
-                    match bits {
-                        8 => next_i32.and_then(|value| {
-                            value
-                                .ok()
-                                .map(|value| (value as i8).to_sample::<Self::Item>())
-                        }),
-                        16 => next_i32.and_then(|value| {
-                            value
-                                .ok()
-                                .map(|value| (value as i16).to_sample::<Self::Item>())
-                        }),
-                        24 => next_i32.and_then(|value| {
-                            value
-                                .ok()
-                                .and_then(I24::new)
-                                .map(|value| value.to_sample::<Self::Item>())
-                        }),
-                        32 => next_i32.and_then(|value| {
-                            value.ok().map(|value| value.to_sample::<Self::Item>())
-                        }),
-                        _ => {
-                            // Unofficial WAV integer bit depth, try to handle it anyway
-                            next_i32.and_then(|value| {
-                                value.ok().map(|value| {
-                                    if bits <= 32 {
-                                        (value << (32 - bits)).to_sample::<Self::Item>()
-                                    } else {
-                                        // > 32 bits we cannot handle, so we'll just return
-                                        // equilibrium and let the iterator continue
-                                        Self::Item::EQUILIBRIUM
-                                    }
-                                })
-                            })
-                        }
-                    }
+                    // Unofficial WAV integer bit depth, try to handle it anyway
+                    let next_i32: Option<Result<i32, _>> = self.reader.samples().next();
+                    next_i32.and_then(|value| {
+                        value.ok().map(|value| {
+                            if bits <= 32 {
+                                (value << (32 - bits)).to_sample()
+                            } else {
+                                // > 32 bits we cannot handle, so we'll just return
+                                // equilibrium and let the iterator continue
+                                Self::Item::EQUILIBRIUM
+                            }
+                        })
+                    })
                 }
             };
         next_sample

From 228ec0ccf558c6f6decf7839b577593a1d0cb346 Mon Sep 17 00:00:00 2001
From: Roderick van Domburg <roderick@vandomburg.net>
Date: Mon, 6 Jan 2025 21:39:05 +0100
Subject: [PATCH 04/18] Add integer-samples feature and fix zero detection
 tests

- Add integer-samples feature to optionally use i16 instead of f32 samples
- Fix unreliable zero detection in WAV and MP4 tests using Sample::is_zero()
- Improve test reliability by checking !all(is_zero) instead of any(!=0.0)

The new feature allows applications to choose between floating-point
and fixed-point sample representation based on their needs, while
maintaining f32 the default for best sound quality.
---
 Cargo.toml                   | 13 ++++++++++++-
 benches/shared.rs            |  9 +++++++--
 src/conversions/sample.rs    |  9 ++++++---
 src/decoder/mod.rs           |  4 ++++
 src/lib.rs                   | 12 +++++++++++-
 src/mixer.rs                 |  2 +-
 src/source/channel_volume.rs |  4 ++--
 src/source/delay.rs          |  2 +-
 src/source/pausable.rs       |  4 ++--
 src/source/zero.rs           |  4 ++--
 tests/flac_test.rs           |  7 +++++--
 tests/mp4a_test.rs           |  4 +++-
 tests/wav_test.rs            | 15 +++++++++------
 13 files changed, 65 insertions(+), 24 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index 296ea901..5bb14dd3 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -30,17 +30,28 @@ default = ["playback", "flac", "vorbis", "wav", "mp3"]
 tracing = ["dep:tracing"]
 experimental = ["dep:atomic_float"]
 playback = ["dep:cpal"]
+integer-samples = []
 
 flac = ["claxon"]
 vorbis = ["lewton"]
 wav = ["hound"]
 mp3 = ["symphonia-mp3"]
 minimp3 = ["dep:minimp3_fixed"]
+
 noise = ["rand"]
+
 wasm-bindgen = ["cpal/wasm-bindgen"]
 cpal-shared-stdcxx = ["cpal/oboe-shared-stdcxx"]
+
 symphonia-aac = ["symphonia/aac"]
-symphonia-all = ["symphonia-aac", "symphonia-flac", "symphonia-isomp4", "symphonia-mp3", "symphonia-vorbis", "symphonia-wav"]
+symphonia-all = [
+    "symphonia-aac",
+    "symphonia-flac",
+    "symphonia-isomp4",
+    "symphonia-mp3",
+    "symphonia-vorbis",
+    "symphonia-wav",
+]
 symphonia-flac = ["symphonia/flac"]
 symphonia-isomp4 = ["symphonia/isomp4"]
 symphonia-mp3 = ["symphonia/mp3"]
diff --git a/benches/shared.rs b/benches/shared.rs
index a99e9ad9..2a1c1fdb 100644
--- a/benches/shared.rs
+++ b/benches/shared.rs
@@ -2,6 +2,7 @@ use std::io::Cursor;
 use std::time::Duration;
 use std::vec;
 
+use dasp_sample::Sample;
 use rodio::{ChannelCount, SampleRate, Source};
 
 pub struct TestSource<T> {
@@ -57,7 +58,11 @@ impl TestSource<f32> {
             channels: sound.channels(),
             sample_rate: sound.sample_rate(),
             total_duration: duration,
-            samples: sound.into_iter().collect::<Vec<_>>().into_iter(),
+            samples: sound
+                .into_iter()
+                .map(|s| s.to_sample())
+                .collect::<Vec<_>>()
+                .into_iter(),
         }
     }
 
@@ -70,7 +75,7 @@ impl TestSource<f32> {
             total_duration,
         } = self;
         let samples = samples
-            .map(|s| dasp_sample::Sample::from_sample(s))
+            .map(|s| s.to_sample())
             .collect::<Vec<_>>()
             .into_iter();
         TestSource {
diff --git a/src/conversions/sample.rs b/src/conversions/sample.rs
index 0162c3b6..386ef649 100644
--- a/src/conversions/sample.rs
+++ b/src/conversions/sample.rs
@@ -72,6 +72,9 @@ where
 /// You can implement this trait on your own type as well if you wish so.
 ///
 pub trait Sample: DaspSample + ToSample<f32> {
+    /// The value corresponding to the absence of sound.
+    const ZERO_VALUE: Self = DaspSample::EQUILIBRIUM;
+
     /// Linear interpolation between two samples.
     ///
     /// The result should be equivalent to
@@ -93,9 +96,9 @@ pub trait Sample: DaspSample + ToSample<f32> {
     /// Calls `saturating_add` on the sample.
     fn saturating_add(self, other: Self) -> Self;
 
-    /// Returns the value corresponding to the absence of sound.
-    fn zero_value() -> Self {
-        Self::EQUILIBRIUM
+    /// Returns true if the sample is the zero value.
+    fn is_zero(self) -> bool {
+        self == Self::ZERO_VALUE
     }
 }
 
diff --git a/src/decoder/mod.rs b/src/decoder/mod.rs
index dbf9695c..abbadc39 100644
--- a/src/decoder/mod.rs
+++ b/src/decoder/mod.rs
@@ -31,6 +31,10 @@ mod vorbis;
 #[cfg(all(feature = "wav", not(feature = "symphonia-wav")))]
 mod wav;
 
+#[cfg(feature = "integer-samples")]
+/// Output format of the decoders.
+pub type DecoderSample = i16;
+#[cfg(not(feature = "integer-samples"))]
 /// Output format of the decoders.
 pub type DecoderSample = f32;
 
diff --git a/src/lib.rs b/src/lib.rs
index 4d17d3b1..9533cde3 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -133,11 +133,21 @@
 //! The "tracing" feature replaces the print to stderr when a stream error happens with a
 //! recording an error event with tracing.
 //!
-//! ### Feature "Noise"
+//! ### Feature "noise"
 //!
 //! The "noise" feature adds support for white and pink noise sources. This feature requires the
 //! "rand" crate.
 //!
+//! ### Feature "playback"
+//!
+//! The "playback" feature adds support for playing audio. This feature requires the "cpal" crate.
+//!
+//! ### Feature "integer-samples"
+//!
+//! The "integer-samples" changes the output format of the decoders to use `i16` instead of `f32`.
+//! This is useful if you want to decode audio on an exotic, low-spec or old device that does not
+//! have hardware support for floating-point operations.
+//!
 //! ## How it works under the hood
 //!
 //! Rodio spawns a background thread that is dedicated to reading from the sources and sending
diff --git a/src/mixer.rs b/src/mixer.rs
index f2719c83..b1e58f42 100644
--- a/src/mixer.rs
+++ b/src/mixer.rs
@@ -197,7 +197,7 @@ where
     }
 
     fn sum_current_sources(&mut self) -> S {
-        let mut sum = S::zero_value();
+        let mut sum = S::ZERO_VALUE;
 
         for mut source in self.current_sources.drain(..) {
             if let Some(value) = source.next() {
diff --git a/src/source/channel_volume.rs b/src/source/channel_volume.rs
index ffdc3f87..dcf1180a 100644
--- a/src/source/channel_volume.rs
+++ b/src/source/channel_volume.rs
@@ -40,7 +40,7 @@ where
             if let Some(s) = input.next() {
                 sample = Some(
                     sample
-                        .get_or_insert_with(I::Item::zero_value)
+                        .get_or_insert(I::Item::ZERO_VALUE)
                         .saturating_add(s.amplify(1.0 / num_channels as f32)),
                 );
             }
@@ -101,7 +101,7 @@ where
                 if let Some(s) = self.input.next() {
                     self.current_sample = Some(
                         self.current_sample
-                            .get_or_insert_with(I::Item::zero_value)
+                            .get_or_insert(I::Item::ZERO_VALUE)
                             .saturating_add(s.amplify(1.0 / num_channels as f32)),
                     );
                 }
diff --git a/src/source/delay.rs b/src/source/delay.rs
index a10e5311..f779e21b 100644
--- a/src/source/delay.rs
+++ b/src/source/delay.rs
@@ -70,7 +70,7 @@ where
     fn next(&mut self) -> Option<<I as Iterator>::Item> {
         if self.remaining_samples >= 1 {
             self.remaining_samples -= 1;
-            Some(Sample::zero_value())
+            Some(Sample::ZERO_VALUE)
         } else {
             self.input.next()
         }
diff --git a/src/source/pausable.rs b/src/source/pausable.rs
index 220ed69b..b3da58b8 100644
--- a/src/source/pausable.rs
+++ b/src/source/pausable.rs
@@ -82,12 +82,12 @@ where
     fn next(&mut self) -> Option<I::Item> {
         if self.remaining_paused_samples > 0 {
             self.remaining_paused_samples -= 1;
-            return Some(I::Item::zero_value());
+            return Some(I::Item::ZERO_VALUE);
         }
 
         if let Some(paused_channels) = self.paused_channels {
             self.remaining_paused_samples = paused_channels - 1;
-            return Some(I::Item::zero_value());
+            return Some(I::Item::ZERO_VALUE);
         }
 
         self.input.next()
diff --git a/src/source/zero.rs b/src/source/zero.rs
index 69e3a295..88f2d743 100644
--- a/src/source/zero.rs
+++ b/src/source/zero.rs
@@ -54,12 +54,12 @@ where
         if let Some(num_samples) = self.num_samples {
             if num_samples > 0 {
                 self.num_samples = Some(num_samples - 1);
-                Some(S::zero_value())
+                Some(S::ZERO_VALUE)
             } else {
                 None
             }
         } else {
-            Some(S::zero_value())
+            Some(S::ZERO_VALUE)
         }
     }
 }
diff --git a/tests/flac_test.rs b/tests/flac_test.rs
index 72d804f0..3db42abc 100644
--- a/tests/flac_test.rs
+++ b/tests/flac_test.rs
@@ -1,3 +1,5 @@
+#[cfg(any(feature = "flac", feature = "symphonia-flac"))]
+use rodio::Sample;
 #[cfg(all(feature = "flac", not(feature = "symphonia-flac")))]
 use rodio::Source;
 #[cfg(all(feature = "flac", not(feature = "symphonia-flac")))]
@@ -11,8 +13,9 @@ fn test_flac_encodings() {
     // 16 bit FLAC file exported from Audacity (2 channels, compression level 5)
     let file = std::fs::File::open("assets/audacity16bit_level5.flac").unwrap();
     let mut decoder = rodio::Decoder::new(BufReader::new(file)).unwrap();
+
     // File is not just silence
-    assert!(decoder.any(|x| x != 0.0));
+    assert!(!decoder.all(|x| x.is_zero()));
     // Symphonia does not expose functionality to get the duration so this check must be disabled
     #[cfg(all(feature = "flac", not(feature = "symphonia-flac")))]
     assert_eq!(decoder.total_duration(), Some(Duration::from_secs(3))); // duration is calculated correctly
@@ -21,7 +24,7 @@ fn test_flac_encodings() {
     for level in &[0, 5, 8] {
         let file = std::fs::File::open(format!("assets/audacity24bit_level{level}.flac")).unwrap();
         let mut decoder = rodio::Decoder::new(BufReader::new(file)).unwrap();
-        assert!(decoder.any(|x| x != 0.0));
+        assert!(!decoder.all(|x| x.is_zero()));
         #[cfg(all(feature = "flac", not(feature = "symphonia-flac")))]
         assert_eq!(decoder.total_duration(), Some(Duration::from_secs(3)));
     }
diff --git a/tests/mp4a_test.rs b/tests/mp4a_test.rs
index 96b17c07..2e2386e4 100644
--- a/tests/mp4a_test.rs
+++ b/tests/mp4a_test.rs
@@ -1,6 +1,8 @@
 #![cfg(all(feature = "symphonia-aac", feature = "symphonia-isomp4"))]
 use std::io::BufReader;
 
+use rodio::Sample;
+
 #[test]
 fn test_mp4a_encodings() {
     // mp4a codec downloaded from YouTube
@@ -10,5 +12,5 @@ fn test_mp4a_encodings() {
     // http://creativecommons.org/licenses/by/3.0/
     let file = std::fs::File::open("assets/monkeys.mp4a").unwrap();
     let mut decoder = rodio::Decoder::new(BufReader::new(file)).unwrap();
-    assert!(decoder.any(|x| x != 0.0)); // Assert not all zeros
+    assert!(!decoder.all(|x| x.is_zero())); // Assert not all zeros
 }
diff --git a/tests/wav_test.rs b/tests/wav_test.rs
index 5a8770ad..d86a175a 100644
--- a/tests/wav_test.rs
+++ b/tests/wav_test.rs
@@ -1,3 +1,6 @@
+#[cfg(feature = "wav")]
+use rodio::Sample;
+
 #[cfg(feature = "wav")]
 #[test]
 fn test_wav_encodings() {
@@ -6,30 +9,30 @@ fn test_wav_encodings() {
     // 16 bit wav file exported from Audacity (1 channel)
     let file = std::fs::File::open("assets/audacity16bit.wav").unwrap();
     let mut decoder = rodio::Decoder::new(BufReader::new(file)).unwrap();
-    assert!(decoder.any(|x| x != 0.0)); // Assert not all zeros
+    assert!(!decoder.all(|x| x.is_zero())); // Assert not all zeros
 
     // 16 bit wav file exported from LMMS (2 channels)
     let file = std::fs::File::open("assets/lmms16bit.wav").unwrap();
     let mut decoder = rodio::Decoder::new(BufReader::new(file)).unwrap();
-    assert!(decoder.any(|x| x != 0.0));
+    assert!(!decoder.all(|x| x.is_zero()));
 
     // 24 bit wav file exported from LMMS (2 channels)
     let file = std::fs::File::open("assets/lmms24bit.wav").unwrap();
     let mut decoder = rodio::Decoder::new(BufReader::new(file)).unwrap();
-    assert!(decoder.any(|x| x != 0.0));
+    assert!(!decoder.all(|x| x.is_zero()));
 
     // 32 bit wav file exported from Audacity (1 channel)
     let file = std::fs::File::open("assets/audacity32bit.wav").unwrap();
     let mut decoder = rodio::Decoder::new(BufReader::new(file)).unwrap();
-    assert!(decoder.any(|x| x != 0.0));
+    assert!(!decoder.all(|x| x.is_zero()));
 
     // 32 bit wav file exported from LMMS (2 channels)
     let file = std::fs::File::open("assets/lmms32bit.wav").unwrap();
     let mut decoder = rodio::Decoder::new(BufReader::new(file)).unwrap();
-    assert!(decoder.any(|x| x != 0.0));
+    assert!(!decoder.all(|x| x.is_zero()));
 
     // 32 bit signed integer wav file exported from Audacity (1 channel).
     let file = std::fs::File::open("assets/audacity32bit_int.wav").unwrap();
     let mut decoder = rodio::Decoder::new(BufReader::new(file)).unwrap();
-    assert!(decoder.any(|x| x != 0.0));
+    assert!(!decoder.all(|x| x.is_zero()));
 }

From caeeeeba6ca74c79ac39f5bcbb80e68882fb5280 Mon Sep 17 00:00:00 2001
From: Roderick van Domburg <roderick@vandomburg.net>
Date: Mon, 6 Jan 2025 22:26:39 +0100
Subject: [PATCH 05/18] Deprecate Sample::zero_value() in favor of constant

Re-introduce zero_value() as a deprecated method to provide migration
path towards using ZERO_VALUE constant. Add is_zero() helper method
for more ergonomic zero checks.

Also cleanup implementations:
- Remove redundant saturating_add() implementations (now using trait default)
- Add #[inline] attributes for performance
---
 CHANGELOG.md              |  4 ++++
 src/conversions/sample.rs | 34 ++++++++++++++++------------------
 2 files changed, 20 insertions(+), 18 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4fcdf718..adce4c95 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,6 +18,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `GeneratorFunction`.
 - Minimal builds without `cpal` audio output are now supported.
   See `README.md` for instructions. (#349)
+- Added `Sample::is_zero()` method for checking zero samples.
 
 ### Changed
 - Breaking: `OutputStreamBuilder` should now be used to initialize an audio output stream.
@@ -36,6 +37,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - An issue with `SignalGenerator` that caused it to create increasingly distorted waveforms
   over long run times has been corrected. (#201)
 
+### Deprecated
+- Deprecated `Sample::zero_value()` function in favor of `Sample::ZERO_VALUE` constant
+
 # Version 0.20.1 (2024-11-08)
 
 ### Fixed
diff --git a/src/conversions/sample.rs b/src/conversions/sample.rs
index 386ef649..bae91ea6 100644
--- a/src/conversions/sample.rs
+++ b/src/conversions/sample.rs
@@ -84,22 +84,35 @@ pub trait Sample: DaspSample + ToSample<f32> {
     fn lerp(first: Self, second: Self, numerator: u32, denominator: u32) -> Self;
 
     /// Multiplies the value of this sample by the given amount.
+    #[inline]
     fn amplify(self, value: f32) -> Self {
         self.mul_amp(value.to_sample())
     }
 
-    /// Converts the sample to a f32 value.
+    /// Converts the sample to a normalized `f32` value.
+    #[inline]
     fn to_f32(self) -> f32 {
         self.to_sample()
     }
 
-    /// Calls `saturating_add` on the sample.
-    fn saturating_add(self, other: Self) -> Self;
+    /// Adds the amplitude of another sample to this one.
+    #[inline]
+    fn saturating_add(self, other: Self) -> Self {
+        self.add_amp(other.to_signed_sample())
+    }
 
     /// Returns true if the sample is the zero value.
+    #[inline]
     fn is_zero(self) -> bool {
         self == Self::ZERO_VALUE
     }
+
+    /// Returns the value corresponding to the absence of sound.
+    #[deprecated(note = "Please use `Self::ZERO_VALUE` instead")]
+    #[inline]
+    fn zero_value() -> Self {
+        Self::ZERO_VALUE
+    }
 }
 
 impl Sample for u16 {
@@ -111,11 +124,6 @@ impl Sample for u16 {
         let d = denominator as i32;
         (a + (b - a) * n / d) as u16
     }
-
-    #[inline]
-    fn saturating_add(self, other: u16) -> u16 {
-        self.saturating_add(other)
-    }
 }
 
 impl Sample for i16 {
@@ -124,11 +132,6 @@ impl Sample for i16 {
         (first as i32 + (second as i32 - first as i32) * numerator as i32 / denominator as i32)
             as i16
     }
-
-    #[inline]
-    fn saturating_add(self, other: i16) -> i16 {
-        self.saturating_add(other)
-    }
 }
 
 impl Sample for f32 {
@@ -136,11 +139,6 @@ impl Sample for f32 {
     fn lerp(first: f32, second: f32, numerator: u32, denominator: u32) -> f32 {
         first + (second - first) * numerator as f32 / denominator as f32
     }
-
-    #[inline]
-    fn saturating_add(self, other: f32) -> f32 {
-        self + other
-    }
 }
 
 #[cfg(test)]

From 6d8eb5817ae214342910fa9d4da5b5a590daa765 Mon Sep 17 00:00:00 2001
From: Roderick van Domburg <roderick@vandomburg.net>
Date: Tue, 7 Jan 2025 21:24:31 +0100
Subject: [PATCH 06/18] perf: optimize Sample, TestSource and benchmarks

- Simplify TestSource initialization by reverting use of generics
- Shortcut direct f32 conversion method for Sample trait
- Shortcut TestSource<f32> implementation
---
 benches/conversions.rs    |  7 ++--
 benches/effects.rs        | 84 ++++++++++++++++++---------------------
 benches/resampler.rs      | 12 +++---
 benches/shared.rs         | 57 +++++++++++++-------------
 src/conversions/sample.rs |  5 +++
 5 files changed, 81 insertions(+), 84 deletions(-)

diff --git a/benches/conversions.rs b/benches/conversions.rs
index 1610191b..40001ccb 100644
--- a/benches/conversions.rs
+++ b/benches/conversions.rs
@@ -1,18 +1,17 @@
 use dasp_sample::FromSample;
 use divan::Bencher;
-use rodio::Source;
+use rodio::{decoder::DecoderSample, Source};
 
 mod shared;
-use shared::TestSource;
 
 fn main() {
     divan::main();
 }
 
 #[divan::bench(types = [i16, u16, f32])]
-fn from_f32_to<T: rodio::Sample + FromSample<f32>>(bencher: Bencher) {
+fn from_sample_to<T: rodio::Sample + FromSample<DecoderSample>>(bencher: Bencher) {
     bencher
-        .with_inputs(|| TestSource::music_wav())
+        .with_inputs(|| shared::music_wav())
         .bench_values(|source| {
             source
                 .convert_samples::<T>()
diff --git a/benches/effects.rs b/benches/effects.rs
index 2849fc82..9e6e1a14 100644
--- a/benches/effects.rs
+++ b/benches/effects.rs
@@ -4,7 +4,7 @@ use divan::Bencher;
 use rodio::Source;
 
 mod shared;
-use shared::TestSource;
+use shared::music_wav;
 
 fn main() {
     divan::main();
@@ -12,76 +12,68 @@ fn main() {
 
 #[divan::bench]
 fn reverb(bencher: Bencher) {
-    bencher
-        .with_inputs(|| TestSource::music_wav())
-        .bench_values(|source| {
-            source
-                .buffered()
-                .reverb(Duration::from_secs_f32(0.05), 0.3)
-                .for_each(divan::black_box_drop)
-        })
+    bencher.with_inputs(|| music_wav()).bench_values(|source| {
+        source
+            .buffered()
+            .reverb(Duration::from_secs_f32(0.05), 0.3)
+            .for_each(divan::black_box_drop)
+    })
 }
 
 #[divan::bench]
 fn high_pass(bencher: Bencher) {
     bencher
-        .with_inputs(|| TestSource::music_wav().to_f32s())
+        .with_inputs(|| music_wav().to_f32s())
         .bench_values(|source| source.high_pass(200).for_each(divan::black_box_drop))
 }
 
 #[divan::bench]
 fn fade_out(bencher: Bencher) {
-    bencher
-        .with_inputs(|| TestSource::music_wav())
-        .bench_values(|source| {
-            source
-                .fade_out(Duration::from_secs(5))
-                .for_each(divan::black_box_drop)
-        })
+    bencher.with_inputs(|| music_wav()).bench_values(|source| {
+        source
+            .fade_out(Duration::from_secs(5))
+            .for_each(divan::black_box_drop)
+    })
 }
 
 #[divan::bench]
 fn amplify(bencher: Bencher) {
     bencher
-        .with_inputs(|| TestSource::music_wav().to_f32s())
+        .with_inputs(|| music_wav())
         .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)
-        })
+    bencher.with_inputs(|| music_wav()).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)
+    })
 }
 
 #[cfg(feature = "experimental")]
 #[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
-            );
+    bencher.with_inputs(|| music_wav()).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);
+        // 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)
-        })
+        // Process the audio stream with AGC disabled
+        amplified_source.for_each(divan::black_box_drop)
+    })
 }
diff --git a/benches/resampler.rs b/benches/resampler.rs
index 7d4609fa..ace155d8 100644
--- a/benches/resampler.rs
+++ b/benches/resampler.rs
@@ -1,9 +1,11 @@
 use divan::Bencher;
+use rodio::decoder::DecoderSample;
 use rodio::source::UniformSourceIterator;
 
 mod shared;
+use shared::music_wav;
+
 use rodio::Source;
-use shared::TestSource;
 
 fn main() {
     divan::main();
@@ -13,11 +15,11 @@ fn main() {
 fn no_resampling(bencher: Bencher) {
     bencher
         .with_inputs(|| {
-            let source = TestSource::<f32>::music_wav();
+            let source = music_wav();
             (source.channels(), source.sample_rate(), source)
         })
         .bench_values(|(channels, sample_rate, source)| {
-            UniformSourceIterator::<_, f32>::new(source, channels, sample_rate)
+            UniformSourceIterator::<_, DecoderSample>::new(source, channels, sample_rate)
                 .for_each(divan::black_box_drop)
         })
 }
@@ -32,11 +34,11 @@ const COMMON_SAMPLE_RATES: [u32; 12] = [
 fn resample_to(bencher: Bencher, target_sample_rate: u32) {
     bencher
         .with_inputs(|| {
-            let source = TestSource::<f32>::music_wav();
+            let source = music_wav();
             (source.channels(), source)
         })
         .bench_values(|(channels, source)| {
-            UniformSourceIterator::<_, f32>::new(source, channels, target_sample_rate)
+            UniformSourceIterator::<_, DecoderSample>::new(source, channels, target_sample_rate)
                 .for_each(divan::black_box_drop)
         })
 }
diff --git a/benches/shared.rs b/benches/shared.rs
index 2a1c1fdb..b2dfea65 100644
--- a/benches/shared.rs
+++ b/benches/shared.rs
@@ -2,8 +2,7 @@ use std::io::Cursor;
 use std::time::Duration;
 use std::vec;
 
-use dasp_sample::Sample;
-use rodio::{ChannelCount, SampleRate, Source};
+use rodio::{decoder::DecoderSample, ChannelCount, Sample, SampleRate, Source};
 
 pub struct TestSource<T> {
     samples: vec::IntoIter<T>,
@@ -26,7 +25,7 @@ impl<T> ExactSizeIterator for TestSource<T> {
     }
 }
 
-impl<T: rodio::Sample> Source for TestSource<T> {
+impl<T: Sample> Source for TestSource<T> {
     fn current_span_len(&self) -> Option<usize> {
         None // forever
     }
@@ -44,28 +43,7 @@ impl<T: rodio::Sample> Source for TestSource<T> {
     }
 }
 
-impl TestSource<f32> {
-    pub fn music_wav() -> Self {
-        let data = include_bytes!("../assets/music.wav");
-        let cursor = Cursor::new(data);
-
-        let duration = Duration::from_secs(10);
-        let sound = rodio::Decoder::new(cursor)
-            .expect("music.wav is correctly encoded & wav is supported")
-            .take_duration(duration);
-
-        TestSource {
-            channels: sound.channels(),
-            sample_rate: sound.sample_rate(),
-            total_duration: duration,
-            samples: sound
-                .into_iter()
-                .map(|s| s.to_sample())
-                .collect::<Vec<_>>()
-                .into_iter(),
-        }
-    }
-
+impl TestSource<i16> {
     #[allow(unused, reason = "not everything from shared is used in all libs")]
     pub fn to_f32s(self) -> TestSource<f32> {
         let TestSource {
@@ -74,10 +52,7 @@ impl TestSource<f32> {
             sample_rate,
             total_duration,
         } = self;
-        let samples = samples
-            .map(|s| s.to_sample())
-            .collect::<Vec<_>>()
-            .into_iter();
+        let samples = samples.map(|s| s.to_f32()).collect::<Vec<_>>().into_iter();
         TestSource {
             samples,
             channels,
@@ -86,3 +61,27 @@ impl TestSource<f32> {
         }
     }
 }
+
+impl TestSource<f32> {
+    #[allow(unused, reason = "not everything from shared is used in all libs")]
+    pub fn to_f32s(self) -> TestSource<f32> {
+        self
+    }
+}
+
+pub fn music_wav() -> TestSource<DecoderSample> {
+    let data = include_bytes!("../assets/music.wav");
+    let cursor = Cursor::new(data);
+
+    let duration = Duration::from_secs(10);
+    let sound = rodio::Decoder::new(cursor)
+        .expect("music.wav is correctly encoded & wav is supported")
+        .take_duration(duration);
+
+    TestSource {
+        channels: sound.channels(),
+        sample_rate: sound.sample_rate(),
+        total_duration: duration,
+        samples: sound.into_iter().collect::<Vec<_>>().into_iter(),
+    }
+}
diff --git a/src/conversions/sample.rs b/src/conversions/sample.rs
index bae91ea6..631b0ac5 100644
--- a/src/conversions/sample.rs
+++ b/src/conversions/sample.rs
@@ -139,6 +139,11 @@ impl Sample for f32 {
     fn lerp(first: f32, second: f32, numerator: u32, denominator: u32) -> f32 {
         first + (second - first) * numerator as f32 / denominator as f32
     }
+
+    #[inline]
+    fn to_f32(self) -> f32 {
+        self
+    }
 }
 
 #[cfg(test)]

From ebcad85bd6998ed1a3e4c5daa4bd000013d41421 Mon Sep 17 00:00:00 2001
From: Roderick van Domburg <roderick@vandomburg.net>
Date: Tue, 7 Jan 2025 22:37:10 +0100
Subject: [PATCH 07/18] flac: Fix overflow and improve error handling

- Fix potential overflow in Duration calculation by doing division before multiplication
- Calculate total_duration once during decoder initialization instead of each call
- Remove unwrap() calls in is_flac() for better error handling
- Refactor code for better maintainability and safety
---
 CHANGELOG.md        |  2 ++
 src/decoder/flac.rs | 47 +++++++++++++++++++++++++--------------------
 2 files changed, 28 insertions(+), 21 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index adce4c95..cee28e47 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -36,6 +36,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Symphonia decoder `total_duration` incorrect value caused by conversion from `Time` to `Duration`.
 - An issue with `SignalGenerator` that caused it to create increasingly distorted waveforms
   over long run times has been corrected. (#201)
+- FLAC decoder duration calculation now calculated once and handles very large files correctly
+- Removed unwrap() calls in FLAC format detection for better error handling
 
 ### Deprecated
 - Deprecated `Sample::zero_value()` function in favor of `Sample::ZERO_VALUE` constant
diff --git a/src/decoder/flac.rs b/src/decoder/flac.rs
index b9eadb44..6ac6e9d4 100644
--- a/src/decoder/flac.rs
+++ b/src/decoder/flac.rs
@@ -8,12 +8,11 @@ use crate::Source;
 use crate::common::{ChannelCount, SampleRate};
 
 use claxon::FlacReader;
-use cpal::I24;
-use dasp_sample::Sample;
+use dasp_sample::{Sample, I24};
 
 use super::DecoderSample;
 
-/// Decoder for the Flac format.
+/// Decoder for the FLAC format.
 pub struct FlacDecoder<R>
 where
     R: Read + Seek,
@@ -25,21 +24,34 @@ where
     bits_per_sample: u32,
     sample_rate: SampleRate,
     channels: ChannelCount,
-    samples: Option<u64>,
+    total_duration: Option<Duration>,
 }
 
 impl<R> FlacDecoder<R>
 where
     R: Read + Seek,
 {
-    /// Attempts to decode the data as Flac.
+    /// Attempts to decode the data as FLAC.
     pub fn new(mut data: R) -> Result<FlacDecoder<R>, R> {
         if !is_flac(data.by_ref()) {
             return Err(data);
         }
 
         let reader = FlacReader::new(data).unwrap();
+
         let spec = reader.streaminfo();
+        let sample_rate = spec.sample_rate;
+
+        // `samples` in FLAC means "inter-channel samples" aka frames
+        // so we do not divide by `self.channels` here.
+        let total_duration = spec.samples.map(|s| {
+            // Calculate duration as (samples * 1_000_000) / sample_rate
+            // but do the division first to avoid overflow
+            let sample_rate = sample_rate as u64;
+            let secs = s / sample_rate;
+            let nanos = ((s % sample_rate) * 1_000_000_000) / sample_rate;
+            Duration::new(secs, nanos as u32)
+        });
 
         Ok(FlacDecoder {
             reader,
@@ -49,11 +61,12 @@ where
             current_block_channel_len: 1,
             current_block_off: 0,
             bits_per_sample: spec.bits_per_sample,
-            sample_rate: spec.sample_rate,
+            sample_rate,
             channels: spec.channels as ChannelCount,
-            samples: spec.samples,
+            total_duration,
         })
     }
+
     pub fn into_inner(self) -> R {
         self.reader.into_inner()
     }
@@ -80,10 +93,7 @@ where
 
     #[inline]
     fn total_duration(&self) -> Option<Duration> {
-        // `samples` in FLAC means "inter-channel samples" aka frames
-        // so we do not divide by `self.channels` here.
-        self.samples
-            .map(|s| Duration::from_micros(s * 1_000_000 / self.sample_rate as u64))
+        self.total_duration
     }
 
     #[inline]
@@ -141,18 +151,13 @@ where
     }
 }
 
-/// Returns true if the stream contains Flac data, then resets it to where it was.
+/// Returns true if the stream contains FLAC data, then tries to rewind it to where it was.
 fn is_flac<R>(mut data: R) -> bool
 where
     R: Read + Seek,
 {
-    let stream_pos = data.stream_position().unwrap();
-
-    if FlacReader::new(data.by_ref()).is_err() {
-        data.seek(SeekFrom::Start(stream_pos)).unwrap();
-        return false;
-    }
-
-    data.seek(SeekFrom::Start(stream_pos)).unwrap();
-    true
+    let stream_pos = data.stream_position().unwrap_or_default();
+    let result = FlacReader::new(data.by_ref()).is_ok();
+    let _ = data.seek(SeekFrom::Start(stream_pos));
+    result
 }

From dcc2e7a3540316d683ac6818d39c28484a87edbb Mon Sep 17 00:00:00 2001
From: Roderick van Domburg <roderick@vandomburg.net>
Date: Tue, 7 Jan 2025 22:39:33 +0100
Subject: [PATCH 08/18] wav: Fix overflow and improve error handling

- Fix potential overflow in total_duration calculation
- Remove unwrap() calls in is_wave() for better error handling
---
 CHANGELOG.md       |  4 ++--
 src/decoder/wav.rs | 22 +++++++++++-----------
 2 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index cee28e47..c40d32a3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -36,8 +36,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Symphonia decoder `total_duration` incorrect value caused by conversion from `Time` to `Duration`.
 - An issue with `SignalGenerator` that caused it to create increasingly distorted waveforms
   over long run times has been corrected. (#201)
-- FLAC decoder duration calculation now calculated once and handles very large files correctly
-- Removed unwrap() calls in FLAC format detection for better error handling
+- WAV and FLAC decoder duration calculation now calculated once and handles very large files correctly
+- Removed unwrap() calls in WAV and FLAC format detection for better error handling
 
 ### Deprecated
 - Deprecated `Sample::zero_value()` function in favor of `Sample::ZERO_VALUE` constant
diff --git a/src/decoder/wav.rs b/src/decoder/wav.rs
index 562e8fa2..8a107bc2 100644
--- a/src/decoder/wav.rs
+++ b/src/decoder/wav.rs
@@ -42,8 +42,13 @@ where
 
         let sample_rate = spec.sample_rate;
         let channels = spec.channels;
-        let total_duration =
-            Duration::from_micros((1_000_000 * len) / (sample_rate as u64 * channels as u64));
+
+        let total_duration = {
+            let sample_rate = sample_rate as u64;
+            let secs = len / sample_rate;
+            let nanos = ((len % sample_rate) * 1_000_000_000) / sample_rate;
+            Duration::new(secs, nanos as u32)
+        };
 
         Ok(WavDecoder {
             reader,
@@ -207,13 +212,8 @@ fn is_wave<R>(mut data: R) -> bool
 where
     R: Read + Seek,
 {
-    let stream_pos = data.stream_position().unwrap();
-
-    if WavReader::new(data.by_ref()).is_err() {
-        data.seek(SeekFrom::Start(stream_pos)).unwrap();
-        return false;
-    }
-
-    data.seek(SeekFrom::Start(stream_pos)).unwrap();
-    true
+    let stream_pos = data.stream_position().unwrap_or_default();
+    let result = WavReader::new(data.by_ref()).is_ok();
+    let _ = data.seek(SeekFrom::Start(stream_pos));
+    result
 }

From b948e55a7239557c8f5771d81159c2a116824dbe Mon Sep 17 00:00:00 2001
From: Roderick van Domburg <roderick@vandomburg.net>
Date: Tue, 7 Jan 2025 22:50:29 +0100
Subject: [PATCH 09/18] mp3: Fix compilation and improve error handling

- Remove unwrap() calls in MP3 format detection
- Convert samples to `DecoderFormat` using to_sample()
---
 CHANGELOG.md       |  2 +-
 src/decoder/mp3.rs | 27 +++++++++++++--------------
 2 files changed, 14 insertions(+), 15 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c40d32a3..ce78cd4d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -37,7 +37,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - An issue with `SignalGenerator` that caused it to create increasingly distorted waveforms
   over long run times has been corrected. (#201)
 - WAV and FLAC decoder duration calculation now calculated once and handles very large files correctly
-- Removed unwrap() calls in WAV and FLAC format detection for better error handling
+- Removed unwrap() calls in MP3, WAV and FLAC format detection for better error handling
 
 ### Deprecated
 - Deprecated `Sample::zero_value()` function in favor of `Sample::ZERO_VALUE` constant
diff --git a/src/decoder/mp3.rs b/src/decoder/mp3.rs
index 99d69a63..5fc2ca44 100644
--- a/src/decoder/mp3.rs
+++ b/src/decoder/mp3.rs
@@ -1,7 +1,8 @@
 use std::io::{Read, Seek, SeekFrom};
 use std::time::Duration;
 
-use super::DecoderFormat;
+use super::DecoderSample;
+use crate::common::{ChannelCount, SampleRate};
 use crate::source::SeekError;
 use crate::Source;
 
@@ -9,6 +10,8 @@ use minimp3::Decoder;
 use minimp3::Frame;
 use minimp3_fixed as minimp3;
 
+use dasp_sample::Sample;
+
 pub struct Mp3Decoder<R>
 where
     R: Read + Seek,
@@ -16,7 +19,7 @@ where
     // decoder: SeekDecoder<R>,
     decoder: Decoder<R>,
     // what minimp3 calls frames rodio calls spans
-    current_span: minimp3::Frame,
+    current_span: Frame,
     current_span_offset: usize,
 }
 
@@ -34,10 +37,7 @@ where
         // thus if we crash here one of these invariants is broken:
         // .expect("should be able to allocate memory, perform IO");
         // let current_span = decoder.decode_frame()
-        let current_span = decoder.next_frame()
-            // the reader makes enough data available therefore
-            // if we crash here the invariant broken is:
-            .expect("data should not corrupt");
+        let current_span = decoder.next_frame().unwrap();
 
         Ok(Mp3Decoder {
             decoder,
@@ -74,7 +74,7 @@ where
         None
     }
 
-    fn try_seek(&mut self, pos: Duration) -> Result<(), SeekError> {
+    fn try_seek(&mut self, _pos: Duration) -> Result<(), SeekError> {
         // TODO waiting for PR in minimp3_fixed or minimp3
 
         // let pos = (pos.as_secs_f32() * self.sample_rate() as f32) as u64;
@@ -93,7 +93,7 @@ impl<R> Iterator for Mp3Decoder<R>
 where
     R: Read + Seek,
 {
-    type Item = DecoderFormat;
+    type Item = DecoderSample;
 
     fn next(&mut self) -> Option<Self::Item> {
         if self.current_span_offset == self.current_span_len().unwrap() {
@@ -109,7 +109,7 @@ where
         let v = self.current_span.data[self.current_span_offset];
         self.current_span_offset += 1;
 
-        Some(v)
+        Some(v.to_sample())
     }
 }
 
@@ -118,10 +118,9 @@ fn is_mp3<R>(mut data: R) -> bool
 where
     R: Read + Seek,
 {
-    let stream_pos = data.seek(SeekFrom::Current(0)).unwrap();
+    let stream_pos = data.stream_position().unwrap_or_default();
     let mut decoder = Decoder::new(data.by_ref());
-    let ok = decoder.next_frame().is_ok();
-    data.seek(SeekFrom::Start(stream_pos)).unwrap();
-
-    ok
+    let result = decoder.next_frame().is_ok();
+    let _ = data.seek(SeekFrom::Start(stream_pos));
+    result
 }

From ef303cbff0d86d01f467c93ad084a3cb0baceb33 Mon Sep 17 00:00:00 2001
From: Roderick van Domburg <roderick@vandomburg.net>
Date: Wed, 8 Jan 2025 20:45:18 +0100
Subject: [PATCH 10/18] fix: handle missing track gracefully in symphonia
 decoder

Instead of unwrapping the track lookup result directly, add proper error
handling to return None when the requested track is not found in the format.
This prevents potential panic scenarios during audio decoding initialization.
---
 src/decoder/symphonia.rs | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/src/decoder/symphonia.rs b/src/decoder/symphonia.rs
index fc4547a2..4d8536ed 100644
--- a/src/decoder/symphonia.rs
+++ b/src/decoder/symphonia.rs
@@ -88,12 +88,15 @@ impl SymphoniaDecoder {
             ))?
             .id;
 
-        let track = probed
+        let track = match probed
             .format
             .tracks()
             .iter()
             .find(|track| track.id == track_id)
-            .unwrap();
+        {
+            Some(track) => track,
+            None => return Ok(None),
+        };
 
         let mut decoder = symphonia::default::get_codecs()
             .make(&track.codec_params, &DecoderOptions::default())?;

From e48655bd9ea2fbdcbfeeafa498f523e3309154a1 Mon Sep 17 00:00:00 2001
From: Roderick van Domburg <roderick@vandomburg.net>
Date: Wed, 8 Jan 2025 20:46:45 +0100
Subject: [PATCH 11/18] vorbis: improve error handling

Makes the Vorbis format detection more robust by:
- Using unwrap_or_default() for stream position failures
- Simplifying the is_vorbis() check logic
- Adding explanatory comment for unwrap in stream reader creation

This change reduces the number of unwrap calls and handles IO errors
more gracefully when checking for Vorbis format.
---
 src/decoder/vorbis.rs | 15 +++++----------
 1 file changed, 5 insertions(+), 10 deletions(-)

diff --git a/src/decoder/vorbis.rs b/src/decoder/vorbis.rs
index 135ff80a..2c36ade4 100644
--- a/src/decoder/vorbis.rs
+++ b/src/decoder/vorbis.rs
@@ -30,7 +30,7 @@ where
             return Err(data);
         }
 
-        let stream_reader = OggStreamReader::new(data).unwrap();
+        let stream_reader = OggStreamReader::new(data).expect("should still be vorbis");
         Ok(Self::from_stream_reader(stream_reader))
     }
     pub fn from_stream_reader(mut stream_reader: OggStreamReader<R>) -> Self {
@@ -145,13 +145,8 @@ fn is_vorbis<R>(mut data: R) -> bool
 where
     R: Read + Seek,
 {
-    let stream_pos = data.stream_position().unwrap();
-
-    if OggStreamReader::new(data.by_ref()).is_err() {
-        data.seek(SeekFrom::Start(stream_pos)).unwrap();
-        return false;
-    }
-
-    data.seek(SeekFrom::Start(stream_pos)).unwrap();
-    true
+    let stream_pos = data.stream_position().unwrap_or_default();
+    let result = OggStreamReader::new(data.by_ref()).is_ok();
+    let _ = data.seek(SeekFrom::Start(stream_pos));
+    result
 }

From 663f4709cecaf0f8e73d9ed2f1464b2aa81993b2 Mon Sep 17 00:00:00 2001
From: Roderick van Domburg <roderick@vandomburg.net>
Date: Wed, 8 Jan 2025 21:06:01 +0100
Subject: [PATCH 12/18] refactor: improve error handling messages across audio
 formats

Add explanatory expect() messages when initializing decoders for FLAC, MP3,
and WAV formats. Also improves MP3 decoder's span length handling by removing
unwrap() in favor of the ? operator. These changes maintain the same behavior
while making debugging easier by providing context for potential panics.

Affected decoders:
- FLAC
- MP3
- WAV
---
 src/decoder/flac.rs | 2 +-
 src/decoder/mp3.rs  | 5 +++--
 src/decoder/wav.rs  | 3 ++-
 3 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/src/decoder/flac.rs b/src/decoder/flac.rs
index 6ac6e9d4..1cf85938 100644
--- a/src/decoder/flac.rs
+++ b/src/decoder/flac.rs
@@ -37,7 +37,7 @@ where
             return Err(data);
         }
 
-        let reader = FlacReader::new(data).unwrap();
+        let reader = FlacReader::new(data).expect("should still be flac");
 
         let spec = reader.streaminfo();
         let sample_rate = spec.sample_rate;
diff --git a/src/decoder/mp3.rs b/src/decoder/mp3.rs
index 5fc2ca44..fe7e5859 100644
--- a/src/decoder/mp3.rs
+++ b/src/decoder/mp3.rs
@@ -37,7 +37,7 @@ where
         // thus if we crash here one of these invariants is broken:
         // .expect("should be able to allocate memory, perform IO");
         // let current_span = decoder.decode_frame()
-        let current_span = decoder.next_frame().unwrap();
+        let current_span = decoder.next_frame().expect("should still be mp3");
 
         Ok(Mp3Decoder {
             decoder,
@@ -96,7 +96,8 @@ where
     type Item = DecoderSample;
 
     fn next(&mut self) -> Option<Self::Item> {
-        if self.current_span_offset == self.current_span_len().unwrap() {
+        let current_span_len = self.current_span_len()?;
+        if self.current_span_offset == current_span_len {
             if let Ok(span) = self.decoder.next_frame() {
                 // if let Ok(span) = self.decoder.decode_frame() {
                 self.current_span = span;
diff --git a/src/decoder/wav.rs b/src/decoder/wav.rs
index 8a107bc2..a3ab3d2a 100644
--- a/src/decoder/wav.rs
+++ b/src/decoder/wav.rs
@@ -32,7 +32,7 @@ where
             return Err(data);
         }
 
-        let reader = WavReader::new(data).unwrap();
+        let reader = WavReader::new(data).expect("should still be wav");
         let spec = reader.spec();
         let len = reader.len() as u64;
         let reader = SamplesIterator {
@@ -57,6 +57,7 @@ where
             channels: channels as ChannelCount,
         })
     }
+
     pub fn into_inner(self) -> R {
         self.reader.reader.into_inner()
     }

From a2669adbb2f1357e67c311d7dc0a05d10e1f28b8 Mon Sep 17 00:00:00 2001
From: Roderick van Domburg <roderick@vandomburg.net>
Date: Wed, 8 Jan 2025 21:22:16 +0100
Subject: [PATCH 13/18] refactor: rename integer-samples feature to
 integer-decoder

Renamed the "integer-samples" feature flag to "integer-decoder" to better
reflect its purpose of controlling decoder output format rather than general
sample handling.

- Renamed feature flag in Cargo.toml
- Updated corresponding cfg attributes in source code
- Updated documentation to reflect the new feature name
- Maintains same functionality of switching between i16/f32 decoder output

This change makes the feature's purpose more explicit and matches the
component it affects.
---
 CHANGELOG.md       | 8 +++++---
 Cargo.toml         | 2 +-
 src/decoder/mod.rs | 4 ++--
 src/lib.rs         | 4 ++--
 4 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ce78cd4d..f2db5982 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -27,7 +27,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Breaking: `Sink::try_new` renamed to `connect_new` and does not return error anymore.
             `Sink::new_idle` was renamed to `new`.
 - Breaking: In the `Source` trait, the method `current_frame_len()` was renamed to `current_span_len()`.
-- Breaking: `Decoder` now outputs `f32` samples instead of `i16`.
+- Breaking: `Decoder` now outputs `f32` samples by default instead of `i16`.
+  Enable the `integer-decoder` to revert to `i16` samples.
 - The term 'frame' was renamed to 'span' in the crate and documentation.
 
 ### Fixed
@@ -36,8 +37,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Symphonia decoder `total_duration` incorrect value caused by conversion from `Time` to `Duration`.
 - An issue with `SignalGenerator` that caused it to create increasingly distorted waveforms
   over long run times has been corrected. (#201)
-- WAV and FLAC decoder duration calculation now calculated once and handles very large files correctly
-- Removed unwrap() calls in MP3, WAV and FLAC format detection for better error handling
+- WAV and FLAC decoder duration calculation now calculated once and handles very large files
+  correctly
+- Removed unwrap() calls in MP3, WAV, FLAC and Vorbis format detection for better error handling
 
 ### Deprecated
 - Deprecated `Sample::zero_value()` function in favor of `Sample::ZERO_VALUE` constant
diff --git a/Cargo.toml b/Cargo.toml
index 5bb14dd3..4e756567 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -30,7 +30,7 @@ default = ["playback", "flac", "vorbis", "wav", "mp3"]
 tracing = ["dep:tracing"]
 experimental = ["dep:atomic_float"]
 playback = ["dep:cpal"]
-integer-samples = []
+integer-decoder = []
 
 flac = ["claxon"]
 vorbis = ["lewton"]
diff --git a/src/decoder/mod.rs b/src/decoder/mod.rs
index abbadc39..1fb45fa4 100644
--- a/src/decoder/mod.rs
+++ b/src/decoder/mod.rs
@@ -31,10 +31,10 @@ mod vorbis;
 #[cfg(all(feature = "wav", not(feature = "symphonia-wav")))]
 mod wav;
 
-#[cfg(feature = "integer-samples")]
+#[cfg(feature = "integer-decoder")]
 /// Output format of the decoders.
 pub type DecoderSample = i16;
-#[cfg(not(feature = "integer-samples"))]
+#[cfg(not(feature = "integer-decoder"))]
 /// Output format of the decoders.
 pub type DecoderSample = f32;
 
diff --git a/src/lib.rs b/src/lib.rs
index 9533cde3..9663887f 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -142,9 +142,9 @@
 //!
 //! The "playback" feature adds support for playing audio. This feature requires the "cpal" crate.
 //!
-//! ### Feature "integer-samples"
+//! ### Feature "integer-decoder"
 //!
-//! The "integer-samples" changes the output format of the decoders to use `i16` instead of `f32`.
+//! The "integer-decoder" changes the output format of the decoders to use `i16` instead of `f32`.
 //! This is useful if you want to decode audio on an exotic, low-spec or old device that does not
 //! have hardware support for floating-point operations.
 //!

From e72be7d36f622a7debde29265ea286ff5389139d Mon Sep 17 00:00:00 2001
From: Roderick van Domburg <roderick@vandomburg.net>
Date: Wed, 8 Jan 2025 21:39:20 +0100
Subject: [PATCH 14/18] perf: optimize sample conversion based on decoder
 output format

Avoid unnecessary sample conversions in MP3 and WAV decoders by using
cfg attributes to conditionally perform format conversion only when needed.
---
 src/decoder/flac.rs |  7 ++++++-
 src/decoder/mp3.rs  |  4 +++-
 src/decoder/wav.rs  | 16 ++++++++++++++--
 3 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/src/decoder/flac.rs b/src/decoder/flac.rs
index 1cf85938..05b18bff 100644
--- a/src/decoder/flac.rs
+++ b/src/decoder/flac.rs
@@ -123,7 +123,12 @@ where
                 let bits = self.bits_per_sample;
                 let real_val = match bits {
                     8 => (raw_val as i8).to_sample(),
-                    16 => (raw_val as i16).to_sample(),
+                    16 => {
+                        let raw_val = raw_val as i16;
+                        #[cfg(not(feature = "integer-decoder"))] // perf
+                        let raw_val = raw_val.to_sample();
+                        raw_val
+                    }
                     24 => I24::new(raw_val).unwrap_or(Sample::EQUILIBRIUM).to_sample(),
                     32 => raw_val.to_sample(),
                     _ => {
diff --git a/src/decoder/mp3.rs b/src/decoder/mp3.rs
index fe7e5859..42ee9a22 100644
--- a/src/decoder/mp3.rs
+++ b/src/decoder/mp3.rs
@@ -110,7 +110,9 @@ where
         let v = self.current_span.data[self.current_span_offset];
         self.current_span_offset += 1;
 
-        Some(v.to_sample())
+        #[cfg(not(feature = "integer-decoder"))] // perf
+        let v = v.to_sample();
+        Some(v)
     }
 }
 
diff --git a/src/decoder/wav.rs b/src/decoder/wav.rs
index a3ab3d2a..c58bc0d5 100644
--- a/src/decoder/wav.rs
+++ b/src/decoder/wav.rs
@@ -86,7 +86,13 @@ where
                 (SampleFormat::Float, bits) => {
                     if bits == 32 {
                         let next_f32: Option<Result<f32, _>> = self.reader.samples().next();
-                        next_f32.and_then(|value| value.ok().map(|value| value.to_sample()))
+                        next_f32.and_then(|value| {
+                            value.ok().map(|value| {
+                                #[cfg(feature = "integer-decoder")] // perf
+                                let value = value.to_sample();
+                                value
+                            })
+                        })
                     } else {
                         // > 32 bits we cannot handle, so we'll just return equilibrium
                         // and let the iterator continue
@@ -100,7 +106,13 @@ where
                 }
                 (SampleFormat::Int, 16) => {
                     let next_i16: Option<Result<i16, _>> = self.reader.samples().next();
-                    next_i16.and_then(|value| value.ok().map(|value| value.to_sample()))
+                    next_i16.and_then(|value| {
+                        value.ok().map(|value| {
+                            #[cfg(not(feature = "integer-decoder"))] // perf
+                            let value = value.to_sample();
+                            value
+                        })
+                    })
                 }
                 (SampleFormat::Int, 24) => {
                     let next_i24_in_i32: Option<Result<i32, _>> = self.reader.samples().next();

From 1a5c3e6a8eeeea79b72e548814c068f69cd7fa0b Mon Sep 17 00:00:00 2001
From: Roderick van Domburg <roderick@vandomburg.net>
Date: Wed, 8 Jan 2025 21:50:23 +0100
Subject: [PATCH 15/18] refactor: fix clippy lints

---
 src/decoder/wav.rs | 18 ++++++++----------
 1 file changed, 8 insertions(+), 10 deletions(-)

diff --git a/src/decoder/wav.rs b/src/decoder/wav.rs
index c58bc0d5..f604bdbf 100644
--- a/src/decoder/wav.rs
+++ b/src/decoder/wav.rs
@@ -87,11 +87,10 @@ where
                     if bits == 32 {
                         let next_f32: Option<Result<f32, _>> = self.reader.samples().next();
                         next_f32.and_then(|value| {
-                            value.ok().map(|value| {
-                                #[cfg(feature = "integer-decoder")] // perf
-                                let value = value.to_sample();
-                                value
-                            })
+                            let value = value.ok();
+                            #[cfg(feature = "integer-decoder")] // perf
+                            let value = value.map(|value| value.to_sample());
+                            value
                         })
                     } else {
                         // > 32 bits we cannot handle, so we'll just return equilibrium
@@ -107,11 +106,10 @@ where
                 (SampleFormat::Int, 16) => {
                     let next_i16: Option<Result<i16, _>> = self.reader.samples().next();
                     next_i16.and_then(|value| {
-                        value.ok().map(|value| {
-                            #[cfg(not(feature = "integer-decoder"))] // perf
-                            let value = value.to_sample();
-                            value
-                        })
+                        let value = value.ok();
+                        #[cfg(not(feature = "integer-decoder"))] // perf
+                        let value = value.map(|value| value.to_sample());
+                        value
                     })
                 }
                 (SampleFormat::Int, 24) => {

From 9711ffe17580a2d158530135e2d6726987d79181 Mon Sep 17 00:00:00 2001
From: Roderick van Domburg <roderick@vandomburg.net>
Date: Wed, 8 Jan 2025 22:12:59 +0100
Subject: [PATCH 16/18] perf: add inline hints to into_inner and I/O methods

Add #[inline] attributes to:
- into_inner() methods across decoders (WAV, Vorbis, Symphonia)
- read() and seek() implementations for ReadSeekSource

These simple pass-through methods are good candidates for inlining as they
just forward calls to their inner types without additional logic.
---
 benches/shared.rs               | 6 ++++++
 src/conversions/mod.rs          | 4 +---
 src/decoder/flac.rs             | 1 +
 src/decoder/mp3.rs              | 2 ++
 src/decoder/read_seek_source.rs | 5 +++++
 src/decoder/symphonia.rs        | 1 +
 src/decoder/vorbis.rs           | 2 ++
 src/decoder/wav.rs              | 1 +
 8 files changed, 19 insertions(+), 3 deletions(-)

diff --git a/benches/shared.rs b/benches/shared.rs
index b2dfea65..bba74cec 100644
--- a/benches/shared.rs
+++ b/benches/shared.rs
@@ -14,30 +14,36 @@ pub struct TestSource<T> {
 impl<T> Iterator for TestSource<T> {
     type Item = T;
 
+    #[inline]
     fn next(&mut self) -> Option<Self::Item> {
         self.samples.next()
     }
 }
 
 impl<T> ExactSizeIterator for TestSource<T> {
+    #[inline]
     fn len(&self) -> usize {
         self.samples.len()
     }
 }
 
 impl<T: Sample> Source for TestSource<T> {
+    #[inline]
     fn current_span_len(&self) -> Option<usize> {
         None // forever
     }
 
+    #[inline]
     fn channels(&self) -> ChannelCount {
         self.channels
     }
 
+    #[inline]
     fn sample_rate(&self) -> SampleRate {
         self.sample_rate
     }
 
+    #[inline]
     fn total_duration(&self) -> Option<Duration> {
         Some(self.total_duration)
     }
diff --git a/src/conversions/mod.rs b/src/conversions/mod.rs
index e6ad817e..a842ccd0 100644
--- a/src/conversions/mod.rs
+++ b/src/conversions/mod.rs
@@ -11,7 +11,5 @@ pub use self::sample::Sample;
 pub use self::sample_rate::SampleRateConverter;
 
 mod channels;
-// TODO: < shouldn't be public ; there's a bug in Rust 1.4 and below that makes This
-// `pub` mandatory
-pub mod sample;
+mod sample;
 mod sample_rate;
diff --git a/src/decoder/flac.rs b/src/decoder/flac.rs
index 05b18bff..d00d01a0 100644
--- a/src/decoder/flac.rs
+++ b/src/decoder/flac.rs
@@ -67,6 +67,7 @@ where
         })
     }
 
+    #[inline]
     pub fn into_inner(self) -> R {
         self.reader.into_inner()
     }
diff --git a/src/decoder/mp3.rs b/src/decoder/mp3.rs
index 42ee9a22..521c7ffc 100644
--- a/src/decoder/mp3.rs
+++ b/src/decoder/mp3.rs
@@ -45,6 +45,8 @@ where
             current_span_offset: 0,
         })
     }
+
+    #[inline]
     pub fn into_inner(self) -> R {
         self.decoder.into_inner()
     }
diff --git a/src/decoder/read_seek_source.rs b/src/decoder/read_seek_source.rs
index 52f20e6d..d9717023 100644
--- a/src/decoder/read_seek_source.rs
+++ b/src/decoder/read_seek_source.rs
@@ -9,28 +9,33 @@ pub struct ReadSeekSource<T: Read + Seek + Send + Sync> {
 impl<T: Read + Seek + Send + Sync> ReadSeekSource<T> {
     /// Instantiates a new `ReadSeekSource<T>` by taking ownership and wrapping the provided
     /// `Read + Seek`er.
+    #[inline]
     pub fn new(inner: T) -> Self {
         ReadSeekSource { inner }
     }
 }
 
 impl<T: Read + Seek + Send + Sync> MediaSource for ReadSeekSource<T> {
+    #[inline]
     fn is_seekable(&self) -> bool {
         true
     }
 
+    #[inline]
     fn byte_len(&self) -> Option<u64> {
         None
     }
 }
 
 impl<T: Read + Seek + Send + Sync> Read for ReadSeekSource<T> {
+    #[inline]
     fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
         self.inner.read(buf)
     }
 }
 
 impl<T: Read + Seek + Send + Sync> Seek for ReadSeekSource<T> {
+    #[inline]
     fn seek(&mut self, pos: SeekFrom) -> Result<u64> {
         self.inner.seek(pos)
     }
diff --git a/src/decoder/symphonia.rs b/src/decoder/symphonia.rs
index 4d8536ed..eb2198ea 100644
--- a/src/decoder/symphonia.rs
+++ b/src/decoder/symphonia.rs
@@ -53,6 +53,7 @@ impl SymphoniaDecoder {
         }
     }
 
+    #[inline]
     pub(crate) fn into_inner(self) -> MediaSourceStream {
         self.format.into_inner()
     }
diff --git a/src/decoder/vorbis.rs b/src/decoder/vorbis.rs
index 2c36ade4..3784c4d6 100644
--- a/src/decoder/vorbis.rs
+++ b/src/decoder/vorbis.rs
@@ -54,6 +54,8 @@ where
             next: 0,
         }
     }
+
+    #[inline]
     pub fn into_inner(self) -> OggStreamReader<R> {
         self.stream_reader
     }
diff --git a/src/decoder/wav.rs b/src/decoder/wav.rs
index f604bdbf..82898142 100644
--- a/src/decoder/wav.rs
+++ b/src/decoder/wav.rs
@@ -58,6 +58,7 @@ where
         })
     }
 
+    #[inline]
     pub fn into_inner(self) -> R {
         self.reader.reader.into_inner()
     }

From 54bb43429dbc744fd5c3a502df4d0f4d13a1a96f Mon Sep 17 00:00:00 2001
From: Roderick van Domburg <roderick@vandomburg.net>
Date: Mon, 13 Jan 2025 19:15:10 +0100
Subject: [PATCH 17/18] wav: return None instead of EQUILIBRIUM for unsupported
 bit depths

Instead of returning EQUILIBRIUM (0.0) when encountering WAV bit depths > 32,
return None to terminate the iterator. Also add error logging through tracing
or stdout to indicate the unsupported format.
---
 src/conversions/sample.rs |  6 ++++++
 src/decoder/wav.rs        | 28 +++++++++++++++-------------
 2 files changed, 21 insertions(+), 13 deletions(-)

diff --git a/src/conversions/sample.rs b/src/conversions/sample.rs
index 631b0ac5..8456e42c 100644
--- a/src/conversions/sample.rs
+++ b/src/conversions/sample.rs
@@ -144,6 +144,12 @@ impl Sample for f32 {
     fn to_f32(self) -> f32 {
         self
     }
+
+    #[inline]
+    fn is_zero(self) -> bool {
+        2.0 * (self - Self::ZERO_VALUE).abs()
+            <= f32::EPSILON * (self.abs() + Self::ZERO_VALUE.abs())
+    }
 }
 
 #[cfg(test)]
diff --git a/src/decoder/wav.rs b/src/decoder/wav.rs
index 82898142..f6381bad 100644
--- a/src/decoder/wav.rs
+++ b/src/decoder/wav.rs
@@ -94,9 +94,11 @@ where
                             value
                         })
                     } else {
-                        // > 32 bits we cannot handle, so we'll just return equilibrium
-                        // and let the iterator continue
-                        Some(Self::Item::EQUILIBRIUM)
+                        #[cfg(feature = "tracing")]
+                        tracing::error!("Unsupported WAV float bit depth: {}", bits);
+                        #[cfg(not(feature = "tracing"))]
+                        println!("Unsupported WAV float bit depth: {}", bits);
+                        None
                     }
                 }
 
@@ -126,17 +128,17 @@ where
                 (SampleFormat::Int, bits) => {
                     // Unofficial WAV integer bit depth, try to handle it anyway
                     let next_i32: Option<Result<i32, _>> = self.reader.samples().next();
-                    next_i32.and_then(|value| {
-                        value.ok().map(|value| {
-                            if bits <= 32 {
-                                (value << (32 - bits)).to_sample()
-                            } else {
-                                // > 32 bits we cannot handle, so we'll just return
-                                // equilibrium and let the iterator continue
-                                Self::Item::EQUILIBRIUM
-                            }
+                    if bits <= 32 {
+                        next_i32.and_then(|value| {
+                            value.ok().map(|value| (value << (32 - bits)).to_sample())
                         })
-                    })
+                    } else {
+                        #[cfg(feature = "tracing")]
+                        tracing::error!("Unsupported WAV integer bit depth: {}", bits);
+                        #[cfg(not(feature = "tracing"))]
+                        println!("Unsupported WAV integer bit depth: {}", bits);
+                        None
+                    }
                 }
             };
         next_sample

From 9861056120d6b7ecc9826585d6a040802106a9fe Mon Sep 17 00:00:00 2001
From: Roderick van Domburg <roderick@vandomburg.net>
Date: Mon, 20 Jan 2025 20:16:26 +0100
Subject: [PATCH 18/18] fix: print wav decoder errors to stdout

---
 src/decoder/wav.rs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/decoder/wav.rs b/src/decoder/wav.rs
index f6381bad..7b389731 100644
--- a/src/decoder/wav.rs
+++ b/src/decoder/wav.rs
@@ -97,7 +97,7 @@ where
                         #[cfg(feature = "tracing")]
                         tracing::error!("Unsupported WAV float bit depth: {}", bits);
                         #[cfg(not(feature = "tracing"))]
-                        println!("Unsupported WAV float bit depth: {}", bits);
+                        eprintln!("Unsupported WAV float bit depth: {}", bits);
                         None
                     }
                 }
@@ -136,7 +136,7 @@ where
                         #[cfg(feature = "tracing")]
                         tracing::error!("Unsupported WAV integer bit depth: {}", bits);
                         #[cfg(not(feature = "tracing"))]
-                        println!("Unsupported WAV integer bit depth: {}", bits);
+                        eprintln!("Unsupported WAV integer bit depth: {}", bits);
                         None
                     }
                 }