Hound

https://docs.rs/hound
Admin
Hound is a Rust library for encoding and decoding WAV audio files with support for multiple sample...
Tokens:77,575
Snippets:683
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Handling File Metadata with `Result`

Source: https://docs.rs/hound/latest/hound/type.Result.html

Shows how to use `Result` and its methods like `and_then` when working with file system operations, such as getting metadata. This example checks for successful retrieval of metadata and handles potential errors like 'NotFound'.

```rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```

--------------------------------

### Writing a WAV file

Source: https://docs.rs/hound/latest/index.html

This example demonstrates how to create a 440 Hz sine wave and save it as a mono WAV file with specific audio properties.

```APIDOC
## Writing a WAV file

This example demonstrates how to create a 440 Hz sine wave and save it as a mono WAV file with specific audio properties.

```rust
use std::f32::consts::PI;
use std::i16;
use hound;

let spec = hound::WavSpec {
    channels: 1,
    sample_rate: 44100,
    bits_per_sample: 16,
    sample_format: hound::SampleFormat::Int,
};
let mut writer = hound::WavWriter::create("sine.wav", spec).unwrap();
for t in (0 .. 44100).map(|x| x as f32 / 44100.0) {
    let sample = (t * 440.0 * 2.0 * PI).sin();
    let amplitude = i16::MAX as f32;
    writer.write_sample((sample * amplitude) as i16).unwrap();
}
writer.finalize().unwrap();
```
```

--------------------------------

### Reading a WAV file and calculating RMS

Source: https://docs.rs/hound/latest/index.html

This example shows how to open an audio file, read its samples, and compute the root mean square (RMS) value.

```APIDOC
## Reading a WAV file and calculating RMS

This example shows how to open an audio file, read its samples, and compute the root mean square (RMS) value.

```rust
use hound;

let mut reader = hound::WavReader::open("testsamples/pop.wav").unwrap();
let sqr_sum = reader.samples::<i16>()
                    .fold(0.0, |sqr_sum, s| {
    let sample = s.unwrap() as f64;
    sqr_sum + sample * sample
});
println!("RMS is {}", (sqr_sum / reader.len() as f64).sqrt());
```
```

--------------------------------

### step_by() Method for WavSamples

Source: https://docs.rs/hound/latest/hound/struct.WavSamples.html

Creates a new iterator that starts at the same point as WavSamples but advances by a specified `step` at each iteration. This method consumes the original iterator.

```rust
fn step_by(self, step: usize) -> StepBy<Self>
where
    Self: Sized,
```

--------------------------------

### Generate WAV Header for Infinite File

Source: https://docs.rs/hound/latest/src/hound/lib.rs.html

Creates a WAV header suitable for infinite audio streams. Shows examples for different channel counts and sample rates.

```rust
let spec = WavSpec {
        bits_per_sample: 16,
        channels: 1,
        sample_format: SampleFormat::Int,
        sample_rate: 16000,
    };
    let v = spec.into_header_for_infinite_file();
    assert_eq!(&v[..], &b"RIFF\xFF\xFF\xFF\xFFWAVE\nfmt \x10\x00\x00\x00\x01\x00\x01\x00\x80>\x00\x00\x00}\x00\x00\x02\x00\x10\x00\ndata\xFF\xFF\xFF\xFF"[..]);

    let spec = WavSpec {
        bits_per_sample: 16,
        channels: 10,
        sample_format: SampleFormat::Int,
        sample_rate: 16000,
    };
    let v = spec.into_header_for_infinite_file();
    assert_eq!(&v[..], &b"RIFF\xFF\xFF\xFF\xFFWAVE\nfmt \x28\x00\x00\x00\xfe\xff\x0a\x00\x80>\x00\x00\x00\xe2\x04\x00\n\x14\x00\x10\x00\x16\x00\x10\x00\xff\x03\x00\x00\x01\x00\x00\x00\n\x00\x00\x10\x00\x80\x00\x00\xaa\x008\x9bQ\ndata\xFF\xFF\xFF\xFF"[..]);
}

```

--------------------------------

### Get WavReader Specification

Source: https://docs.rs/hound/latest/hound/struct.WavReader.html

Returns information about the WAVE file's specifications, such as sample rate, bit depth, and number of channels.

```rust
pub fn spec(&self) -> WavSpec
```

--------------------------------

### Get 16-bit Integer Sample Writer

Source: https://docs.rs/hound/latest/src/hound/write.rs.html

Creates an efficient writer for 16-bit integer samples, omitting dynamic checks. It uses an internal buffer that can be reused if sufficiently large. Panics if the WAV spec is not for 16-bit integer samples or if more samples than allocated are written.

```rust
pub fn get_i16_writer<'s>(&'s mut self,
                             num_samples: u32)
                             -> SampleWriter16<'s, W> {
    if self.spec.sample_format != SampleFormat::Int {
        panic!("When calling get_i16_writer, the sample format must be int.");
    }
    if self.spec.bits_per_sample != 16 {
        panic!("When calling get_i16_writer, the number of bits per sample must be 16.");
    }

    let num_bytes = num_samples as usize * 2;

    if self.sample_writer_buffer.len() < num_bytes {
        let mut new_buffer = Vec::<MaybeUninit<u8>>::with_capacity(num_bytes);
        unsafe { new_buffer.set_len(num_bytes); }
        self.sample_writer_buffer = new_buffer;
    }

    SampleWriter16 {
        writer: &mut self.writer,
        buffer: &mut self.sample_writer_buffer[..num_bytes],
        data_bytes_written: &mut self.data_bytes_written,
        index: 0,
    }
}
```

