refactor: use Decoder::try_from<Path> for file loading in examples and tests

roderickvd · roderickvd · commit 418728260221 · 2025-09-17T21:39:25.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -27,6 +27,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `with_scan_duration()` - Enable file scanning for duration computation.
 - All alternative decoders now support `Settings` via `new_with_settings()`.
 - Symphonia decoder handles multi-track containers and chained Ogg streams.
+- Added `Decoder::TryFrom` implementations for memory-based types:
+  - `Vec<u8>` - Decoding from owned byte vectors
+  - `Box<[u8]>` - Decoding from boxed byte slices
+  - `Arc<[u8]>` - Decoding from shared byte slices
+  - `&'static [u8]` - Decoding from embedded static data
+  - `Cow<'static, [u8]>` - Decoding from borrowed or owned byte data
+  - `bytes::Bytes` - Decoding from bytes crate (requires `bytes` feature)
+  - `&Path` and `PathBuf` - Convenient file path decoding with format hints
+- `TryFrom<BufReader<R>>` and `TryFrom<Cursor<T>>` now use `DecoderBuilder` with optimized settings
+  instead of basic `Decoder::new()` - enabling seeking and byte length detection where possible.
 
 ### Changed
 - `output_to_wav` renamed to `wav_to_file` and now takes ownership of the `Source`.
diff --git a/examples/automatic_gain_control.rs b/examples/automatic_gain_control.rs
@@ -1,7 +1,7 @@
 use rodio::source::Source;
 use rodio::Decoder;
 use std::error::Error;
-use std::fs::File;
+use std::path::Path;
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::Arc;
 use std::thread;
