# audio
[<img alt="github" src="https://img.shields.io/badge/github-udoprog/audio-8da0cb?style=for-the-badge&logo=github" height="20">](https://github.com/udoprog/audio)
[<img alt="crates.io" src="https://img.shields.io/crates/v/audio.svg?style=for-the-badge&color=fc8d62&logo=rust" height="20">](https://crates.io/crates/audio)
[<img alt="docs.rs" src="https://img.shields.io/badge/docs.rs-audio-66c2a5?style=for-the-badge&logoColor=white&logo=data:image/svg+xml;base64,PHN2ZyByb2xlPSJpbWciIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgdmlld0JveD0iMCAwIDUxMiA1MTIiPjxwYXRoIGZpbGw9IiNmNWY1ZjUiIGQ9Ik00ODguNiAyNTAuMkwzOTIgMjE0VjEwNS41YzAtMTUtOS4zLTI4LjQtMjMuNC0zMy43bC0xMDAtMzcuNWMtOC4xLTMuMS0xNy4xLTMuMS0yNS4zIDBsLTEwMCAzNy41Yy0xNC4xIDUuMy0yMy40IDE4LjctMjMuNCAzMy43VjIxNGwtOTYuNiAzNi4yQzkuMyAyNTUuNSAwIDI2OC45IDAgMjgzLjlWMzk0YzAgMTMuNiA3LjcgMjYuMSAxOS45IDMyLjJsMTAwIDUwYzEwLjEgNS4xIDIyLjEgNS4xIDMyLjIgMGwxMDMuOS01MiAxMDMuOSA1MmMxMC4xIDUuMSAyMi4xIDUuMSAzMi4yIDBsMTAwLTUwYzEyLjItNi4xIDE5LjktMTguNiAxOS45LTMyLjJWMjgzLjljMC0xNS05LjMtMjguNC0yMy40LTMzLjd6TTM1OCAyMTQuOGwtODUgMzEuOXYtNjguMmw4NS0zN3Y3My4zek0xNTQgMTA0LjFsMTAyLTM4LjIgMTAyIDM4LjJ2LjZsLTEwMiA0MS40LTEwMi00MS40di0uNnptODQgMjkxLjFsLTg1IDQyLjV2LTc5LjFsODUtMzguOHY3NS40em0wLTExMmwtMTAyIDQxLjQtMTAyLTQxLjR2LS42bDEwMi0zOC4yIDEwMiAzOC4ydi42em0yNDAgMTEybC04NSA0Mi41di03OS4xbDg1LTM4Ljh2NzUuNHptMC0xMTJsLTEwMiA0MS40LTEwMi00MS40di0uNmwxMDItMzguMiAxMDIgMzguMnYuNnoiPjwvcGF0aD48L3N2Zz4K" height="20">](https://docs.rs/audio)
[<img alt="build status" src="https://img.shields.io/github/actions/workflow/status/udoprog/audio/ci.yml?branch=main&style=for-the-badge" height="20">](https://github.com/udoprog/audio/actions?query=branch%3Amain)
A crate for working with audio in Rust.
This is made up of several parts, each can be used independently of each
other:
* [audio-core] - The core crate, which defines traits that allows for
interacting with audio buffers independent of their layout in memory.
* [audio] - This crate, which provides a collection of high-quality audio
buffers which implements the traits provided in [audio-core].
* [audio-device] - A crate for interacting with audio devices in idiomatic
Rust.
* [audio-generator] - A crate for generating audio.
Audio buffers provided by this crate have zero or more channels that can be
iterated over. A channel is simply a sequence of samples. The samples within
each channel at one moment in time are a frame. A buffer can store channels
in various ways in memory, as detailed in the next section.
<br>
## Buffers
This crate provides several structs for storing buffers of multichannel
audio. The examples represent how the two channels `[1, 2, 3, 4]` and `[5,
6, 7, 8]` are stored in memory:
* [Dynamic]: each channel is stored in its own heap allocation. So `[1, 2,
3, 4]` and `[5, 6, 7, 8]`. This may be more performant when resizing
freqently. Generally prefer one of the other buffer types for better CPU
cache locality.
* [Interleaved]: samples of each channel are interleaved in one heap
allocation. So `[1, 5, 2, 6, 3, 7, 4, 8]`.
* [Sequential]: each channel is stored one after the other in one heap
allocation. So `[1, 2, 3, 4, 5, 6, 7, 8]`.
These all implement the [Buf] and [BufMut] traits, allowing library authors
to abstract over any one specific format. The exact channel and frame count
of a buffer is known as its *topology*. The following example allocates
buffers with 4 frames and 2 channels. The buffers are arranged in memory
differently, but data is copied into them using the same API.
```rust
use audio::{BufMut, ChannelMut};
let mut dynamic = audio::dynamic![[0i16; 4]; 2];
let mut interleaved = audio::interleaved![[0i16; 4]; 2];
let mut sequential = audio::sequential![[0i16; 4]; 2];
audio::channel::copy_iter(0i16.., dynamic.get_mut(0).unwrap());
audio::channel::copy_iter(0i16.., interleaved.get_mut(0).unwrap());
audio::channel::copy_iter(0i16.., sequential.get_mut(0).unwrap());
```
We also support [wrapping][wrap] external buffers so that they can
interoperate like other audio buffers.
<br>
## Example: [play-mp3]
Play an mp3 file with [minimp3-rs], [cpal], and [rubato] for resampling.
This example can handle with any channel and sample rate configuration.
```bash
cargo run --release --package audio-examples --bin play-mp3 -- path/to/file.mp3
```
<br>
## Examples
```rust
use rand::Rng;
let mut buf = audio::buf::Dynamic::<f32>::new();
buf.resize_channels(2);
buf.resize_frames(2048);
/// Fill both channels with random noise.
let mut rng = rand::thread_rng();
rng.fill(&mut buf[0]);
rng.fill(&mut buf[1]);
```
For convenience we also provide several macros for constructing various
forms of dynamic audio buffers. These should mostly be used for testing.
```rust
let mut buf = audio::buf::Dynamic::<f32>::with_topology(4, 8);
for mut channel in &mut buf {
for f in channel.iter_mut() {
*f = 2.0;
}
}
assert_eq! {
buf,
audio::dynamic![[2.0; 8]; 4],
};
assert_eq! {
buf,
audio::dynamic![[2.0, 2.0, 2.0, 2.0, 2.0, 2.0, 2.0, 2.0]; 4],
};
```
[audio-core]: https://docs.rs/audio-core
[audio-device]: https://docs.rs/audio-device
[audio-generator]: https://docs.rs/audio-generator
[audio]: https://docs.rs/audio
[Buf]: https://docs.rs/audio-core/latest/audio_core/trait.Buf.html
[BufMut]: https://docs.rs/audio-core/latest/audio_core/trait.BufMut.html
[cpal]: https://github.com/RustAudio/cpal
[Dynamic::resize]: https://docs.rs/audio/latest/audio/dynamic/struct.Dynamic.html#method.resize
[dynamic!]: https://docs.rs/audio/latest/audio/macros/macro.dynamic.html
[Dynamic]: https://docs.rs/audio/latest/audio/dynamic/struct.Dynamic.html
[Interleaved]: https://docs.rs/audio/latest/audio/interleaved/struct.Interleaved.html
[minimp3-rs]: https://github.com/germangb/minimp3-rs
[play-mp3]: https://github.com/udoprog/audio/tree/main/examples/src/bin/play-mp3.rs
[rubato]: https://github.com/HEnquist/rubato
[Sequential]: https://docs.rs/audio/latest/audio/sequential/struct.Sequential.html
[wrap]: https://docs.rs/audio/latest/audio/wrap/index.html