1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

//! [![Documentation](https://docs.rs/audio/badge.svg)](https://docs.rs/audio)
//! [![Crates](https://img.shields.io/crates/v/audio.svg)](https://crates.io/crates/audio)
//! [![Actions Status](https://github.com/udoprog/audio/workflows/Rust/badge.svg)](https://github.com/udoprog/audio/actions)
//!
//! 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][Dynamic] - where each channel is stored in its own
//!   heap-allocated buffer.
//! * [interleaved][Interleaved] - where each channel is interleaved, like
//!   `0:0, 1:0, 1:0, 1:1`.
//! * [sequential][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*.
//!
//! ```rust
//! 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][wrap] 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 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.
//!
//! ```rust
//! 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],
//! };
//! ```
//!
//! [Channels]: https://docs.rs/audio-core/0/audio_core/trait.Channels.html
//! [ChannelsMut]: https://docs.rs/audio-core/0/audio_core/trait.ChannelsMut.html
//! [cpal]: https://github.com/RustAudio/cpal
//! [Dynamic::resize]: https://docs.rs/audio/0.2.0-alpha.3/audio/dynamic/struct.Dynamic.html#method.resize
//! [dynamic!]: https://docs.rs/audio/0.2.0-alpha.3/audio/macros/macro.dynamic.html
//! [Dynamic]: https://docs.rs/audio/0.2.0-alpha.3/audio/dynamic/struct.Dynamic.html
//! [Interleaved]: https://docs.rs/audio/0.2.0-alpha.3/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/0.2.0-alpha.3/audio/sequential/struct.Sequential.html
//! [wrap]: https://docs.rs/audio/0.2.0-alpha.3/audio/wrap/index.html

#![deny(missing_docs, broken_intra_doc_links)]
#![allow(clippy::should_implement_trait)]

#[macro_use]
mod macros;
pub mod buf;
pub mod dynamic;
pub mod interleaved;
pub mod io;
pub mod sequential;
mod utils;
pub mod wrap;

#[cfg(test)]
mod tests;

pub use self::dynamic::Dynamic;
pub use self::interleaved::Interleaved;
pub use self::sequential::Sequential;

pub use audio_core::*;