Crate audio

A library for working with audio buffers

The buffer is constructed similarly to a Vec<Vec<T>>, except the interior vector has a fixed size. And the buffer makes no attempt to clear data which is freed when using functions such as Dynamic::resize.

Formats and topologies

The following are the three canonical audio formats which are supported by this library:

• dynamic - where each channel is stored in its own heap-allocated buffer.
• interleaved - where each channel is interleaved, like 0:0, 1:0, 1:0, 1:1.
• sequential - where each channel is stored in a linear buffer, one after another. Like 0:0, 0:1, 1:0, 1:0.

These all implement the Channels and ChannelsMut 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.

use audio::ChannelsMut as _;

let mut dynamic = audio::dynamic![[0i16; 4]; 2];
let mut interleaved = audio::interleaved![[0i16; 4]; 2];
let mut sequential = audio::sequential![[0i16; 4]; 2];

dynamic.channel_mut(0).copy_from_iter(0i16..);
interleaved.channel_mut(0).copy_from_iter(0i16..);
sequential.channel_mut(0).copy_from_iter(0i16..);

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.

cargo run --release --package audio-examples --bin play-mp3 -- path/to/file.mp3

Examples

use rand::Rng as _;

let mut buffer = audio::Dynamic::<f32>::new();

buffer.resize_channels(2);
buffer.resize(2048);

/// Fill both channels with random noise.
let mut rng = rand::thread_rng();
rng.fill(&mut buffer[0]);
rng.fill(&mut buffer[1]);

For convenience we also provide several macros for constructing various forms of dynamic audio buffers. These should mostly be used for testing.

let mut buf = audio::Dynamic::<f32>::with_topology(4, 8);

for channel in &mut buf {
    for f in channel {
        *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],
};

Re-exports

pub use self::dynamic::Dynamic;

pub use self::interleaved::Interleaved;

pub use self::sequential::Sequential;

Modules

buf	Utilities for working with buffers.
dynamic	A dynamically sized, multi-channel audio buffer.
interleaved	A dynamically sized, multi-channel interleaved audio buffer.
io	Reading and writing sequentially from buffers.
sequential	A dynamically sized, multi-channel sequential audio buffer.
wrap	Wrap an external type to implement Channels and ChannelsMut.

Macros

dynamic	Construct an audio buffer.
interleaved	Construct an interleaved audio buffer.
sequential	Construct a sequential audio buffer.

Structs

Channel	The buffer of a single channel.
ChannelMut	The mutable buffer of a single channel.

Traits

AsInterleaved	A trait describing a buffer that is interleaved.
AsInterleavedMut	A trait describing a buffer that is interleaved and mutable.
Buf	The base trait available to all audio buffers.
Channels	A trait describing something that has channels.
ChannelsMut	A trait describing a mutable audio buffer.
ExactSizeBuf	Trait used to describe a buffer that knows exactly how many frames it has regardless of if it’s sized or not.
InterleavedBuf	Trait implemented for buffers which are linearly stored in memory.
ReadBuf	Trait used to govern sequential reading of an audio buffer.
ResizableBuf	Trait implemented for buffers that can be resized.
Sample	A sample that can be stored in an audio buffer. Types implementing this are known as being sample apt.
Translate	Trait used for translating one sample type to another.
WriteBuf	Trait used to govern sequential writing to an audio buffer.