Crate audio_samples

Expand description

§AudioSamples

A high-performance audio processing library for Rust that provides type-safe sample format conversions, statistical analysis, and various audio processing operations.

§Overview

§Installation

Add this to your Cargo.toml:

[dependencies]
audio_samples = "0.10.0"

or more easily with:

cargo add audio_samples

For specific features, enable only what you need:

[dependencies]
audio_samples = { version = "*", features = ["fft", "plotting"] }

Or enable everything:

[dependencies]
audio_samples = { version = "*", features = ["full"] }

§Features

The library uses a modular feature system to keep dependencies minimal:

statistics: statistics utilities (peak, RMS, variance, etc.)
processing: processing operations (normalize, scale, clip, etc.)
editing: time-domain editing operations (trim, pad, reverse, etc.)
channels: channel operations (mono/stereo conversion)
fft: FFT-backed transforms (adds FFT dependencies)
plotting: plotting utilities (adds signal plotting dependencies)
resampling: resampling utilities (using rubato crate)
serialization: serialization utilities (using serde crate)

See Cargo.toml for the complete feature list and feature groups.

§Error Handling

The library uses a hierarchical error system designed for precise error handling:

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;
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, 44100);

// Create stereo audio
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, 44100);

§Basic Statistics

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

// frequency, sample rate, duration, amplitude
// <f32, f32> indicates the sine wave will be
// generated using single float precision and
// the resulting samples will also be f32
let audio = sine_wave::<f32, f32>(440.0, Duration::from_secs_f32(1.0), 44100, 1.0);
// Simple statistics
let peak = audio.peak();
let min = audio.min_sample();
let max = audio.max_sample();
let mean = audio.mean();

// More complex statistics (return Result)
let rms = audio.rms().unwrap();
let variance = audio.variance().unwrap();
let zero_crossings = audio.zero_crossings();

§Processing Operations

use audio_samples::{AudioProcessing, NormalizationMethod};
use ndarray::array;

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

// Basic processing (in-place)
audio
    .normalize(-1.0, 1.0, NormalizationMethod::Peak)
    .unwrap();
audio.scale(0.5); // Reduce volume by half
audio.remove_dc_offset();

§Type Conversions

use audio_samples::AudioSamples;
use ndarray::array;

// Convert between sample types
let audio_f32 = AudioSamples::new_mono(array![1.0f32, 2.0, 3.0], 44100);
let audio_i16 = audio_f32.as_type::<i16>().unwrap();
let audio_f64 = audio_f32.as_type::<f64>().unwrap();

§Iterating Over Audio Data

use audio_samples::AudioSampleIterators;
use ndarray::array;

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

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

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

// Windowed iteration for analysis
for window in audio.windows(1024, 512) {
    // Process 1024-sample windows with 50% overlap
    let window_rms = window.rms().unwrap();
    println!("Window RMS: {:.3}", window_rms);
}

§Builder Pattern for Complex Processing

For more complex operations, use the fluent builder API:

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

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

// Chain multiple operations
audio.processing()
    .normalize(-1.0, 1.0, NormalizationMethod::Peak)
    .scale(0.8)
    .remove_dc_offset()
    .apply()
    .unwrap();

§Core Type System

§Supported Sample Types

i16 - 16-bit signed integer
I24 - 24-bit signed integer (from i24 crate)
i32 - 32-bit signed integer
f32 - 32-bit floating point
f64 - 64-bit floating point

§Type System Traits

The library provides a rich trait system for working with different audio sample types:

§`AudioSample` Trait

Core trait that all audio sample types implement. Provides common operations and constraints needed for audio processing.

§Conversion Traits

ConvertTo<T> - Type-safe conversions between audio sample types with proper scaling
- i16 -> f32: Normalized to -1.0 to 1.0 range
- f32 -> i16: Scaled and clamped to integer range
- Handles bit depth differences automatically
CastFrom<T> / CastInto<T> - Direct type casting without audio-specific scaling
- For computational operations where you need the raw numeric value
- Example: i16 sample 1334 casts to f32 as 1334.0 (not normalized)
- Use when you need to work with samples as regular numbers, not audio values

