flush buffer, changelog entry, rename wav output fns

Author: dvdsk

CHANGELOG.md

@@ -19,6 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Adds a new input source: Microphone.
 - Adds a new method on source: record which collects all samples into a
   SamplesBuffer.
+- Adds `wav_to_writer` which writes a `Source` to a writer.
 
 ### Fixed
 - docs.rs will now document all features, including those that are optional.
@@ -27,6 +28,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `PeriodicAccess` is slightly more accurate for 44.1 kHz sample rate families.
 
 ### Changed
+- `output_to_wav` renamed to `wav_to_file` and now takes ownership of the `Source`.
 - `Blue` noise generator uses uniform instead of Gaussian noise for better performance.
 - `Gaussian` noise generator has standard deviation of 0.6 for perceptual equivalence.
 

src/lib.rs

@@ -198,7 +198,7 @@ pub use crate::spatial_sink::SpatialSink;
 pub use crate::stream::{play, OutputStream, OutputStreamBuilder, PlayError, StreamError};
 #[cfg(feature = "wav_output")]
 #[cfg_attr(docsrs, doc(cfg(feature = "wav_output")))]
-pub use crate::wav_output::output_to_wav;
+pub use crate::wav_output::wav_to_file;
 #[cfg(feature = "wav_output")]
 #[cfg_attr(docsrs, doc(cfg(feature = "wav_output")))]
-pub use crate::wav_output::collect_to_wav;
+pub use crate::wav_output::wav_to_writer;

src/wav_output.rs

@@ -1,8 +1,8 @@
 use crate::common::assert_error_traits;
 use crate::Source;
 use hound::{SampleFormat, WavSpec};
+use std::io::{self, Write};
 use std::path;
-use std::io;
 use std::sync::Arc;
 
 #[derive(Debug, thiserror::Error, Clone)]
@@ -15,6 +15,8 @@ pub enum ToWavError {
     Writing(#[source] Arc<hound::Error>),
     #[error("Failed to update the wav header")]
     Finishing(#[source] Arc<hound::Error>),
+    #[error("Failed to flush all bytes to writer")]
+    Flushing(#[source] Arc<std::io::Error>),
 }
 assert_error_traits!(ToWavError);
 
@@ -23,14 +25,17 @@ assert_error_traits!(ToWavError);
 /// the output without opening output stream to a real audio device.
 ///
 /// If the file already exists it will be overwritten.
-pub fn output_to_wav(
+///
+/// # Note
+/// This is a convenience wrapper around `wav_to_writer`
+pub fn wav_to_file(
     source: impl Source,
     wav_file: impl AsRef<path::Path>,
 ) -> Result<(), ToWavError> {
     let mut file = std::fs::File::create(wav_file)
         .map_err(Arc::new)
         .map_err(ToWavError::OpenFile)?;
-    collect_to_wav(source, &mut file)
+    wav_to_writer(source, &mut file)
 }
 
 /// Saves Source's output into a writer. The output samples format is 32-bit float. This function
@@ -43,16 +48,16 @@ pub fn output_to_wav(
 /// # use rodio::collect_to_wav;
 /// # const SAMPLES: [rodio::Sample; 5] = [0.0, 1.0, 2.0, 3.0, 4.0];
 /// # let source = StaticSamplesBuffer::new(
-/// #     1.try_into().unwrap(), 
-/// #     1.try_into().unwrap(), 
+/// #     1.try_into().unwrap(),
+/// #     1.try_into().unwrap(),
 /// #     &SAMPLES
 /// # );
 /// let mut writer = std::io::Cursor::new(Vec::new());
-/// collect_to_wav(source, &mut writer)?;
+/// wav_to_writer(source, &mut writer)?;
 /// let wav_bytes: Vec<u8> = writer.into_inner();
 /// # Ok::<(), Box<dyn std::error::Error>>(())
 /// ```
-pub fn collect_to_wav(
+pub fn wav_to_writer(
     source: impl Source,
     writer: &mut (impl io::Write + io::Seek),
 ) -> Result<(), ToWavError> {
@@ -62,20 +67,26 @@ pub fn collect_to_wav(
         bits_per_sample: 32,
         sample_format: SampleFormat::Float,
     };
-    let writer = io::BufWriter::new(writer);
-    let mut writer = hound::WavWriter::new(writer, format)
-        .map_err(Arc::new)
-        .map_err(ToWavError::Creating)?;
-    for sample in source {
+    let mut writer = io::BufWriter::new(writer);
+    {
+        let mut writer = hound::WavWriter::new(&mut writer, format)
+            .map_err(Arc::new)
+            .map_err(ToWavError::Creating)?;
+        for sample in source {
+            writer
+                .write_sample(sample)
+                .map_err(Arc::new)
+                .map_err(ToWavError::Writing)?;
+        }
         writer
-            .write_sample(sample)
+            .finalize()
             .map_err(Arc::new)
-            .map_err(ToWavError::Writing)?;
+            .map_err(ToWavError::Finishing)?;
     }
     writer
-        .finalize()
+        .flush()
         .map_err(Arc::new)
-        .map_err(ToWavError::Finishing)?;
+        .map_err(ToWavError::Flushing)?;
     Ok(())
 }