@@ -12,8 +12,8 @@ fn main() -> Result<(), Box<dyn Error>> {
     let sink = rodio::Sink::connect_new(stream_handle.mixer());
 
     // Decode the sound file into a source
-    let file = File::open("assets/music.flac")?;
-    let source = Decoder::try_from(file)?;
+    let path = Path::new("assets/music.flac");
+    let source = Decoder::try_from(path)?;
 
     // Apply automatic gain control to the source
     let agc_source = source.automatic_gain_control(1.0, 4.0, 0.005, 5.0);
diff --git a/examples/callback_on_end.rs b/examples/callback_on_end.rs
@@ -6,8 +6,8 @@ fn main() -> Result<(), Box<dyn Error>> {
     let stream_handle = rodio::OutputStreamBuilder::open_default_stream()?;
     let sink = rodio::Sink::connect_new(stream_handle.mixer());
 
-    let file = std::fs::File::open("assets/music.wav")?;
-    sink.append(rodio::Decoder::try_from(file)?);
+    let path = std::path::Path::new("assets/music.wav");
+    sink.append(rodio::Decoder::try_from(path)?);
 
     // lets increment a number after `music.wav` has played. We are going to use atomics
     // however you could also use a `Mutex` or send a message through a `std::sync::mpsc`.
diff --git a/examples/distortion_mp3.rs b/examples/distortion_mp3.rs
@@ -6,9 +6,9 @@ fn main() -> Result<(), Box<dyn Error>> {
     let stream_handle = rodio::OutputStreamBuilder::open_default_stream()?;
     let sink = rodio::Sink::connect_new(stream_handle.mixer());
 
-    let file = std::fs::File::open("assets/music.mp3")?;
+    let path = std::path::Path::new("assets/music.mp3");
     // Apply distortion effect before appending to the sink
-    let source = rodio::Decoder::try_from(file)?.distortion(4.0, 0.3);
+    let source = rodio::Decoder::try_from(path)?.distortion(4.0, 0.3);
     sink.append(source);
 
     sink.sleep_until_end();
diff --git a/examples/distortion_wav.rs b/examples/distortion_wav.rs
@@ -6,9 +6,9 @@ fn main() -> Result<(), Box<dyn Error>> {
     let stream_handle = rodio::OutputStreamBuilder::open_default_stream()?;
     let sink = rodio::Sink::connect_new(stream_handle.mixer());
 
-    let file = std::fs::File::open("assets/music.wav")?;
+    let path = std::path::Path::new("assets/music.wav");
     // Apply distortion effect before appending to the sink
-    let source = rodio::Decoder::try_from(file)?.distortion(4.0, 0.3);
+    let source = rodio::Decoder::try_from(path)?.distortion(4.0, 0.3);
     sink.append(source);
 
     sink.sleep_until_end();
diff --git a/examples/distortion_wav_alternate.rs b/examples/distortion_wav_alternate.rs
@@ -12,8 +12,8 @@ fn main() -> Result<(), Box<dyn Error>> {
     let stream_handle = rodio::OutputStreamBuilder::open_default_stream()?;
     let sink = rodio::Sink::connect_new(stream_handle.mixer());
 
-    let file = std::fs::File::open("assets/music.wav")?;
-    let source = rodio::Decoder::try_from(file)?;
+    let path = std::path::Path::new("assets/music.wav");
+    let source = rodio::Decoder::try_from(path)?;
 
     // Shared flag to enable/disable distortion
     let distortion_enabled = Arc::new(AtomicBool::new(true));
diff --git a/examples/into_file.rs b/examples/into_file.rs
@@ -5,8 +5,8 @@ use std::error::Error;
 /// This example does not use any audio devices
 /// and can be used in build configurations without `cpal` feature enabled.
 fn main() -> Result<(), Box<dyn Error>> {
-    let file = std::fs::File::open("assets/music.mp3")?;
-    let mut audio = rodio::Decoder::try_from(file)?
+    let path = std::path::Path::new("assets/music.mp3");
+    let mut audio = rodio::Decoder::try_from(path)?
         .automatic_gain_control(1.0, 4.0, 0.005, 3.0)
         .speed(0.8);
 
diff --git a/examples/limit_wav.rs b/examples/limit_wav.rs
@@ -5,8 +5,8 @@ fn main() -> Result<(), Box<dyn Error>> {
     let stream_handle = rodio::OutputStreamBuilder::open_default_stream()?;
     let sink = rodio::Sink::connect_new(stream_handle.mixer());
 
-    let file = std::fs::File::open("assets/music.wav")?;
-    let source = rodio::Decoder::try_from(file)?
+    let path = std::path::Path::new("assets/music.wav");
+    let source = rodio::Decoder::try_from(path)?
         .amplify(3.0)
         .limit(LimitSettings::default());
 
diff --git a/examples/low_pass.rs b/examples/low_pass.rs
@@ -1,14 +1,13 @@
 use std::error::Error;
-use std::io::BufReader;
 
 use rodio::Source;
 
 fn main() -> Result<(), Box<dyn Error>> {
     let stream_handle = rodio::OutputStreamBuilder::open_default_stream()?;
     let sink = rodio::Sink::connect_new(stream_handle.mixer());
 
-    let file = std::fs::File::open("assets/music.wav")?;
-    let decoder = rodio::Decoder::new(BufReader::new(file))?;
+    let path = std::path::Path::new("assets/music.wav");
+    let decoder = rodio::Decoder::try_from(path)?;
     let source = decoder.low_pass(200);
     sink.append(source);
 
diff --git a/examples/music_flac.rs b/examples/music_flac.rs
@@ -4,8 +4,8 @@ fn main() -> Result<(), Box<dyn Error>> {
     let stream_handle = rodio::OutputStreamBuilder::open_default_stream()?;
     let sink = rodio::Sink::connect_new(stream_handle.mixer());
 
-    let file = std::fs::File::open("assets/music.flac")?;
-    sink.append(rodio::Decoder::try_from(file)?);
+    let path = std::path::Path::new("assets/music.flac");
+    sink.append(rodio::Decoder::try_from(path)?);
 
     sink.sleep_until_end();
 
diff --git a/examples/music_m4a.rs b/examples/music_m4a.rs
@@ -4,8 +4,8 @@ fn main() -> Result<(), Box<dyn Error>> {
     let stream_handle = rodio::OutputStreamBuilder::open_default_stream()?;
     let sink = rodio::Sink::connect_new(stream_handle.mixer());
 
-    let file = std::fs::File::open("assets/music.m4a")?;
-    sink.append(rodio::Decoder::try_from(file)?);
+    let path = std::path::Path::new("assets/music.m4a");
+    sink.append(rodio::Decoder::try_from(path)?);
 
     sink.sleep_until_end();
 
diff --git a/examples/music_mp3.rs b/examples/music_mp3.rs
@@ -4,8 +4,8 @@ fn main() -> Result<(), Box<dyn Error>> {
     let stream_handle = rodio::OutputStreamBuilder::open_default_stream()?;
     let sink = rodio::Sink::connect_new(stream_handle.mixer());
 
-    let file = std::fs::File::open("assets/music.mp3")?;
-    sink.append(rodio::Decoder::try_from(file)?);
+    let path = std::path::Path::new("assets/music.mp3");
+    sink.append(rodio::Decoder::try_from(path)?);
 
     sink.sleep_until_end();
 
diff --git a/examples/music_wav.rs b/examples/music_wav.rs
@@ -4,8 +4,8 @@ fn main() -> Result<(), Box<dyn Error>> {
     let stream_handle = rodio::OutputStreamBuilder::open_default_stream()?;
     let sink = rodio::Sink::connect_new(stream_handle.mixer());
 
-    let file = std::fs::File::open("assets/music.wav")?;
-    sink.append(rodio::Decoder::try_from(file)?);
+    let path = std::path::Path::new("assets/music.wav");
+    sink.append(rodio::Decoder::try_from(path)?);
 
     sink.sleep_until_end();
 
diff --git a/examples/reverb.rs b/examples/reverb.rs
@@ -6,8 +6,8 @@ fn main() -> Result<(), Box<dyn Error>> {
     let stream_handle = rodio::OutputStreamBuilder::open_default_stream()?;
     let sink = rodio::Sink::connect_new(stream_handle.mixer());
 
-    let file = std::fs::File::open("assets/music.ogg")?;
-    let source = rodio::Decoder::try_from(file)?;
+    let path = std::path::Path::new("assets/music.ogg");
+    let source = rodio::Decoder::try_from(path)?;
     let with_reverb = source.buffered().reverb(Duration::from_millis(40), 0.7);
     sink.append(with_reverb);
 
diff --git a/examples/seek_mp3.rs b/examples/seek_mp3.rs
@@ -5,8 +5,8 @@ fn main() -> Result<(), Box<dyn Error>> {
     let stream_handle = rodio::OutputStreamBuilder::open_default_stream()?;
     let sink = rodio::Sink::connect_new(stream_handle.mixer());
 
-    let file = std::fs::File::open("assets/music.mp3")?;
-    sink.append(rodio::Decoder::try_from(file)?);
+    let path = std::path::Path::new("assets/music.mp3");
+    sink.append(rodio::Decoder::try_from(path)?);
 
     std::thread::sleep(std::time::Duration::from_secs(2));
     sink.try_seek(Duration::from_secs(0))?;
diff --git a/examples/spatial.rs b/examples/spatial.rs
@@ -28,8 +28,8 @@ fn main() -> Result<(), Box<dyn Error>> {
         positions.2,
     );
 
-    let file = std::fs::File::open("assets/music.ogg")?;
-    let source = rodio::Decoder::try_from(file)?
+    let path = std::path::Path::new("assets/music.ogg");
+    let source = rodio::Decoder::try_from(path)?
         .repeat_infinite()
         .take_duration(total_duration);
     sink.append(source);
diff --git a/examples/stereo.rs b/examples/stereo.rs
@@ -7,8 +7,8 @@ fn main() -> Result<(), Box<dyn Error>> {
     let stream_handle = rodio::OutputStreamBuilder::open_default_stream()?;
     let sink = rodio::Sink::connect_new(stream_handle.mixer());
 
-    let file = std::fs::File::open("assets/RL.ogg")?;
-    sink.append(rodio::Decoder::try_from(file)?.amplify(0.2));
+    let path = std::path::Path::new("assets/RL.ogg");
+    sink.append(rodio::Decoder::try_from(path)?.amplify(0.2));
 
     sink.sleep_until_end();
 
diff --git a/src/decoder/mod.rs b/src/decoder/mod.rs
@@ -5,13 +5,13 @@
 //!
 //! # Usage
 //!
-//! The simplest way to decode files (automatically sets up seeking and duration):
+//! The simplest way to decode files (automatically sets up seeking, duration and format hint):
 //! ```no_run
-//! use std::fs::File;
+//! use std::path::Path;
 //! use rodio::Decoder;
 //!
-//! let file = File::open("audio.mp3").unwrap();
-//! let decoder = Decoder::try_from(file).unwrap();  // Automatically sets byte_len from metadata
+//! let path = Path::new("audio.mp3");
+//! let decoder = Decoder::try_from(path).unwrap();  // Automatically sets byte_len from metadata
 //! ```
 //!
 //! For more control over decoder settings, use the builder pattern:
@@ -322,8 +322,8 @@ impl<R: Read + Seek> DecoderImpl<R> {
 /// use std::fs::File;
 /// use rodio::Decoder;
 ///
-/// let file = File::open("music.mp3").unwrap();
-/// let decoder = Decoder::try_from(file).unwrap();
+/// let path = std::path::Path::new("music.mp3");
+/// let decoder = Decoder::try_from(path).unwrap();
 /// ```
 impl TryFrom<std::fs::File> for Decoder<BufReader<std::fs::File>> {
     type Error = DecoderError;
diff --git a/src/lib.rs b/src/lib.rs
@@ -23,9 +23,9 @@
 //!         .expect("open default audio stream");
 //! let sink = rodio::Sink::connect_new(&stream_handle.mixer());
 //! // Load a sound from a file, using a path relative to Cargo.toml
-//! let file = File::open("examples/music.ogg").unwrap();
+//! let path = std::path::Path::new("examples/music.ogg");
 //! // Decode that sound file into a source
-//! let source = Decoder::try_from(file).unwrap();
+//! let source = Decoder::try_from(path).unwrap();
 //! // Play the sound directly on the device
 //! stream_handle.mixer().add(source);
 //!
diff --git a/src/source/speed.rs b/src/source/speed.rs
@@ -21,9 +21,9 @@
 //! let stream_handle = rodio::OutputStreamBuilder::open_default_stream()
 //!         .expect("open default audio stream");
 //! // Load a sound from a file, using a path relative to `Cargo.toml`
-//! let file = File::open("examples/music.ogg").unwrap();
+//! let path = std::path::Path::new("examples/music.ogg");
 //! // Decode that sound file into a source
-//! let source = Decoder::try_from(file).unwrap();
+//! let source = Decoder::try_from(path).unwrap();
 //! // Play the sound directly on the device 2x faster
 //! stream_handle.mixer().add(source.speed(2.0));
 //! std::thread::sleep(std::time::Duration::from_secs(5));
diff --git a/src/wav_output.rs b/src/wav_output.rs
@@ -46,7 +46,7 @@ pub fn wav_to_file(
 /// # Example
 /// ```rust
 /// # use rodio::static_buffer::StaticSamplesBuffer;
-/// # use rodio::collect_to_wav;
+/// # use rodio::wav_to_writer;
 /// # const SAMPLES: [rodio::Sample; 5] = [0.0, 1.0, 2.0, 3.0, 4.0];
 /// # let source = StaticSamplesBuffer::new(
 /// #     1.try_into().unwrap(),
@@ -130,7 +130,7 @@ impl<I: Iterator<Item = Sample>> Iterator for WholeFrames<I> {
 #[cfg(test)]
 mod test {
     use super::wav_to_file;
-    use crate::Source;
+    use crate::{Decoder, Source};
     use std::io::BufReader;
     use std::time::Duration;
 
@@ -144,15 +144,13 @@ mod test {
         let wav_file_path = "target/tmp/save-to-wav-test.wav";
         wav_to_file(&mut make_source(), wav_file_path).expect("output file can be written");
 
-        let file = std::fs::File::open(wav_file_path).expect("output file can be opened");
-        // Not using crate::Decoder bcause it is limited to i16 samples.
-        let mut reader =
-            hound::WavReader::new(BufReader::new(file)).expect("wav file can be read back");
+        let path = std::path::Path::new(wav_file_path);
+        let decoder = Decoder::try_from(path).expect("wav file can be read back");
         let reference = make_source();
-        assert_eq!(reference.sample_rate().get(), reader.spec().sample_rate);
-        assert_eq!(reference.channels().get(), reader.spec().channels);
+        assert_eq!(reference.sample_rate(), decoder.sample_rate());
+        assert_eq!(reference.channels(), decoder.channels());
 
-        let actual_samples: Vec<f32> = reader.samples::<f32>().map(|x| x.unwrap()).collect();
+        let actual_samples: Vec<f32> = decoder.collect();
         let expected_samples: Vec<f32> = reference.collect();
         assert!(
             expected_samples == actual_samples,
diff --git a/tests/flac_test.rs b/tests/flac_test.rs
@@ -7,17 +7,18 @@ use std::time::Duration;
 #[test]
 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::try_from(file).unwrap();
+    let path = std::path::Path::new("assets/audacity16bit_level5.flac");
+    let mut decoder = rodio::Decoder::try_from(path).unwrap();
 
     // File is not just silence
     assert!(decoder.any(|x| x != 0.0));
     assert_eq!(decoder.total_duration(), Some(Duration::from_secs(3))); // duration is calculated correctly
 
     // 24 bit FLAC file exported from Audacity (2 channels, various compression levels)
     for level in &[0, 5, 8] {
-        let file = std::fs::File::open(format!("assets/audacity24bit_level{level}.flac")).unwrap();
-        let mut decoder = rodio::Decoder::try_from(file).unwrap();
+        let path_str = format!("assets/audacity24bit_level{level}.flac");
+        let path = std::path::Path::new(&path_str);
+        let mut decoder = rodio::Decoder::try_from(path).unwrap();
         assert!(!decoder.all(|x| x != 0.0));
         assert_eq!(decoder.total_duration(), Some(Duration::from_secs(3)));
     }
diff --git a/tests/mp3_test.rs b/tests/mp3_test.rs
@@ -1,8 +1,8 @@
 #[cfg(any(feature = "minimp3", feature = "symphonia-mp3"))]
 #[test]
 fn test_silent_mp3() {
-    let file = std::fs::File::open("assets/silence.mp3").unwrap();
-    let mut decoder = rodio::Decoder::try_from(file).unwrap();
+    let path = std::path::Path::new("assets/silence.mp3");
+    let mut decoder = rodio::Decoder::try_from(path).unwrap();
 
     // File is just silence
     assert!(decoder.all(|x| x < 0.0001));
diff --git a/tests/seek.rs b/tests/seek.rs
@@ -342,12 +342,10 @@ fn time_remaining(decoder: Decoder<impl Read + Seek>) -> Duration {
 
 fn get_music(format: &str) -> Decoder<impl Read + Seek> {
     let asset = Path::new("assets/music").with_extension(format);
-    let file = std::fs::File::open(asset).unwrap();
-    Decoder::try_from(file).unwrap()
+    Decoder::try_from(asset).unwrap()
 }
 
 fn get_rl(format: &str) -> Decoder<impl Read + Seek> {
     let asset = Path::new("assets/RL").with_extension(format);
-    let file = std::fs::File::open(asset).unwrap();
-    Decoder::try_from(file).unwrap()
+    Decoder::try_from(asset).unwrap()
 }
diff --git a/tests/source_traits.rs b/tests/source_traits.rs
@@ -329,8 +329,9 @@ fn decoder_returns_hi_res_bit_depths() {
     ];
 
     for (asset, bit_depth) in CASES {
-        let file = std::fs::File::open(format!("assets/{asset}")).unwrap();
-        if let Ok(decoder) = rodio::Decoder::try_from(file) {
+        let path_str = format!("assets/{asset}");
+        let path = std::path::Path::new(&path_str);
+        if let Ok(decoder) = rodio::Decoder::try_from(path) {
             // TODO: Symphonia returns None for audacity32bit.wav (float)
             if let Some(returned_bit_depth) = decoder.bits_per_sample() {
                 assert_eq!(
diff --git a/tests/wav_test.rs b/tests/wav_test.rs