--------------------------------

### enumerate() Method for WavSamples

Source: https://docs.rs/hound/latest/hound/struct.WavSamples.html

Creates a new iterator that yields pairs of (index, sample), where index is the iteration count starting from zero. This is useful when the position of a sample is relevant.

```rust
fn enumerate(self) -> Enumerate<Self>
where
    Self: Sized,
```

--------------------------------

### Get an efficient 16-bit integer sample writer

Source: https://docs.rs/hound/latest/hound/struct.WavWriter.html

Obtains an efficient writer specifically for 16-bit integer samples. This writer uses internal buffering and omits many dynamic checks, improving performance. It's designed to write exactly `num_samples`.

```rust
pub fn get_i16_writer<'s>(
    &'s mut self,
    num_samples: u32,
) -> SampleWriter16<'s, W>
```

--------------------------------

### Append Samples to a WAV File

Source: https://docs.rs/hound/latest/src/hound/lib.rs.html

Shows how to create a WAV file, write initial samples, and then append more samples to it. Verifies the file size increase and the correctness of appended samples.

```rust
fn assert_contents(fname: &str, expected: &[i16]) {
    let mut reader = WavReader::open(fname).unwrap();
    let samples: Vec<i16> = reader.samples().map(|s| s.unwrap()).collect();
    assert_eq!(&samples[..], expected);
}

#[test]
fn append_works_on_files() {
    use std::fs;

    let spec = WavSpec {
        channels: 1,
        sample_rate: 44100,
        bits_per_sample: 16,
        sample_format: SampleFormat::Int,
    };

    let mut writer = WavWriter::create("append.wav", spec).unwrap();
    writer.write_sample(11_i16).unwrap();
    writer.write_sample(13_i16).unwrap();
    writer.write_sample(17_i16).unwrap();
    writer.finalize().unwrap();

    assert_contents("append.wav", &[11, 13, 17]);

    let len = fs::metadata("append.wav").unwrap().len();

    let mut appender = WavWriter::append("append.wav").unwrap();

    appender.write_sample(19_i16).unwrap();
    appender.write_sample(23_i16).unwrap();
    appender.finalize().unwrap();

    // We appended four bytes of audio data (2 16-bit samples), so the file
    // should have grown by 4 bytes.
    assert_eq!(fs::metadata("append.wav").unwrap().len(), len + 4);

    assert_contents("append.wav", &[11, 13, 17, 19, 23]);
}

```

--------------------------------

### IEEE Float Subformat GUID Constant

Source: https://docs.rs/hound/latest/src/hound/lib.rs.html

Defines the GUID constant for IEEE float audio subformat, used in WAVEFORMATEXTENSIBLE structures.

```rust
const KSDATAFORMAT_SUBFORMAT_IEEE_FLOAT: [u8; 16] = [0x03, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10, 0x00,
                                                   0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71];
```

--------------------------------

### PCM Subformat GUID Constant

Source: https://docs.rs/hound/latest/src/hound/lib.rs.html

Defines the GUID constant for Pulse-Code Modulation (PCM) audio subformat, used in WAVEFORMATEXTENSIBLE structures.

```rust
const KSDATAFORMAT_SUBFORMAT_PCM: [u8; 16] = [0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10, 0x00, 0x80,
                                            0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71];
```

--------------------------------

### WavWriter::new

Source: https://docs.rs/hound/latest/src/hound/write.rs.html

Creates a new WavWriter instance. It takes a writer and WavSpec, and automatically handles the creation of WavSpecEx. It writes parts of the header immediately, so it returns a Result.

```APIDOC
## WavWriter::new

### Description
Creates a writer that writes the WAVE format to the underlying writer. The underlying writer is assumed to be at offset 0. `WavWriter` employs *no* buffering internally. It is recommended to wrap the writer in a `BufWriter` to avoid too many `write` calls. The `create()` constructor does this automatically.

This writes parts of the header immediately, hence a `Result` is returned.

### Parameters
- `writer`: The underlying writer implementing `io::Write` and `io::Seek`.
- `spec`: A `WavSpec` struct describing the audio properties (sample rate, channels, bits per sample).

### Returns
A `Result` containing the initialized `WavWriter` or an error if header writing fails.
```

--------------------------------

### Type ID

Source: https://docs.rs/hound/latest/hound/struct.WavIntoSamples.html

Gets the `TypeId` of `self`.

```APIDOC
#### fn type_id(&self) -> TypeId
```

--------------------------------

### Write and Read i16 Samples Losslessly

Source: https://docs.rs/hound/latest/src/hound/lib.rs.html

Demonstrates writing and reading 16-bit integer samples to and from a WAV file, verifying that the process is lossless.

```rust
#[test]
fn write_read_i16_is_lossless() {
    let mut buffer = io::Cursor::new(Vec::new());
    let write_spec = WavSpec {
        channels: 2,
        sample_rate: 44100,
        bits_per_sample: 16,
        sample_format: SampleFormat::Int,
    };

    {
        let mut writer = WavWriter::new(&mut buffer, write_spec).unwrap();
        for s in -1024_i16..1024 {
            writer.write_sample(s).unwrap();
        }
        writer.finalize().unwrap();
    }

    {
        buffer.set_position(0);
        let mut reader = WavReader::new(&mut buffer).unwrap();
        assert_eq!(write_spec, reader.spec());
        assert_eq!(reader.len(), 2048);
        for (expected, read) in (-1024_i16..1024).zip(reader.samples()) {
            assert_eq!(expected, read.unwrap());
        }
    }
}
```

