Crate audio_samples

Expand description

§AudioSamples

A typed audio processing library for Rust that treats audio as a first-class, invariant-preserving object rather than an unstructured numeric buffer. is this library?

audio_samples provides a single central type, AudioSamples<T>, that pairs raw PCM data (backed by ndarray) with essential metadata: sample rate, channel count, and memory layout. Every audio processing operation in the library is defined as a trait method on this type, ensuring that metadata travels with the data throughout a processing pipeline. does this library exist?

Low-level audio APIs in Rust typically expose bare slices or Vec<f32> buffers, leaving metadata management to the caller. This encourages subtle bugs such as mismatched sample rates after resampling, or interleaved/non-interleaved confusion when passing buffers between components. audio_samples eliminates these error classes by encoding invariants directly into the type. should it be used?

Start by creating an AudioSamples<T> from an ndarray or from one of the built-in signal generators (see utils::generation), then chain trait methods for any further processing. Feature flags keep the dependency footprint small – only enable what your application needs.

§Installation

cargo add audio_samples

§Features

The library uses a modular feature flag system. Only enable what you need.

Feature	Description
`statistics`	Peak, RMS, variance, zero-crossings, and other statistical measures
`processing`	Normalise, scale, clip, DC offset removal, and other sample-level operations (implies `statistics`)
`editing`	Time-domain editing: trim, pad, reverse, concatenate, fade (implies `statistics`, `random-generation`)
`channels`	Channel operations: mono↔stereo conversion, channel extraction, interleave/deinterleave
`transforms`	Spectrogram and frequency-domain transforms via the `spectrograms` crate
`iir-filtering`	IIR filter design and application (Butterworth, Chebyshev I)
`parametric-eq`	Multi-band parametric equaliser (implies `iir-filtering`)
`dynamic-range`	Compression, limiting, and expansion with side-chain support
`envelopes`	Amplitude, RMS, and analytical envelope followers (implies `dynamic-range`, `editing`, `random-generation`)
`peak-picking`	Onset strength curve peak picking
`onset-detection`	Onset detection (implies `transforms`, `peak-picking`, `processing`)
`beat-tracking`	Beat tracking and tempo estimation
`decomposition`	Audio source decomposition (implies `onset-detection`)
`pitch-analysis`	YIN and autocorrelation pitch detection (implies `transforms`)
`vad`	Voice activity detection
`resampling`	High-quality resampling via the `rubato` crate
`plotting`	Signal plotting via `plotly`
`fixed-size-audio`	Stack-allocated fixed-size audio buffers
`random-generation`	Noise generators and stochastic signal sources (implies `rand`)
`full`	Enables all of the above

See Cargo.toml for the complete dependency graph.

§Error Handling

All fallible operations return AudioSampleResult<T>, which is an alias for Result<T, AudioSampleError>. Errors are structured so that the variant indicates the category of failure and the inner type provides detail.

use audio_samples::{AudioSampleError, AudioSampleResult, ParameterError};

let audio_result: AudioSampleResult<()> = Err(AudioSampleError::Parameter(
    ParameterError::invalid_value("window_size", "must be > 0"),
));

match audio_result {
    Ok(()) => {}
    Err(AudioSampleError::Conversion(err)) => eprintln!("Conversion failed: {err}"),
    Err(AudioSampleError::Parameter(err)) => eprintln!("Invalid parameter: {err}"),
    Err(other_err) => eprintln!("Other error: {other_err}"),
}

§Full Examples

Examples live in the repository (see examples/) and in the crate-level docs on https://docs.rs/audio_samples.

§Quick Start

§Creating Audio Data

use audio_samples::{AudioSamples, sample_rate};
use ndarray::array;

// Create mono audio
let data = array![0.1f32, 0.5, -0.3, 0.8, -0.2];
let audio = AudioSamples::new_mono(data, sample_rate!(44100)).unwrap();

// Create stereo audio (channels × samples)
let stereo_data = array![
    [0.1f32, 0.5, -0.3],  // Left channel
    [0.8f32, -0.2, 0.4]   // Right channel
];
let stereo_audio = AudioSamples::new_multi_channel(stereo_data, sample_rate!(44100)).unwrap();

§Basic Statistics

Requires the statistics feature.

use audio_samples::{AudioStatistics, sine_wave, sample_rate};
use std::time::Duration;

// Generate a 440 Hz sine wave at 44.1 kHz sample rate, amplitude 1.0
let audio = sine_wave::<f32>(440.0, Duration::from_secs_f32(1.0), sample_rate!(44100), 1.0);

let peak           = audio.peak();
let min            = audio.min_sample();
let max            = audio.max_sample();
let mean           = audio.mean();
let rms            = audio.rms().unwrap();
let variance       = audio.variance().unwrap();
let zero_crossings = audio.zero_crossings();

§Processing Operations

Requires the processing feature.

use audio_samples::{AudioProcessing, NormalizationConfig, AudioSamples, sample_rate};
use ndarray::array;

let data = array![0.1f32, 0.5, -0.3, 0.8, -0.2];
let audio = AudioSamples::new_mono(data, sample_rate!(44100)).unwrap();

// Method chaining: each operation consumes and returns Self
let audio = audio
    .normalize(NormalizationConfig::peak(1.0))
    .unwrap()
    .scale(0.5)
    .remove_dc_offset()
    .unwrap();

