Crate rotary

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 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.

use rotary::BufMut as _;

let mut dynamic = rotary::dynamic![[0i16; 4]; 2];
let mut interleaved = rotary::interleaved![[0i16; 4]; 2];
let mut sequential = rotary::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 rotary 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 rotary-examples --bin play-mp3 -- path/to/file.mp3

Examples

use rand::Rng as _;

let mut buffer = rotary::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 = rotary::Dynamic::<f32>::with_topology(4, 8);

for channel in &mut buf {
    for f in channel {
        *f = 2.0;
    }
}

assert_eq! {
    buf,
    rotary::dynamic![[2.0; 8]; 4],
};

assert_eq! {
    buf,
    rotary::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 Buf and BufMut.

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

Buf	A trait describing an immutable audio buffer.
BufMut	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.
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.