--------------------------------

### Any::type_id

Source: https://docs.rs/hound/latest/hound/enum.Error.html

Gets the `TypeId` of the current type. This is part of the blanket implementation of the `Any` trait.

```rust
fn type_id(&self) -> TypeId
```

--------------------------------

### GetTypeId Implementation for SampleWriter16

Source: https://docs.rs/hound/latest/hound/struct.SampleWriter16.html

Gets the `TypeId` of `self`. This is part of the `Any` trait implementation.

```rust
fn type_id(&self) -> TypeId

```

--------------------------------

### Create a new WavWriter for a file

Source: https://docs.rs/hound/latest/src/hound/write.rs.html

Use this constructor to create a new WAVE file. It handles file creation, buffering, and initialization of the WavWriter. The file will be overwritten if it already exists.

```rust
pub fn create<P: AsRef<path::Path>>(filename: P, 
spec: WavSpec)
 -> Result<WavWriter<io::BufWriter<fs::File>>> {
        let file = try!(fs::File::create(filename));
        let buf_writer = io::BufWriter::new(file);
        WavWriter::new(buf_writer, spec)
    }
```

--------------------------------

### fn report(self) -> ExitCode

Source: https://docs.rs/hound/latest/hound/type.Result.html

Is called to get the representation of the value as status code. This status code is returned to the operating system.

```APIDOC
## fn report(self) -> ExitCode

### Description
Is called to get the representation of the value as status code. This status code is returned to the operating system.

### Parameters
#### Path Parameters
- **self** (Result<T, E>) - Required - The Result value to report.

### Response
- **ExitCode** - The status code representation of the Result.
```

--------------------------------

### Write and Read i24 Samples Losslessly

Source: https://docs.rs/hound/latest/src/hound/lib.rs.html

Illustrates writing 24-bit integer samples using i32 and reading them back as i32, confirming lossless sign extension.

```rust
#[test]
fn write_read_i24_is_lossless() {
    let mut buffer = io::Cursor::new(Vec::new());
    let write_spec = WavSpec {
        channels: 16,
        sample_rate: 96000,
        bits_per_sample: 24,
        sample_format: SampleFormat::Int,
    };

    // Write `i32` samples, but with at most 24 bits per sample.
    {
        let mut writer = WavWriter::new(&mut buffer, write_spec).unwrap();
        for s in -128_i32..127 + 1 {
            writer.write_sample(s * 256 * 256).unwrap();
        }
        writer.finalize().unwrap();
    }

    // Then read them into `i32`. This should extend the sign in the correct
    // manner.
    {
        buffer.set_position(0);
        let mut reader = WavReader::new(&mut buffer).unwrap();
        assert_eq!(write_spec, reader.spec());
        assert_eq!(reader.len(), 256);
        for (expected, read) in (-128_i32..127 + 1)
            .map(|x| x * 256 * 256)
            .zip(reader.samples()) {
            assert_eq!(expected, read.unwrap());
        }
    }
}
```

--------------------------------

### Get Remaining Sample Count

Source: https://docs.rs/hound/latest/src/hound/read.rs.html

Provides the number of samples remaining in the WAV file. This is used by the iterator's size_hint method.

```rust
fn iter_size_hint<R>(reader: &WavReader<R>) -> (usize, Option<usize>) {
    let samples_left = reader.num_samples - reader.samples_read;
    (samples_left as usize, Some(samples_left as usize))
}
```

--------------------------------

### Append Samples to Existing WAV File

Source: https://docs.rs/hound/latest/src/hound/lib.rs.html

Shows how to use `WavWriter::new_append` to add more samples to an existing WAV file in memory. The appended samples are correctly read after seeking to the beginning of the buffer.

```rust
let mut buffer = io::Cursor::new(Vec::new());
    let samples = &[2, 5, 7, 11];
    let spec = WavSpec {
        channels: 2,
        sample_rate: 44100,
        bits_per_sample: 16,
        sample_format: SampleFormat::Int,
    };

    // Write initial file.
    {
        let mut writer = WavWriter::new(&mut buffer, spec).unwrap();
        for s in samples { writer.write_sample(*s).unwrap(); }
    }

    buffer.seek(io::SeekFrom::Start(0)).unwrap();

    // Append samples (the same ones a second time).
    {
        let mut writer = WavWriter::new_append(&mut buffer).unwrap();
        assert_eq!(writer.spec(), spec);
        for s in samples { writer.write_sample(*s).unwrap(); }
    }

    buffer.seek(io::SeekFrom::Start(0)).unwrap();

    let mut reader = WavReader::new(&mut buffer).unwrap();
    let read_samples: Vec<i16> = reader.samples()
        .map(|r| r.unwrap())
        .collect();

    // We expect to see all samples up to the flush, but not the later ones.
    assert_eq!(&read_samples[..], &[2, 5, 7, 11, 2, 5, 7, 11]);
```

--------------------------------

### i32 Sample Implementation

Source: https://docs.rs/hound/latest/hound/trait.Sample.html

Implementation of the Sample trait for i32 audio samples. Provides methods for reading, writing, and converting i32 samples.

```rust
impl Sample for i32 {
    fn write<W: Write>(self, writer: &mut W, bits: u16) -> Result<()> { ... }
    fn write_padded<W: Write>(
        self,
        writer: &mut W,
        bits: u16,
        byte_width: u16,
    ) -> Result<()>
    {
        ... 
    }
    fn as_i16(self) -> i16 { ... }
    fn read<R: Read>(
        reader: &mut R,
        fmt: SampleFormat,
        bytes: u16,
        bits: u16,
    ) -> Result<i32> {
        ... 
    }
}
```

