Crate audio_sample

Crate audio_sample 

Source
Expand description

§Audio Sample Processing & Conversion Crate

A modern, trait-oriented audio processing crate focused on efficient, safe, and composable handling of audio sample sequences.

This library introduces AudioSample as a core trait and builds powerful abstractions around common audio use cases, enabling seamless format conversions, channel layout transformations, numerical array integration, and more.

§Supported Sample Types

  • i16: Standard 16-bit signed PCM
  • I24: 24-bit signed integer audio sample (from the i24 crate)
  • i32: 32-bit signed PCM
  • f32: 32-bit floating-point audio
  • f64: 64-bit floating-point audio

§Key Features

  • Zero-cost abstractions: Efficient trait-based design minimizes allocations and runtime overhead.
  • Safe sample conversions: Conversions between all supported formats, preserving fidelity.
  • Typed iterators: Enhance any Iterator<Item = AudioSample> with extended functionality via the Samples trait.
  • Ergonomic collection APIs: Convert entire buffers (e.g. Vec<i16>, Box<[i32]>) with the ConvertCollection trait.
  • Channel layout support: Convert between interleaved and planar layouts using samples::planar_to_interleaved and samples::interleaved_to_planar.
  • Numerical computing: Transform structured audio into an [ndarray::Array2] matrices for signal processing.

§Implementation Notes

  • Float-to-int: Clamped and rounded into the full range of the target type.
  • Int-to-float: Normalized into the range [-1.0, 1.0].
  • Cross-bit-depth: Preserves perceptual amplitude via scaling.

§Reporting Issues

Found a bug or want a feature? Create an issue at GitHub

§Usage Examples

§Basic Sample Conversion

use audio_sample::{ConvertTo, AudioSample};

let s: i16 = i16::MAX;
let f: f32 = s.convert_to();
assert!(f <= 1.0);

§Converting an Audio Buffer

use audio_sample::ConvertCollection;

let raw: Vec<i16> = vec![0, 16384, -16384, 32767];
let as_f32: Vec<f32> = raw.convert();

§Working with Iterator-Based Samples

use audio_sample::{Samples, ConvertTo};

let raw: Vec<i16> = vec![1, 2, 3];
let sum: f32 = raw.iter().sum::<i16>() as f32;

§Convert to ndarray Matrix

NOTE: Requires the ndarray feature.

#[cfg(feature = "ndarray")]{
use audio_sample::{AudioSample, StructuredSamples, ToNdarray, ChannelLayout};
use ndarray::Array2;

#[derive(Clone, Default)]
struct Interleaved<T> { data: Vec<T>, channels: usize }

impl<T> Iterator for Interleaved<T>
where T: Copy
{
    type Item = T;
    fn next(&mut self) -> Option<T> {
        match self.data.is_empty() {
            true => None,
            false => Some(self.data.remove(0))
        }
    }
}
impl<T: AudioSample> ExactSizeIterator for Interleaved<T> {
    fn len(&self) -> usize {
        self.data.len()
    }
}

impl<T> StructuredSamples for Interleaved<T>
where T: AudioSample
{
    fn layout(&self) -> ChannelLayout { ChannelLayout::Interleaved }
    fn channels(&self) -> usize { self.channels }
}

let data = Interleaved { data: vec![1.0, 10.0, 2.0, 20.0], channels: 2 };
let matrix: Array2<f32> = data.to_ndarray().unwrap();
}

Re-exports§

pub use crate::error::AudioSampleError;
pub use crate::error::AudioSampleResult;
pub use samples::AsSamples;
pub use samples::ConvertCollection;
pub use samples::Samples;
pub use samples::StructuredSamples;

Modules§

error
samples
Samples

Macros§

I24
creates an i24 from a constant expression will give a compile error if the expression overflows an i24

Structs§

I24
A signed 24-bit integer type.

Enums§

ChannelLayout

Traits§

AudioSample
Marker trait for audio sample types.
ConvertTo
Trait for converting one sample type to another.