AudioSamples

Fast, simple, and expressive audio in Rust

Overview

Most audio libraries expose samples as raw numeric buffers. In Python, audio is typically represented as a NumPy array whose dtype is explicit, but whose meaning is not: sample rate, channel layout, amplitude range, memory interleaving, and PCM versus floating-point semantics are tracked externally, if at all. In Rust, the situation is reversed but not resolved. Libraries provide fast and safe low-level primitives, yet users are still responsible for managing raw buffers, writing ad hoc conversion code, and manually preserving invariants across crates.

AudioSamples is designed to close this gap by providing a strongly typed audio representation that makes audio semantics explicit and enforced by construction. Sample format, numeric domain, channel structure, and layout are encoded in the type system, and all operations preserve or explicitly update these invariants.

The result is an API that supports both exploratory workflows and reliable system-level use, without requiring users to remember hidden conventions or reimplement common audio logic.

AudioSamples is the core data and processing layer of the broader audio related crates. It defines the canonical audio object and the operations that act upon it.

Other crates that build on this foundation:

audio_samples_io for decoding and encoding audio containers into typed audio objects
audio_samples_playback for device-level output
audio_samples_python for Python bindings, enabling AudioSamples to act as a type-safe backend for Python workflows
html_view for lightweight visualisation and inspection, generating self-contained HTML outputs suitable for analysis and reporting

NOTE The crate is still a WIP so some features particularly plotting and serialization are not fully complete.

Installation

cargo add audio_samples

See the Features for more details.

Quick Start

Generating and mixing signals

This example generates a sine wave in a target sample format, converts it to floating-point samples, and mixes it with a second signal.

use audio_samples::{
    AudioProcessing, AudioTypeConversion, cosine_wave, operations::types::NormalizationMethod,
    sine_wave,
};
use std::time::Duration;

fn main() {
    let sample_rate = 44_100;
    let duration = Duration::from_secs_f64(1.0);
    let frequency = 440.0;
    let amplitude = 0.5;

    // Generate a sine wave with i16 output samples.
    // The waveform is computed in f32 and converted into i16.
    let pcm_sine = sine_wave::<i16, f32>(frequency, duration, sample_rate, amplitude);

    // Convert to floating-point representation
    let float_sine = pcm_sine.to_format::<f32>();

    // Generate a second signal directly as floating-point samples
    let cosine = cosine_wave::<f32, f32>(frequency / 2.0, duration, sample_rate, amplitude);

    // Mix the two signals
    let mixed = (float_sine + cosine).normalize(-1.0, 1.0, NormalizationMethod::MinMax);
}

Spectral transforms and analysis

AudioSamples supports spectral and time–frequency transforms via the AudioTransforms trait, enabled by the spectral-analysis feature. These operations produce standard frequency-domain and time–frequency representations used in audio analysis and research.

Enable the feature:

cargo add audio_samples --features spectral-analysis

Example: STFT, spectrogram, and MFCC computation

use audio_samples::{
    AudioProcessing, AudioTypeConversion, cosine_wave, operations::types::NormalizationMethod,
    sine_wave,
};
use std::time::Duration;

fn main() {
    let sample_rate = 44_100;
    let duration = Duration::from_secs_f64(1.0);
    let frequency = 440.0;
    let amplitude = 0.5;

    // Generate a sine wave with i16 output samples.
    // The waveform is computed in f32 and converted into i16.
    let pcm_sine = sine_wave::<i16, f32>(frequency, duration, sample_rate, amplitude);

    // Convert to floating-point representation
    let float_sine = pcm_sine.to_format::<f32>();

    // Generate a second signal directly as floating-point samples
    let cosine = cosine_wave::<f32, f32>(frequency / 2.0, duration, sample_rate, amplitude);

    // Mix the two signals
    let mixed = (float_sine + cosine).normalize(-1.0, 1.0, NormalizationMethod::MinMax);
}

Features

Default features

statistics
processing
editing
channels

Major functionality groups

fft
resampling
serialization
plotting

Transform and analysis features

spectral-analysis
beat-detection (requires spectral-analysis)

Plotting sub-features

static-plots (PNG output)

Performance features

parallel-processing
simd (nightly only)
mkl
fixed-size-audio

Utility features

formatting
random-generation
utilities-full

Documentation

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

Examples

A range of examples is included in the repository.

Additional demos include:

DTMF encoder and decoder
Basic synthesis examples
Audio inspection utilities

More advanced I/O and playback examples are provided in the companion crates.

Companion Crates

`audio_samples_io`

Rust crate providing audio file I/O utilities and helpers. audio_samples_io is the IO extension of the audio_samples crate.

`audio_samples_playback`

Device-level playback built on AudioSamples.

`audio_samples_python`

Python bindings exposing AudioSamples, AudioIO and AudioPlayback.

`html_view`

A lightweight, cross-platform HTML viewer for Rust.

html_view provides a minimal, ergonomic API for rendering HTML content in a native window, similar in spirit to matplotlib.pyplot.show() for visualisation rather than UI development.

`dtmf_tones`

A zero-heap, no_std friendly, const-first implementation of the standard DTMF (Dual-Tone Multi-Frequency) keypad used in telephony systems.
This crate provides compile-time safe mappings between keypad keys and their canonical low/high frequencies, along with runtime helpers for practical audio processing.

`i24`

i24 provides a 24-bit signed integer type for Rust, filling the gap between i16 and i32. This type is particularly useful in audio processing, certain embedded systems, and other scenarios where 24-bit precision is required but 32 bits would be excessive

License

MIT License

Contributing

Contributions are welcome. Please submit a pull request and see CONTRIBUTING.md for guidance.

audio_samples 0.10.5