--------------------------------

### Error::source - Get Underlying Error

Source: https://docs.rs/hound/latest/hound/enum.Error.html

Retrieves the lower-level source of this error, if one exists. This is useful for error inspection and handling.

```rust
fn source(&self) -> Option<&(dyn Error + 'static)>
```

--------------------------------

### Error::cause - Deprecated

Source: https://docs.rs/hound/latest/hound/enum.Error.html

Deprecated method to get the underlying cause of an error. Prefer `Error::source` for newer Rust versions.

```rust
fn cause(&self) -> Option<&dyn Error>
```

--------------------------------

### Create a new WavWriter with WavSpecEx

Source: https://docs.rs/hound/latest/hound/struct.WavWriter.html

Creates a new WavWriter using an extended specification (WavSpecEx). Similar to `new()`, it's recommended to use a BufWriter for performance. This function also writes initial header parts, returning a Result.

```rust
pub fn new_with_spec_ex(writer: W, spec_ex: WavSpecEx) -> Result<WavWriter<W>>
```

--------------------------------

### Get WAV Length

Source: https://docs.rs/hound/latest/src/hound/write.rs.html

Returns the number of samples in the file written so far. The length of the file is its duration (in samples) times the number of channels.

```rust
pub fn len(&self) -> u32 {
        self.data_bytes_written / self.bytes_per_sample as u32
    }
```

--------------------------------

### Write and Read i16 Samples via SampleWriter Losslessly

Source: https://docs.rs/hound/latest/src/hound/lib.rs.html

Shows how to use SampleWriter for writing 16-bit integer samples, including both safe and unchecked methods, and verifies lossless read operations.

```rust
#[test]
fn write_read_i16_via_sample_writer_is_lossless() {
    let mut buffer = io::Cursor::new(Vec::new());
    let write_spec = WavSpec {
        channels: 2,
        sample_rate: 44100,
        bits_per_sample: 16,
        sample_format: SampleFormat::Int,
    };

    {
        let mut writer = WavWriter::new(&mut buffer, write_spec).unwrap();
        {
            {
                let mut sample_writer = writer.get_i16_writer(1024);
                for s in -1024_i16..0 {
                    sample_writer.write_sample(s);
                }
                sample_writer.flush().unwrap();
            }

            {
                let mut sample_writer = writer.get_i16_writer(1024);
                for s in 0i16..1024 {
                    unsafe { sample_writer.write_sample_unchecked(s); }
                }
                sample_writer.flush().unwrap();
            }
        }
        writer.finalize().unwrap();
    }

    {
        buffer.set_position(0);
        let mut reader = WavReader::new(&mut buffer).unwrap();
        assert_eq!(write_spec, reader.spec());
        assert_eq!(reader.len(), 2048);
        for (expected, read) in (-1024_i16..1024).zip(reader.samples()) {
            assert_eq!(expected, read.unwrap());
        }
    }
}
```

--------------------------------

### Get WavReader Length

Source: https://docs.rs/hound/latest/hound/struct.WavReader.html

Returns the total number of sample values the iterator will yield. This is calculated as duration (in samples) multiplied by the number of channels.

```rust
pub fn len(&self) -> u32
```

--------------------------------

### Write and Read Float Samples to WAV

Source: https://docs.rs/hound/latest/src/hound/lib.rs.html

Demonstrates writing float samples to a WAV file in memory and then reading them back to verify correctness. Ensures the WAV specification matches the read data and that all samples are correctly written and read.

```rust
let mut buffer = io::Cursor::new(Vec::new());
    let write_spec = WavSpec {
        channels: 2,
        sample_rate: 44100,
        bits_per_sample: 32,
        sample_format: SampleFormat::Float,
    };

    {
        let mut writer = WavWriter::new(&mut buffer, write_spec).unwrap();
        for s in 1_u32..257 {
            writer.write_sample(1.0f32 / s as f32).unwrap();
        }
        writer.finalize().unwrap();
    }

    {
        buffer.set_position(0);
        let mut reader = WavReader::new(&mut buffer).unwrap();
        assert_eq!(write_spec, reader.spec());
        assert_eq!(reader.len(), 256);
        for (expected, read) in (1..257)
            .map(|x| 1.0_f32 / x as f32)
            .zip(reader.samples()) {
            assert_eq!(expected, read.unwrap());
        }
    }
```

--------------------------------

### Get WavReader Duration

Source: https://docs.rs/hound/latest/hound/struct.WavReader.html

Returns the duration of the WAVE file in samples. This value is independent of the number of channels and how many samples have already been read.

```rust
pub fn duration(&self) -> u32
```

--------------------------------

### Read, Append, and Read WAV Data

Source: https://docs.rs/hound/latest/src/hound/lib.rs.html

Demonstrates reading samples from a WAV buffer, appending new samples, and then reading the modified buffer. Ensures original samples are preserved and appended samples are correctly added.