§Type Conversions

use audio_samples::{AudioSamples, AudioTypeConversion, sample_rate};
use ndarray::array;

let audio_f32 = AudioSamples::new_mono(array![1.0f32, 2.0, 3.0], sample_rate!(44100)).unwrap();
let audio_i16 = audio_f32.clone().to_type::<i16>();
let audio_f64 = audio_f32.to_type::<f64>();

§Iterating Over Audio Data

use audio_samples::{AudioSampleIterators, AudioSamples, sample_rate};
use ndarray::array;

let audio = AudioSamples::new_mono(
    array![1.0f32, 2.0, 3.0, 4.0],
    sample_rate!(44100),
).unwrap();

// Iterate by frames (one sample per channel per time step)
for frame in audio.frames() {
    println!("Frame: {:?}", frame);
}

// Iterate by channels
for channel in audio.channels() {
    println!("Channel: {:?}", channel);
}

§Core Type System

§Supported Sample Types

Type	Width	Notes
`u8`	8-bit unsigned	Mid-scale (128) represents silence
`i16`	16-bit signed	CD-quality audio
`I24`	24-bit signed	From the `i24` crate
`i32`	32-bit signed	High-dynamic-range integer audio
`f32`	32-bit float	Most DSP operations use this type
`f64`	64-bit float	High-precision processing

§Type System Traits

AudioSample – Core trait all sample types implement. Provides constants (MAX, MIN, BITS, BYTES, LABEL) and low-level byte operations.
ConvertTo<T> / ConvertFrom<T> – Audio-aware conversions with correct scaling between bit depths (e.g. i16 → f32 normalises to [-1.0, 1.0]).
CastFrom<T> / CastInto<T> – Raw numeric casts without scaling. Use these when you need the raw integer value as a float for computation, not as an audio amplitude.
AudioTypeConversion – High-level conversion methods on AudioSamples<T> such as as_f32(), as_i16(), and as_type::<U>().

§Signal Generation

The utils::generation module provides functions for creating test and reference signals: sine_wave, cosine_wave, square_wave, triangle_wave, sawtooth_wave, chirp, impulse, silence, compound_tone, and am_signal.

use audio_samples::{sine_wave, sample_rate};
use audio_samples::utils::comparison;
use std::time::Duration;

let a = sine_wave::<f32>(440.0, Duration::from_secs(1), sample_rate!(44100), 1.0);
let b = sine_wave::<f32>(440.0, Duration::from_secs(1), sample_rate!(44100), 1.0);
let corr: f64 = comparison::correlation(&a, &b).unwrap();
assert!(corr > 0.99);

§Documentation

Full API documentation is available at docs.rs/audio_samples.

§License

MIT

§Contributing

Contributions are welcome. Please open an issue or pull request on GitHub.

Re-exports§

pub use crate::traits::AudioSample;
pub use crate::traits::AudioTypeConversion;
pub use crate::traits::CastFrom;
pub use crate::traits::CastInto;
pub use crate::traits::ConvertFrom;
pub use crate::traits::ConvertTo;
pub use crate::traits::StandardSample;
pub use crate::iterators::AudioSampleIterators;
pub use crate::iterators::ChannelIterator;
pub use crate::iterators::FrameIterator;
pub use crate::iterators::PaddingMode;
pub use crate::utils::generation::ToneComponent;
pub use crate::utils::generation::am_signal;
pub use crate::utils::generation::chirp;
pub use crate::utils::generation::compound_tone;
pub use crate::utils::generation::cosine_wave;
pub use crate::utils::generation::impulse;
pub use crate::utils::generation::sawtooth_wave;
pub use crate::utils::generation::silence;
pub use crate::utils::generation::sine_wave;
pub use crate::utils::generation::square_wave;
pub use crate::utils::generation::triangle_wave;

Modules§

conversions: Audio sample type conversion utilities. is this module?
iterators: Structured iteration over audio sample data.
operations: Audio processing operations and transformations.
simd_conversions: SIMD-optimized audio sample conversions.
traits: Core trait definitions for audio sample types and operations.
utils: Utility functions and helpers for audio processing.

Macros§

channels: Creates a NonZeroU32 channel count from a compile-time constant.
nzu: Creates a NonZeroUsize from a compile-time constant with zero-check.
sample_rate: Creates a NonZeroU32 sample rate from a compile-time constant.

Structs§

AudioSamples: Represents homogeneous audio samples with associated metadata.
I24: A signed 24-bit integer type.
StereoAudioSamples: A newtype wrapper around AudioSamples that guarantees exactly two channels (stereo).

Enums§

AudioData: Channel-agnostic container for raw audio sample data.
AudioSampleError: Root error type for all audio sample operations.
ConversionError: Errors that occur during type conversion and casting operations.
FeatureError: Errors related to missing or disabled cargo features.
LayoutError: Errors related to memory layout, array structure, and data organization.
NdResult: A tagged result that is either a 1-D mono array or a 2-D multi-channel array.
ParameterError: Errors related to invalid parameters, ranges, or configuration values.
ProcessingError: Errors that occur during audio processing operations.
SampleType: Identifies the numeric type used to represent individual audio samples.

Traits§

PackedStruct: A trait for types that can be read from and written to packed byte representations.

Type Aliases§

AudioSampleResult: Convenience alias for any Result that may fail with AudioSampleError.