<div align="center">

# audio_samples_io

## Fast and simple audio reading and writing in Rust

<img src="logo.png" title="AudioSamples Logo -- Ferrous' Mustachioed Cousin From East Berlin, Eisenhaltig" width="200"/>

[![Crates.io][crate-img]][crate] [![Docs.rs][docs-img]][docs] [![License: MIT][license-img]][license]
</div>

Rust crate providing audio file I/O utilities and helpers.

`audio_samples_io` is the IO extension of the [audio_samples](https://crates.io/crates/audio_samples) crate.
`audio_samples_io` builds on top of the representations provided by `audio_samples` to provide the functionality necessary for reading, writing and investigating audio files.

## NOTE: Still under development

Currently only supports `.wav` files

- flac
- mp3
- aiff
- ogg
- aac

## Quick start

Install via:

```bash
cargo add audio_samples_io
```

```rust
use std::time::Duration;

use audio_samples_io::error::AudioIOResult;
use audio_samples::{AudioSamples, sine_wave};

pub fn main() -> AudioIOResult<()> {
    // create and write a basic signal and read it back
    let sine_wave: AudioSamples<f32> =
        sine_wave::<_, f32>(440.0, Duration::from_secs_f64(10.0), 44100, 1.0);
    audio_samples_io::write("./sine_wave.wav", &sine_wave)?;

    let read_sine_wave: AudioSamples<f32> = audio_samples_io::read("./sine_wave.wav")?;
    println!("{:#}", read_sine_wave);
    println!("Duration: {:.1}s", read_sine_wave.duration_seconds::<f32>());
    Ok(())
}
```

## Benchmarks

Checkout the [benchmark summary](./benchmark_summary.md) doc for a comparison against [Hound](https://crates.io/crates/hound) and [libsndfile](https://libsndfile.github.io/libsndfile/).

To run the benchmarks (Criterion) reading and writing.

```bash
cargo bench --bench wav_rw
```

I have included a small benchmark reported binary for collating benchmarks to a markdown file

```bash
cargo run --bin benchmark_reporter --features benchmark_reporting
```

## Output files

- `benchmark_report.md` — Markdown summary generated by the reporter binary
- `benchmark_results.csv` — Detailed CSV export of benchmark rows (times in μs)
- `benchmark_summary.csv` — Executive summary CSV

## License

MIT License

---

## Contributing

Contributions are welcome. Please submit a pull request and see
[CONTRIBUTING.md](CONTRIBUTING.md) for guidance.

[crate]: https://crates.io/crates/audio_samples_io  
[crate-img]: https://img.shields.io/crates/v/audio_samples_io?style=for-the-badge&color=009E73&label=crates.io

[docs]: https://docs.rs/audio_samples_io  
[docs-img]: https://img.shields.io/badge/docs.rs-online-009E73?style=for-the-badge&labelColor=gray

[license-img]: https://img.shields.io/crates/l/audio_samples_io?style=for-the-badge&label=license&labelColor=gray  
[license]: https://github.com/jmg049/audio_samples_io/blob/main/LICENSE