```rust
f.read_to_end(&mut buffer).unwrap();

        let samples_orig: Vec<i32>;
        let samples_after: Vec<i32>;

        // Read samples first.
        let mut cursor = io::Cursor::new(buffer);
        {
            let mut reader = WavReader::new(&mut cursor).unwrap();
            samples_orig = reader.samples().map(|r| r.unwrap()).collect();
        }
        buffer = cursor.into_inner();

        // Open in append mode and append one sample.
        let mut cursor = io::Cursor::new(buffer);
        {
            let mut writer = WavWriter::new_append(&mut cursor).unwrap();
            writer.write_sample(41_i8).unwrap();
            writer.write_sample(43_i8).unwrap();
        }
        buffer = cursor.into_inner();

        {
            let cursor = io::Cursor::new(buffer);
            let mut reader = WavReader::new(cursor)
                .expect("Reading wav failed after append.");
            samples_after = reader.samples().map(|r| r.unwrap()).collect();
        }

        assert_eq!(&samples_orig[..], &samples_after[..samples_orig.len()]);
        assert_eq!(samples_after[samples_after.len() - 2], 41_i32);
        assert_eq!(samples_after[samples_after.len() - 1], 43_i32);

        println!("ok");
    }
}

```

--------------------------------

### Iterating over Ok values with iter

Source: https://docs.rs/hound/latest/hound/type.Result.html

Use `iter` to get an iterator that yields a reference to the contained value if the Result is Ok, otherwise yields nothing.

```rust
let x: Result<u32, &str> = Ok(7);
assert_eq!(x.iter().next(), Some(&7));

let x: Result<u32, &str> = Err("nothing!");
assert_eq!(x.iter().next(), None);
```

--------------------------------

### Sample::read Method

Source: https://docs.rs/hound/latest/hound/trait.Sample.html

Reads an audio sample from a WAVE data chunk. Requires a reader, sample format, byte count, and bit depth.

```rust
fn read<R: Read>(
        reader: &mut R,
        _: SampleFormat,
        bytes: u16,
        bits: u16,
    ) -> Result<Self>
```

--------------------------------

### next() Method for WavSamples

Source: https://docs.rs/hound/latest/hound/struct.WavSamples.html

Advances the WavSamples iterator and returns the next audio sample as an Option containing a Result. The Result will be Ok(S) on success or Err(Error) if an issue occurs during reading.

```rust
fn next(&mut self) -> Option<Result<S>>;
```

--------------------------------

### Get WAV Duration

Source: https://docs.rs/hound/latest/src/hound/write.rs.html

Returns the duration of the file written so far, in samples. The duration is independent of the number of channels and can be obtained in seconds by dividing by the sample rate.

```rust
pub fn duration(&self) -> u32 {
        self.data_bytes_written / (self.bytes_per_sample as u32 * self.spec.channels as u32)
    }
```

--------------------------------

### Sample::write Method

Source: https://docs.rs/hound/latest/hound/trait.Sample.html

Writes an audio sample to a WAVE data chunk. Ensure the writer and bits parameters are correctly configured for the target format.

```rust
fn write<W: Write>(self, writer: &mut W, bits: u16) -> Result<()>
```

--------------------------------

### Consume WavReader to get Inner Reader

Source: https://docs.rs/hound/latest/hound/struct.WavReader.html

Destroys the `WavReader` and returns the underlying reader. This is useful if you need to access the original reader after processing the audio data.

```rust
pub fn into_inner(self) -> R
```

--------------------------------

### Iterate Over WAV Samples

Source: https://docs.rs/hound/latest/src/hound/read.rs.html

Provides an iterator for WAV samples. Use this to read samples one by one from a WavReader. It handles sample format conversion and advances the reader's position.

```rust
fn iter_next<R, S>(reader: &mut WavReader<R>) -> Option<Result<S>>
    where R: io::Read,
          S: Sample
{
    if reader.samples_read < reader.num_samples {
        reader.samples_read += 1;
        let sample = Sample::read(&mut reader.reader,
                                  reader.spec.sample_format,
                                  reader.bytes_per_sample,
                                  reader.spec.bits_per_sample);
        Some(sample.map_err(Error::from))
    } else {
        None
    }
}
```

```rust
impl<'wr, R, S> Iterator for WavSamples<'wr, R, S>
    where R: io::Read,
          S: Sample
{
    type Item = Result<S>;

    fn next(&mut self) -> Option<Result<S>> {
        iter_next(&mut self.reader)
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        iter_size_hint(&self.reader)
    }
}
```

```rust
impl<R, S> Iterator for WavIntoSamples<R, S>
    where R: io::Read,
          S: Sample
{
    type Item = Result<S>;

    fn next(&mut self) -> Option<Result<S>> {
        iter_next(&mut self.reader)
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        iter_size_hint(&self.reader)
    }
}
```

--------------------------------

### i8 Sample Implementation

Source: https://docs.rs/hound/latest/hound/trait.Sample.html

Implementation of the Sample trait for i8 audio samples. Provides methods for reading, writing, and converting i8 samples.

```rust
impl Sample for i8 {
    fn write<W: Write>(self, writer: &mut W, bits: u16) -> Result<()> { ... }
    fn write_padded<W: Write>(
        self,
        writer: &mut W,
        bits: u16,
        byte_width: u16,
    ) -> Result<()>
    {
        ... 
    }
    fn as_i16(self) -> i16 { ... }
    fn read<R: Read>(
        reader: &mut R,
        fmt: SampleFormat,
        bytes: u16,
        bits: u16,
    ) -> Result<i8> {
        ... 
    }
}
```

--------------------------------

### f32 Sample Implementation

Source: https://docs.rs/hound/latest/hound/trait.Sample.html

Implementation of the Sample trait for f32 audio samples. Provides methods for reading, writing, and converting f32 samples.

