refactor: use BitDepth for bits_per_sample

- Introduce BitDepth as a newtype for non-zero u32
- Update Source trait and all implementations to use Option<BitDepth>
- Update decoders, sources, and tests to use BitDepth instead of u32 for bit depth
- Replace NonZero usage for sample rate and channel count with SampleRate and ChannelCount types where appropriate
- Update documentation and examples to reflect new types

fix: change bits_per_sample to return Option<BitDepth>

Author: roderickvd

benches/pipeline.rs

@@ -1,9 +1,8 @@
-use std::num::NonZero;
 use std::time::Duration;
 
 use divan::Bencher;
-use rodio::ChannelCount;
 use rodio::{source::UniformSourceIterator, Source};
+use rodio::{ChannelCount, SampleRate};
 
 mod shared;
 use shared::music_wav;
@@ -36,7 +35,7 @@ fn long(bencher: Bencher) {
         let resampled = UniformSourceIterator::new(
             effects_applied,
             ChannelCount::new(2).unwrap(),
-            NonZero::new(40_000).unwrap(),
+            SampleRate::new(40_000).unwrap(),
         );
         resampled.for_each(divan::black_box_drop)
     })

benches/shared.rs

@@ -2,13 +2,13 @@ use std::io::Cursor;
 use std::time::Duration;
 use std::vec;
 
-use rodio::{ChannelCount, Sample, SampleRate, Source};
+use rodio::{BitDepth, ChannelCount, Sample, SampleRate, Source};
 
 pub struct TestSource {
     samples: vec::IntoIter<Sample>,
     channels: ChannelCount,
     sample_rate: SampleRate,
-    bits_per_sample: Option<u32>,
+    bits_per_sample: Option<BitDepth>,
     total_duration: Duration,
 }
 
@@ -50,7 +50,7 @@ impl Source for TestSource {
     }
 
     #[inline]
-    fn bits_per_sample(&self) -> Option<u32> {
+    fn bits_per_sample(&self) -> Option<BitDepth> {
         self.bits_per_sample
     }
 }

examples/custom_config.rs

@@ -1,9 +1,8 @@
 use cpal::traits::HostTrait;
 use cpal::{BufferSize, SampleFormat};
 use rodio::source::SineWave;
-use rodio::Source;
+use rodio::{SampleRate, Source};
 use std::error::Error;
-use std::num::NonZero;
 use std::thread;
 use std::time::Duration;
 
