audio

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 safely interacting with audio buffers.
• [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. This can be stored using different topologies as appropriate which will be detailed in the next section.

Formats and topologies

The following are the three canonical audio formats which are supported by this crate. All of the examples represent how the two channels [1, 2, 3, 4] and [5, 6, 7, 8] are stored:

• dynamic - where each channel is stored in its own heap-allocated buffer. Each channel is stored sequentially in their own allocations. So [1, 2, 3, 4] and [5, 6, 7, 8]. Having separate allocations for each channel can be useful if the topologies of the buffers keep frequently changing since changing the number of channels does not require any re-allocation of existing ones.
• interleaved - where each channel is interleaved into one buffer. So [1, 5, 2, 6, 3, 7, 4, 8].
• sequential - where each channel is stored in a linear buffer, one after another. 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.

```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::copyiter(0i16.., dynamic.getmut(0).unwrap()); audio::channel::copyiter(0i16.., interleaved.getmut(0).unwrap()); audio::channel::copyiter(0i16.., sequential.getmut(0).unwrap()); ```

We also support wrapping external buffers so that they can interoperate like other audio buffers.

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

Examples

```rust use rand::Rng;

let mut buf = audio::buf::Dynamic::::new();

buf.resize_channels(2); buf.resize(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::::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], }; ```