```rust
impl Sample for f32 {
    fn write<W: Write>(self, writer: &mut W, bits: u16) -> Result<()> { ... }
    fn write_padded<W: Write>(
        self,
        writer: &mut W,
        bits: u16,
        byte_width: u16,
    ) -> Result<()>
    {
        ... 
    }
    fn as_i16(self) -> i16 { ... }
    fn read<R: Read>(
        reader: &mut R,
        fmt: SampleFormat,
        bytes: u16,
        bits: u16,
    ) -> Result<Self> {
        ... 
    }
}
```

--------------------------------

### Read WAV File with Float Sample Format

Source: https://docs.rs/hound/latest/src/hound/read.rs.html

Opens a WAV file and reads its samples, asserting properties like channel count, sample rate, bits per sample, and sample format. Collects all samples into a Vec<f32>.

```rust
let mut wav_reader = 
WavReader::open("testsamples/waveformatextensible-ieeefloat-44100Hz-mono.wav").unwrap();

assert_eq!(wav_reader.spec().channels, 1);
assert_eq!(wav_reader.spec().sample_rate, 44100);
assert_eq!(wav_reader.spec().bits_per_sample, 32);
assert_eq!(wav_reader.spec().sample_format, SampleFormat::Float);

let samples: Vec<f32> = wav_reader.samples()
                                      .map(|r| r.unwrap())
                                      .collect();

// The test file has been prepared with these exact four samples.
assert_eq!(&samples[..], &[2.0, 3.0, -16411.0, 1019.0]);
```

--------------------------------

### Read WAVE_FORMAT_EXTENSIBLE Chunk

Source: https://docs.rs/hound/latest/src/hound/read.rs.html

Parses the WAVE_FORMAT_EXTENSIBLE chunk, validating its size and extracting the subformat GUID to determine sample format (Int or Float). It also handles fallback for bits_per_sample.

```rust
if chunk_len < 40 {
            return Err(Error::FormatError("unexpected fmt chunk size"));
        }

        let cb_size = try!(reader.read_le_u16());

        if cb_size != 22 {
            return Err(Error::FormatError("unexpected WAVEFORMATEXTENSIBLE size"));
        }

        let valid_bits_per_sample = try!(reader.read_le_u16());
        let _channel_mask = try!(reader.read_le_u32()); 
        let mut subformat = [0u8; 16];
        try!(reader.read_into(&mut subformat));

        let sample_format = match subformat {
            super::KSDATAFORMAT_SUBTYPE_PCM => SampleFormat::Int,
            super::KSDATAFORMAT_SUBTYPE_IEEE_FLOAT => SampleFormat::Float,
            _ => return Err(Error::Unsupported),
        };

        if valid_bits_per_sample > 0 {
            spec.bits_per_sample = valid_bits_per_sample;
        }

        spec.sample_format = sample_format;
        Ok(())
    }
```

--------------------------------

### Iterating mutably over Ok values with iter_mut

Source: https://docs.rs/hound/latest/hound/type.Result.html

Use `iter_mut` to get a mutable iterator that yields a mutable reference to the contained value if the Result is Ok, otherwise yields nothing.

```rust
let mut x: Result<u32, &str> = Ok(7);
match x.iter_mut().next() {
    Some(v) => *v = 40,
    None => {},
}
assert_eq!(x, Ok(40));

let mut x: Result<u32, &str> = Err("nothing!");
assert_eq!(x.iter_mut().next(), None);
```

--------------------------------

### i16 Sample Implementation

Source: https://docs.rs/hound/latest/hound/trait.Sample.html

Implementation of the Sample trait for i16 audio samples. Provides methods for reading, writing, and converting i16 samples.

```rust
impl Sample for i16 {
    fn write<W: Write>(self, writer: &mut W, bits: u16) -> Result<()> { ... }
    fn write_padded<W: Write>(
        self,
        writer: &mut W,
        bits: u16,
        byte_width: u16,
    ) -> Result<()>
    {
        ... 
    }
    fn as_i16(self) -> i16 { ... }
    fn read<R: Read>(
        reader: &mut R,
        fmt: SampleFormat,
        bytes: u16,
        bits: u16,
    ) -> Result<i16> {
        ... 
    }
}
```

--------------------------------

### Get a Reference to the Ok Value

Source: https://docs.rs/hound/latest/hound/type.Result.html

The `as_ref()` method converts a `&Result<T, E>` into a `Result<&T, &E>`, providing immutable references to the contained values without consuming the original `Result`.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.as_ref(), Ok(&2));

let x: Result<u32, &str> = Err("Error");
assert_eq!(x.as_ref(), Err(&"Error"));
```

--------------------------------

### WavWriter::new

Source: https://docs.rs/hound/latest/hound/struct.WavWriter.html

Creates a new WavWriter instance for writing WAVE audio data. It's recommended to wrap the underlying writer in a BufWriter for efficiency.

```APIDOC
## WavWriter::new

### Description
Creates a writer that writes the WAVE format to the underlying writer. The underlying writer is assumed to be at offset 0. `WavWriter` employs _no_ buffering internally. It is recommended to wrap the writer in a `BufWriter` to avoid too many `write` calls. The `create()` constructor does this automatically.
This writes parts of the header immediately, hence a `Result` is returned.

### Signature
```rust
pub fn new(writer: W, spec: WavSpec) -> Result<WavWriter<W>>
```