§Utility Functions

The utils module provides convenient functions for common audio tasks:

§Signal Generation (`utils::generation`)

Test Signals: generate_sine(), generate_white_noise(), generate_chirp()
Complex Signals: generate_multi_tone() for multiple frequencies
Calibration: Known reference signals for testing

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

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

§Documentation

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

§License

MIT License

§Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Re-exports§

pub use crate::iterators::AudioSampleIterators;
pub use crate::iterators::ChannelIterator;
pub use crate::iterators::ChannelIteratorMut;
pub use crate::iterators::FrameIterator;
pub use crate::iterators::FrameIteratorMut;
pub use crate::iterators::FrameMut;
pub use crate::iterators::PaddingMode;
pub use crate::iterators::WindowIterator;
pub use crate::iterators::WindowIteratorMut;
pub use crate::iterators::WindowMut;
pub use crate::operations::AudioStatistics;
pub use crate::operations::AudioProcessing;
pub use crate::operations::NormalizationMethod;
pub use crate::operations::AudioEditing;
pub use crate::operations::AudioChannelOps;
pub use crate::traits::AudioSample;
pub use crate::traits::AudioTypeConversion;
pub use crate::traits::CastFrom;
pub use crate::traits::CastInto;
pub use crate::traits::Castable;
pub use crate::traits::ConvertTo;
pub use crate::utils::audio_math::amplitude_to_db;
pub use crate::utils::audio_math::db_to_amplitude;
pub use crate::utils::audio_math::fft_frequencies;
pub use crate::utils::audio_math::frames_to_time;
pub use crate::utils::audio_math::hz_to_mel;
pub use crate::utils::audio_math::hz_to_midi;
pub use crate::utils::audio_math::mel_scale;
pub use crate::utils::audio_math::mel_to_hz;
pub use crate::utils::audio_math::midi_to_hz;
pub use crate::utils::audio_math::midi_to_note;
pub use crate::utils::audio_math::note_to_midi;
pub use crate::utils::audio_math::power_to_db;
pub use crate::utils::audio_math::time_to_frames;
pub use crate::utils::comparison;
pub use crate::utils::detection;
pub use crate::utils::generation::ToneComponent;
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::multichannel_compound_tone;
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::stereo_chirp;
pub use crate::utils::generation::stereo_silence;
pub use crate::utils::generation::stereo_sine_wave;
pub use crate::utils::generation::triangle_wave;
pub use crate::utils::samples_to_seconds;
pub use crate::utils::seconds_to_samples;
pub use crate::utils::generation::brown_noise;
pub use crate::utils::generation::pink_noise;
pub use crate::utils::generation::white_noise;

Modules§

conversions: Audio Sample Type Conversions
iterators: Iterators and iterator-like helpers over audio samples.
operations: Audio processing operations and transformations.
simd_conversions: SIMD-optimized audio sample conversions.
traits: Core traits for audio processing.
utils: Utility functions and helpers for audio processing.

Macros§

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 wrapper for AudioSamples that guarantees exactly 2 channels (stereo).

Enums§

AudioBytes: Borrowed-or-owned byte view returned by AudioData::bytes.
AudioData: Storage container for audio sample data.
AudioSampleError: Main error type for audio sample operations.
ChannelLayout: Describes how multi-channel audio data is organized in memory
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.
ParameterError: Errors related to invalid parameters, ranges, or configuration values.
ProcessingError: Errors that occur during audio processing operations.
SampleType: Audio sample data types

Constants§

LEFT: Left channel index.
RIGHT: Right channel index.
SUPPORTED_DTYPES: Array of supported audio sample data types as string identifiers

Traits§

PackedStruct: A trait for types that can be read from and written to packed byte representations.
RealFloat: Marker trait for real floating-point types (f32, f64)

Functions§

to_precision: Casts a numeric value into the target floating-point type F.

Type Aliases§

AudioSampleResult: Convenience type alias for results that may contain AudioSampleError
NonZeroU32: A u32 that is known not to equal zero.
NonZeroUsize: A usize that is known not to equal zero.