@@ -16,7 +15,7 @@ fn main() -> Result<(), Box<dyn Error>> {
         // No need to set all parameters explicitly here,
         // the defaults were set from the device's description.
         .with_buffer_size(BufferSize::Fixed(256))
-        .with_sample_rate(NonZero::new(48_000).unwrap())
+        .with_sample_rate(SampleRate::new(48_000).unwrap())
         .with_sample_format(SampleFormat::F32)
         // Note that the function below still tries alternative configs if the specified one fails.
         // If you need to only use the exact specified configuration,

examples/mix_multiple_sources.rs

@@ -1,12 +1,14 @@
-use rodio::mixer;
 use rodio::source::{SineWave, Source};
+use rodio::{mixer, ChannelCount, SampleRate};
 use std::error::Error;
-use std::num::NonZero;
 use std::time::Duration;
 
 fn main() -> Result<(), Box<dyn Error>> {
     // Construct a dynamic controller and mixer, stream_handle, and sink.
-    let (controller, mixer) = mixer::mixer(NonZero::new(2).unwrap(), NonZero::new(44_100).unwrap());
+    let (controller, mixer) = mixer::mixer(
+        ChannelCount::new(2).unwrap(),
+        SampleRate::new(44_100).unwrap(),
+    );
     let stream_handle = rodio::OutputStreamBuilder::open_default_stream()?;
     let sink = rodio::Sink::connect_new(stream_handle.mixer());
 

examples/signal_generator.rs

@@ -1,7 +1,8 @@
 //! Test signal generator example.
 
 use std::error::Error;
-use std::num::NonZero;
+
+use rodio::SampleRate;
 
 fn main() -> Result<(), Box<dyn Error>> {
     use rodio::source::{chirp, Function, SignalGenerator, Source};
@@ -12,7 +13,7 @@ fn main() -> Result<(), Box<dyn Error>> {
 
     let test_signal_duration = Duration::from_millis(1000);
     let interval_duration = Duration::from_millis(1500);
-    let sample_rate = NonZero::new(48000).unwrap();
+    let sample_rate = SampleRate::new(48000).unwrap();
 
     println!("Playing 1000 Hz tone");
     stream_handle.mixer().add(

src/buffer.rs

@@ -5,15 +5,14 @@
 //! # Example
 //!
 //! ```
-//! use rodio::buffer::SamplesBuffer;
-//! use core::num::NonZero;
-//! let _ = SamplesBuffer::new(NonZero::new(1).unwrap(), NonZero::new(44100).unwrap(), vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0]);
+//! use rodio::{ChannelCount, SampleRate, buffer::SamplesBuffer};
+//! let _ = SamplesBuffer::new(ChannelCount::new(1).unwrap(), SampleRate::new(44100).unwrap(), vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0]);
 //! ```
 //!
 
 use crate::common::{ChannelCount, SampleRate};
 use crate::source::{SeekError, UniformSourceIterator};
-use crate::{Sample, Source};
+use crate::{BitDepth, Sample, Source};
 use std::sync::Arc;
 use std::time::Duration;
 
@@ -92,7 +91,7 @@ impl Source for SamplesBuffer {
     }
 
     #[inline]
-    fn bits_per_sample(&self) -> Option<u32> {
+    fn bits_per_sample(&self) -> Option<BitDepth> {
         None
     }
 

src/common.rs

@@ -4,9 +4,12 @@ use std::num::NonZero;
 /// Stream sample rate (a frame rate or samples per second per channel).
 pub type SampleRate = NonZero<u32>;
 
-/// Number of channels in a stream. Can never be Zero
+/// Number of channels in a stream. Can never be zero.
 pub type ChannelCount = NonZero<u16>;
 
+/// Number of bits per sample. Can never be zero.
+pub type BitDepth = NonZero<u32>;
+
 /// Represents value of a single sample.
 /// Silence corresponds to the value `0.0`. The expected amplitude range is  -1.0...1.0.
 /// Values below and above this range are clipped in conversion to other sample types.

src/decoder/flac.rs

@@ -72,11 +72,7 @@ use dasp_sample::Sample as _;
 use dasp_sample::I24;
 
 use super::{utils, Settings};
-use crate::{
-    common::{ChannelCount, Sample, SampleRate},
-    source::SeekError,
-    Source,
-};
+use crate::{source::SeekError, BitDepth, ChannelCount, Sample, SampleRate, Source};
 
 /// Reader options for `claxon` FLAC decoder.
 ///
@@ -152,7 +148,7 @@ where
     /// Preserved from the original FLAC stream metadata and used for proper
     /// sample conversion during iteration. FLAC supports various bit depths
     /// including non-standard ones like 12 and 20-bit.
-    bits_per_sample: u32,
+    bits_per_sample: BitDepth,
 
     /// Sample rate in Hz.
     ///
@@ -299,7 +295,8 @@ where
             current_block: Vec::with_capacity(max_block_size),
             current_block_samples_per_channel: 1,
             current_block_off: 0,
-            bits_per_sample: spec.bits_per_sample,
+            bits_per_sample: BitDepth::new(spec.bits_per_sample)
+                .expect("flac should never have zero bits per sample"),
             sample_rate: SampleRate::new(sample_rate)
                 .expect("flac data should never have a zero sample rate"),
             channels: ChannelCount::new(
@@ -409,7 +406,7 @@ where
     ///
     /// Always returns `Some(depth)` for valid FLAC streams.
     #[inline]
-    fn bits_per_sample(&self) -> Option<u32> {
+    fn bits_per_sample(&self) -> Option<BitDepth> {
         Some(self.bits_per_sample)
     }
 
@@ -564,7 +561,7 @@ where
                 let raw_val = self.current_block[real_offset];
                 self.current_block_off += 1;
                 self.samples_read += 1;
-                let bits = self.bits_per_sample;
+                let bits = self.bits_per_sample.get();
                 let real_val = match bits {
                     8 => (raw_val as i8).to_sample(),
                     16 => (raw_val as i16).to_sample(),

src/decoder/mod.rs

@@ -59,7 +59,7 @@ use crate::{
     common::{assert_error_traits, ChannelCount, SampleRate},
     math::nz,
     source::{SeekError, Source},
-    Sample,
+    BitDepth, Sample,
 };
 
 pub mod builder;
@@ -269,7 +269,7 @@ impl<R: Read + Seek> DecoderImpl<R> {
     /// For lossy formats this should always return `None` as bit depth is not a meaningful
     /// concept for compressed audio.
     #[inline]
-    fn bits_per_sample(&self) -> Option<u32> {
+    fn bits_per_sample(&self) -> Option<BitDepth> {
         match self {
             #[cfg(feature = "hound")]
             DecoderImpl::Wav(source) => source.bits_per_sample(),
@@ -951,7 +951,7 @@ where
     }
 
     #[inline]
-    fn bits_per_sample(&self) -> Option<u32> {
+    fn bits_per_sample(&self) -> Option<BitDepth> {
         self.0.bits_per_sample()
     }
 
@@ -1131,7 +1131,7 @@ where
 
     /// Returns the bits per sample of the underlying decoder, if available.
     #[inline]
-    fn bits_per_sample(&self) -> Option<u32> {
+    fn bits_per_sample(&self) -> Option<BitDepth> {
         self.inner.as_ref()?.bits_per_sample()
     }
 

src/decoder/mp3.rs

@@ -54,7 +54,6 @@
 
 use std::{
     io::{Read, Seek, SeekFrom},
-    num::NonZero,
     sync::Arc,
     time::Duration,
 };
@@ -66,9 +65,7 @@ use minimp3_fixed as minimp3;
 
 use super::{utils, Settings};
 use crate::{
-    common::{ChannelCount, Sample, SampleRate},
-    decoder::builder::SeekMode,
-    source::SeekError,
+    decoder::builder::SeekMode, source::SeekError, BitDepth, ChannelCount, Sample, SampleRate,
     Source,
 };
 
@@ -354,8 +351,9 @@ where
             start_byte,
             current_span: Some(current_span),
             current_span_offset: 0,
-            channels: NonZero::new(channels as _).expect("mp3's have at least one channel"),
-            sample_rate: NonZero::new(sample_rate as _).expect("mp3's have a non zero sample rate"),
+            channels: ChannelCount::new(channels as _).expect("mp3's have at least one channel"),
+            sample_rate: SampleRate::new(sample_rate as _)
+                .expect("mp3's have a non zero sample rate"),
             samples_read: 0,
             total_samples,
             total_duration,
@@ -537,7 +535,7 @@ where
     /// This method always returns `None` for MP3 streams as bit depth is not
     /// a meaningful concept for lossy compressed audio formats.
     #[inline]
-    fn bits_per_sample(&self) -> Option<u32> {
+    fn bits_per_sample(&self) -> Option<BitDepth> {
         None
     }
 
@@ -716,7 +714,7 @@ where
 
             // Update channels if they changed (can vary between MP3 frames)
             self.channels =
-                NonZero::new(span.channels as _).expect("mp3's have at least one channel");
+                ChannelCount::new(span.channels as _).expect("mp3's have at least one channel");
             // Sample rate is fixed per MP3 stream, so no need to update
             self.current_span = Some(span);
             self.current_span_offset = 0;