### Parameters
* `writer`: The underlying writer implementing `Write` and `Seek`.
* `spec`: The `WavSpec` describing the audio properties.
```

--------------------------------

### Get a Mutable Reference to the Value

Source: https://docs.rs/hound/latest/hound/type.Result.html

The `as_mut()` method converts a `&mut Result<T, E>` into a `Result<&mut T, &mut E>`, providing mutable references to the contained values, allowing in-place modification.

```rust
fn mutate(r: &mut Result<i32, i32>) {
    match r.as_mut() {
        Ok(v) => *v = 42,
        Err(e) => *e = 0,
    }
}

let mut x: Result<i32, i32> = Ok(2);
mutate(&mut x);
assert_eq!(x.unwrap(), 42);

let mut x: Result<i32, i32> = Err(13);
mutate(&mut x);
assert_eq!(x.unwrap_err(), 0);
```

--------------------------------

### Open WAV File with BufReader

Source: https://docs.rs/hound/latest/src/hound/read.rs.html

Convenience constructor to open a file, wrap it in a BufReader, and create a WavReader. Use this for standard file operations.

```rust
impl WavReader<io::BufReader<fs::File>> {
    /// Attempts to create a reader that reads from the specified file.
    ///
    /// This is a convenience constructor that opens a `File`, wraps it in a
    /// `BufReader` and then constructs a `WavReader` from it.
    pub fn open<P: AsRef<path::Path>>(filename: P) -> Result<WavReader<io::BufReader<fs::File>>> {
        let file = try!(fs::File::open(filename));
        let buf_reader = io::BufReader::new(file);
        WavReader::new(buf_reader)
    }
}
```

--------------------------------

### Get WAV Spec

Source: https://docs.rs/hound/latest/src/hound/write.rs.html

Returns information about the WAVE file being written, which is the same spec passed to `WavWriter::new()`. For writers constructed with `WavWriter::new_append()` or `WavWriter::append()`, this returns the spec of the file being appended to.

```rust
pub fn spec(&self) -> WavSpec {
        self.spec
    }
```

--------------------------------

### Create and Write a Sine Wave WAV File

Source: https://docs.rs/hound/latest/hound/index.html

Generates a 440 Hz sine wave and saves it as a mono WAV file with specified sample rate and bit depth. Ensure the output file path is valid.

```rust
use std::f32::consts::PI;
use std::i16;
use hound;

let spec = hound::WavSpec {
    channels: 1,
    sample_rate: 44100,
    bits_per_sample: 16,
    sample_format: hound::SampleFormat::Int,
};
let mut writer = hound::WavWriter::create("sine.wav", spec).unwrap();
for t in (0 .. 44100).map(|x| x as f32 / 44100.0) {
    let sample = (t * 440.0 * 2.0 * PI).sin();
    let amplitude = i16::MAX as f32;
    writer.write_sample((sample * amplitude) as i16).unwrap();
}
writer.finalize().unwrap();
```

--------------------------------

### Get WavReader Samples Iterator

Source: https://docs.rs/hound/latest/hound/struct.WavReader.html

Returns a streaming iterator over all samples in the WAVE file. The channel data is interleaved. The type `S` must match the file's bit depth and sample format.

```rust
pub fn samples<'wr, S: Sample>(&'wr mut self) -> WavSamples<'wr, R, S>
```

--------------------------------

### Write and Read i8 Samples Losslessly

Source: https://docs.rs/hound/latest/src/hound/lib.rs.html

Demonstrates writing 8-bit integer samples and reading them back as 16-bit integers, ensuring the operation is lossless.

```rust
#[test]
fn write_read_i8_is_lossless() {
    let mut buffer = io::Cursor::new(Vec::new());
    let write_spec = WavSpec {
        channels: 16,
        sample_rate: 48000,
        bits_per_sample: 8,
        sample_format: SampleFormat::Int,
    };

    // Write `i8` samples.
    {
        let mut writer = WavWriter::new(&mut buffer, write_spec).unwrap();
        // Iterate over i16 because we cannot specify the upper bound otherwise.
        for s in -128_i16..127 + 1 {
            writer.write_sample(s as i8).unwrap();
        }
        writer.finalize().unwrap();
    }

    // Then read them into `i16`.
    {
        buffer.set_position(0);
        let mut reader = WavReader::new(&mut buffer).unwrap();
        assert_eq!(write_spec, reader.spec());
        assert_eq!(reader.len(), 256);
        for (expected, read) in (-128_i16..127 + 1).zip(reader.samples()) {
            assert_eq!(expected, read.unwrap());
        }
    }
}
```

--------------------------------

### map() Method for WavSamples

Source: https://docs.rs/hound/latest/hound/struct.WavSamples.html

Creates a new iterator that applies a closure to each element yielded by WavSamples. This allows for transforming the samples, for example, changing their type or applying a function. This method consumes the original iterator.

```rust
fn map<B, F>(self, f: F) -> Map<Self, F>
where
    Self: Sized,
    F: FnMut(Self::Item) -> B,
```

--------------------------------

### Sample Trait Methods

Source: https://docs.rs/hound/latest/hound/trait.Sample.html

This section details the core methods required by the Sample trait for audio sample manipulation.

```APIDOC
## fn write<W: Write>(self, writer: &mut W, bits: u16) -> Result<()>

### Description
Writes the audio sample to the WAVE data chunk.

### Parameters
- `writer`: A mutable reference to a type implementing the `Write` trait.
- `bits`: The number of bits per sample.

### Returns
- `Result<()>`: Ok(()) on success, or an error if writing fails.
```

```APIDOC
## fn write_padded<W: Write>(self, writer: &mut W, bits: u16, byte_width: u16) -> Result<()>

### Description
Writes the audio sample to the WAVE data chunk, zero padding the size of the written sample out to `byte_width`.

### Parameters
- `writer`: A mutable reference to a type implementing the `Write` trait.
- `bits`: The number of bits per sample.
- `byte_width`: The target byte width to pad the sample to.

### Returns
- `Result<()>`: Ok(()) on success, or an error if writing fails.
```

```APIDOC
## fn read<R: Read>(reader: &mut R, _: SampleFormat, bytes: u16, bits: u16) -> Result<Self>

### Description
Reads the audio sample from the WAVE data chunk.

### Parameters
- `reader`: A mutable reference to a type implementing the `Read` trait.
- `_`: The `SampleFormat` (unused in this signature, often indicates format details).
- `bytes`: The number of bytes representing the sample.
- `bits`: The number of bits per sample.

### Returns
- `Result<Self>`: The decoded audio sample, or an error if reading fails.
```

```APIDOC
## fn as_i16(self) -> i16

### Description
Casts the sample to a 16-bit sample. This operation does not change the value of the sample, it only casts it. The value is assumed to fit within the range; truncation may occur if the value exceeds the range of `i16`.

### Returns
- `i16`: The sample value cast to a 16-bit signed integer.
```

--------------------------------

### WavWriter::new_with_spec_ex

Source: https://docs.rs/hound/latest/src/hound/write.rs.html

Creates a new WavWriter instance using WavSpecEx. This function writes initial header parts and determines the appropriate format (PCMWAVEFORMAT or WAVEFORMATEXTENSIBLE) based on the audio specifications. It's recommended to use BufWriter for the underlying writer.

```rust
pub fn new_with_spec_ex(writer: W, spec_ex: WavSpecEx) -> Result<WavWriter<W>> {
        let spec = spec_ex.spec;

        let fmt_kind = if spec.channels > 2 || spec.bits_per_sample > 16 {
            FmtKind::WaveFormatExtensible
        } else {
            FmtKind::PcmWaveFormat
        };

        let mut writer = WavWriter {
            spec: spec,
            bytes_per_sample: spec_ex.bytes_per_sample,
            writer: writer,
            data_bytes_written: 0,
            sample_writer_buffer: Vec::new(),
            finalized: false,
            data_len_offset: match fmt_kind {
                FmtKind::WaveFormatExtensible => 64,
                FmtKind::PcmWaveFormat => 40,
            },
        };

        // Hound can only write those bit depths. If something else was

```

--------------------------------

### WAV Reader Seek Consistency Test

Source: https://docs.rs/hound/latest/src/hound/read.rs.html

Tests the seek functionality of WavReader across different WAV file formats. It verifies that seeking to the start, last sample, and beyond the audio data behaves as expected.

```rust
let files = &["testsamples/pcmwaveformat-16bit-44100Hz-mono.wav",
                  "testsamples/waveformatex-16bit-44100Hz-stereo.wav",
                  "testsamples/waveformatextensible-32bit-48kHz-stereo.wav"];
    for fname in files {
        let mut reader = WavReader::open(fname).unwrap();

        // Seeking back to the start should "reset" the reader.
        let count = reader.samples::<i32>().count();
        reader.seek(0).unwrap();
        assert_eq!(reader.samples_read, 0);
        assert_eq!(count, reader.samples::<i32>().count());

        // Seek to the last sample.
        let last_time = reader.duration() - 1;
        let channels = reader.spec.channels;
        reader.seek(last_time).unwrap();
        {
            let mut samples = reader.samples::<i32>();
            for _ in 0..channels {
                assert!(samples.next().is_some());
            }
            assert!(samples.next().is_none());
        }

        // Seeking beyond the audio data produces no samples.
        let num_samples = reader.len();
        reader.seek(num_samples).unwrap();
        assert!(reader.samples::<i32>().next().is_none());
        reader.seek(::std::u32::MAX / channels as u32).unwrap();
        assert!(reader.samples::<i32>().next().is_none());
    }
```

--------------------------------

### WavWriter::new

Source: https://docs.rs/hound/latest/src/hound/write.rs.html

Creates a new WavWriter instance. It automatically handles writing initial parts of the WAVE header. It's recommended to wrap the underlying writer in a BufWriter for efficiency. This function returns a Result due to immediate header writes.

```rust
pub fn new(writer: W, spec: WavSpec) -> Result<WavWriter<W>> {
        let spec_ex = WavSpecEx {
            spec: spec,
            bytes_per_sample: (spec.bits_per_sample + 7) / 8,
        };
        WavWriter::new_with_spec_ex(writer, spec_ex)
    }
```

--------------------------------

### WavWriter::new_with_spec_ex

Source: https://docs.rs/hound/latest/hound/struct.WavWriter.html

Creates a new WavWriter instance using an extended specification (WavSpecEx). Similar to `new`, it's recommended to use a BufWriter.

```APIDOC
## WavWriter::new_with_spec_ex

### Description
Creates a writer that writes the WAVE format to the underlying writer. The underlying writer is assumed to be at offset 0. `WavWriter` employs _no_ buffering internally. It is recommended to wrap the writer in a `BufWriter` to avoid too many `write` calls. The `create()` constructor does this automatically.
This writes parts of the header immediately, hence a `Result` is returned.

### Signature
```rust
pub fn new_with_spec_ex(writer: W, spec_ex: WavSpecEx) -> Result<WavWriter<W>>
```

### Parameters
* `writer`: The underlying writer implementing `Write` and `Seek`.
* `spec_ex`: The `WavSpecEx` describing the audio properties.
```
Tokens:
Raw