Struct StereoAudioSamples 

pub struct StereoAudioSamples<'a, T: AudioSample>(pub AudioSamples<'a, T>);

A wrapper for AudioSamples that guarantees exactly 2 channels (stereo).

Tuple Fields

0: AudioSamples<'a, T>

Implementations

impl<'a, T: AudioSample> StereoAudioSamples<'a, T>

pub fn new( stereo_data: AudioData<'a, T>, sample_rate: u32, ) -> AudioSampleResult<Self>

Creates a new StereoAudioSamples from audio data with exactly 2 channels.

Errors

Returns an error if stereo_data is mono or has a channel count other than 2.

pub fn with_channels<F, R>(&self, f: F) -> AudioSampleResult<R>

where F: FnOnce(AudioSamples<'_, T>, AudioSamples<'_, T>) -> AudioSampleResult<R>,

Safely access individual channels with borrowed references for efficient processing.

This method provides zero-copy access to the left and right channels, allowing efficient operations like STFT on individual channels without data duplication.

Arguments

• f - Closure that receives borrowed left and right channel data

Returns

The result of the closure operation

Example

let stereo_data = array![[0.1f32, 0.2, 0.3], [0.4, 0.5, 0.6]];
let audio = AudioSamples::new_multi_channel(stereo_data, 44100);
let stereo: StereoAudioSamples<'static, f32> = StereoAudioSamples::try_from(audio)?;

stereo.with_channels(|left, right| {
    // left and right are borrowed AudioSamples<'_, f32>
    println!("Left channel samples: {}", left.len());
    println!("Right channel samples: {}", right.len());
    Ok(())
})?;

Methods from Deref<Target = AudioSamples<'a, T>>

pub fn apply_with_error<F>(&mut self, f: F) -> AudioSampleResult<()>

where F: Fn(T) -> AudioSampleResult<T>,

Applies a fallible function to all samples in the audio data. This is a helper method for operations that can fail.

Examples

// Apply a conversion that might fail
audio.apply_with_error(|sample| {
    if sample > max_value {
        Err(AudioSampleError::Parameter(/* error */))
    } else {
        Ok(sample * 2.0)
    }
})?;

pub fn try_fold<F, Acc>(&mut self, acc: Acc, f: F) -> AudioSampleResult<Acc>

where F: FnMut(&mut Acc, T) -> AudioSampleResult<T>,

Applies a fallible function that uses an accumulator pattern. Useful for operations that need to maintain state across samples.

Examples

let mut state = 0.0;
audio.try_fold(|acc, sample| {
    *acc += sample.abs();
    if *acc > threshold {
        Err(AudioSampleError::Parameter(/* error */))
    } else {
        Ok(sample)
    }
})?;

pub fn frames(&'a self) -> FrameIterator<'a, T>

Returns an iterator over frames (one sample from each channel).

Returns

A FrameIterator yielding borrowed frame views.

Panics

Does not panic.

pub fn channels<'iter>(&'iter self) -> ChannelIterator<'iter, 'a, T>

Returns an iterator over complete channels.

Returns

A ChannelIterator yielding owned AudioSamples values (one per channel).

Panics

Does not panic.

pub fn windows( &'a self, window_size: usize, hop_size: usize, ) -> WindowIterator<'a, T>

Returns an iterator over windows of audio data.

The default padding mode is PaddingMode::Zero.

Inputs

• window_size: size of each window in samples (per channel)
• hop_size: number of samples to advance between windows

Returns

A WindowIterator yielding owned windows.

Panics

Does not panic. If window_size == 0 or hop_size == 0, the iterator yields no items.

pub fn frames_mut(&'a mut self) -> FrameIteratorMut<'a, T>

Returns a mutable iterator over frames (one sample from each channel).

Panics

Panics if the underlying multi-channel storage is not contiguous in memory.

pub fn channels_mut(&'a mut self) -> ChannelIteratorMut<'a, T>

Returns a mutable iterator over complete channels.

Panics

Panics if the underlying multi-channel storage is not contiguous in memory.

pub fn windows_mut( &'a mut self, window_size: usize, hop_size: usize, ) -> WindowIteratorMut<'a, T>

Returns a mutable iterator over non-overlapping windows of audio data.

Panics

• Panics if hop_size < window_size and more than one window would be yielded.
• Panics if the underlying multi-channel storage is not contiguous in memory.

If window_size == 0 or hop_size == 0, the iterator yields no items.

pub fn apply_to_frames<F>(&mut self, f: F)

where F: FnMut(usize, &mut [T]),

Applies a function to each frame without borrowing issues.

For mono audio, the callback receives a mutable slice of length 1.

For multi-channel audio, the callback receives a temporary buffer containing exactly one sample per channel. The buffer is ordered by channel index and is copied back into the underlying audio after the callback returns.

Inputs

• f(frame_index, frame_samples)

Returns

()

Panics

Does not panic.

pub fn try_apply_to_channel_data<F>(&mut self, f: F) -> AudioSampleResult<()>

where F: FnMut(usize, &mut [T]),

Applies a function to each channel’s raw data without borrowing issues.

Inputs

• f(channel_index, channel_samples)

Returns

Ok(()) on success.

Errors

Returns AudioSampleError::Layout if the underlying storage is not contiguous.

pub fn apply_to_channel_data<F>(&mut self, f: F)

where F: FnMut(usize, &mut [T]),

Applies a function to each channel’s raw data without borrowing issues.

This is the infallible counterpart to AudioSamples::try_apply_to_channel_data.

Panics

Panics if the underlying storage is not contiguous in memory.

pub fn apply_to_windows<F>(&mut self, window_size: usize, hop_size: usize, f: F)

where F: FnMut(usize, &mut [T]),

Applies a function to each window without borrowing issues.

For mono audio, the callback receives a mutable slice into the underlying buffer.

For multi-channel audio, the callback receives a temporary interleaved buffer of length window_size * num_channels that is copied back after the callback returns.

Inputs

• window_size: size of each window in samples (per channel)
• hop_size: number of samples to advance between windows
• f(window_index, window_samples)

Panics

Does not panic. If window_size == 0 or the audio is empty, this method returns immediately.

pub fn convert_to<O: AudioSample>(&self) -> AudioSamples<'static, O>

where T: ConvertTo<O>,

Convert audio samples to another sample type.

pub fn to_interleaved_vec(&self) -> Vec<T>

Convert the AudioSamples struct into a vector of samples in interleaved format.

pub fn layout_mut(&mut self) -> &mut ChannelLayout

Returns a mutable reference to the channel layout

pub fn set_layout(&mut self, layout: ChannelLayout)

Sets the channel layout

pub fn info(&self) -> (usize, usize, f64, u32, ChannelLayout)

Returns basic info: (num_channels, samples_per_channel, duration_seconds, sample_rate, layout)

pub fn sample_rate(&self) -> NonZeroU32

Returns the sample rate in Hz as a NonZeroU32.

This is guaranteed to be non-zero by construction.

Examples

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

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

pub fn sample_rate_hz(&self) -> u32

Returns the sample rate as a plain u32.

This is a convenience method equivalent to self.sample_rate().get().

pub fn num_channels(&self) -> usize

Returns the number of channels.

This is guaranteed to be ≥ 1 by construction.

pub fn num_channels_nonzero(&self) -> NonZeroUsize

Returns the number of channels as a NonZeroUsize.

This provides a compile-time guarantee that the value is non-zero, eliminating the need for runtime validation in downstream code.

Examples

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

let audio = AudioSamples::new_mono(array![1.0f32, 2.0], sample_rate!(44100));
let channels = audio.num_channels_nonzero();
assert_eq!(channels.get(), 1);

pub fn samples_per_channel(&self) -> usize

Returns the number of samples per channel.

This is guaranteed to be ≥ 1 by construction (empty audio is not allowed).

pub fn samples_per_channel_nonzero(&self) -> NonZeroUsize

Returns the number of samples per channel as a NonZeroUsize.

This provides a compile-time guarantee that the value is non-zero, eliminating the need for runtime validation in downstream code.

Examples

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

let audio = AudioSamples::new_mono(array![1.0f32, 2.0, 3.0], sample_rate!(44100));
let samples = audio.samples_per_channel_nonzero();
assert_eq!(samples.get(), 3);

pub fn total_samples_nonzero(&self) -> NonZeroUsize

Returns the total number of samples as a NonZeroUsize.

This is the product of channels × samples_per_channel, both guaranteed non-zero.

pub fn duration_seconds<F: RealFloat>(&self) -> F

Returns the duration in seconds

pub fn total_samples(&self) -> usize

Returns the total number of samples across all channels

pub fn bytes_per_sample(&self) -> usize

Returns the number of bytes per sample for type T

pub fn layout(&self) -> ChannelLayout

Returns the channel layout

pub fn is_mono(&self) -> bool

Returns true if this is mono audio

pub fn is_multi_channel(&self) -> bool

Returns true if this is multi-channel audio

pub fn len(&self) -> usize

Returns the total number of samples.

pub fn is_empty(&self) -> bool

Returns true if there are no samples.

pub fn shape(&self) -> &[usize]

Returns the shape of the audio data.

pub fn apply<F>(&mut self, f: F)

where F: Fn(T) -> T,

Applies a function to each sample in the audio data in-place.

This method applies the given function to every sample in the audio data, modifying the samples in-place. The function receives each sample and should return the transformed sample.

Arguments

• f - A function that takes a sample and returns a transformed sample

Returns

Nothing. This method is infallible.

Example

// Halve the amplitude of all samples
audio.apply(|sample| sample * 0.5);

// Apply a simple distortion
audio.apply(|sample| sample.clamp(-0.8, 0.8));

pub fn apply_to_channels<F>(&mut self, channels: &[usize], f: F)

where F: Fn(T) -> T + Copy,

Apply a function to specific channels.

pub fn map<F>(&self, f: F) -> AudioSamples<'static, T>

where F: Fn(T) -> T,

Maps a function to each sample and returns a new AudioSamples instance.

This is a functional-style version of apply that doesn’t modify the original audio data but returns a new instance with the transformed samples.

Arguments

• f - A function that takes a sample and returns a transformed sample

Returns

A new AudioSamples instance with the transformed samples

Example

// Create a new audio instance with halved amplitude
let quieter_audio = audio.map(|sample| sample * 0.5);

// Create a new audio instance with clipped samples
let clipped_audio = audio.map(|sample| sample.clamp(-0.8, 0.8));

pub fn map_into<O: AudioSample, F>(&self, f: F) -> AudioSamples<'static, O>

where F: Fn(T) -> O,

Map each sample to a new type using a function. Does not care about in-domain or out-of-domain mapping. i.e. both convert_to and cast_from/into are acceptable.

pub fn apply_with_index<F>(&mut self, f: F)

where F: Fn(usize, T) -> T,

Applies a function to each sample with access to the sample index.

This method is similar to apply but provides the sample index to the function, allowing for position-dependent transformations.

Arguments

• f - A function that takes a sample index and sample value, returns transformed sample

Returns

Nothing. This method is infallible.

Example

// Apply a fade-in effect
audio.apply_with_index(|index, sample| {
    let fade_samples = 44100; // 1 second fade at 44.1kHz
    let gain = if index < fade_samples {
        index as f32 / fade_samples as f32
    } else {
        1.0
    };
    sample * gain
});

pub fn processing<'b>(&'b mut self) -> ProcessingBuilder<'b, T>

where i16: ConvertTo<T>, I24: ConvertTo<T>, i32: ConvertTo<T>, f32: ConvertTo<T>, f64: ConvertTo<T>, AudioSamples<'a, T>: AudioTypeConversion<'a, T>, 'b: 'a,

Creates a processing builder for fluent operation chaining.

This method provides a builder pattern for chaining multiple audio processing operations together and applying them all at once.

Example

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

let mut audio = AudioSamples::new_mono(array![1.0f32, 2.0, 3.0], 44100);
audio.processing()
    .normalize(-1.0, 1.0, NormalizationMethod::Peak)
    .scale(0.5)
    .apply()?;

pub fn slice_samples<R>( &self, sample_range: R, ) -> AudioSampleResult<AudioSamples<'_, T>>

where R: RangeBounds<usize> + Clone,

Slice audio by sample range, keeping all channels.

Creates a new AudioSamples instance containing samples in the specified range.

Arguments

• sample_range - Range of samples to extract (e.g., 100..200)

Returns

A new AudioSamples instance with the sliced samples

Errors

Returns an error if the range is out of bounds.

pub fn slice_channels<'iter, R>( &'iter self, channel_range: R, ) -> AudioSampleResult<AudioSamples<'static, T>>

where R: RangeBounds<usize> + Clone, 'iter: 'a,

Slice audio by channel range, keeping all samples.

Creates a new AudioSamples instance containing only the specified channels.

Arguments

• channel_range - Range of channels to extract (e.g., 0..2 for stereo)

Returns

A new AudioSamples instance with the sliced channels

Errors

Returns an error if the range is out of bounds.

pub fn slice_both<CR, SR>( &self, channel_range: CR, sample_range: SR, ) -> AudioSampleResult<AudioSamples<'static, T>>

where CR: RangeBounds<isize> + Clone, SR: RangeBounds<isize> + Clone,

Slice audio by both channel and sample ranges.

Creates a new AudioSamples instance containing the intersection of the specified channel and sample ranges.

Arguments

• channel_range - Range of channels to extract
• sample_range - Range of samples to extract

Returns

A new AudioSamples instance with the sliced data

Errors

Returns an error if either range is out of bounds.

pub fn bytes(&self) -> AudioSampleResult<AudioBytes<'_>>

Returns a contiguous byte view when possible.

pub fn into_bytes(&self) -> Vec<u8>

Convert audio samples to raw bytes, preferring zero-copy when possible.

pub fn as_bytes(&self) -> Vec<u8>

👎Deprecated: use bytes() for borrowed access or into_bytes() for owned bytes

Deprecated: use bytes() or into_bytes() instead.

pub fn total_byte_size(&self) -> usize

Returns the total size in bytes of all audio data.

This is equivalent to self.data.len() * self.bytes_per_sample().

Examples

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

let audio = AudioSamples::new_mono(array![1.0f32, 2.0, 3.0], 44100);
assert_eq!(audio.total_byte_size(), 12); // 3 samples × 4 bytes per f32

pub fn apply_windowed<F>( &mut self, window_size: usize, hop_size: usize, func: F, ) -> AudioSampleResult<()>

where F: Fn(&[T], &[T]) -> Vec<T>,

Apply a windowed processing function to the audio data.

This method processes the audio in overlapping windows, applying the provided function to each window and updating the audio data with the results.

Arguments

• window_size - Size of each processing window in samples
• hop_size - Number of samples to advance between windows
• func - Function called for each window, receiving (current_window, prev_window)

Returns

Returns Ok(()) on success, or an error if parameters are invalid.

pub fn replace_data( &mut self, new_data: AudioData<'a, T>, ) -> AudioSampleResult<()>

Replaces the audio data while preserving sample rate and channel layout.

This method allows you to swap out the underlying audio data with new data of the same channel configuration, maintaining the existing sample rate and layout metadata.

Arguments

• new_data - The new audio data to replace the current data

Returns

Returns Ok(()) on success, or an error if the new data has incompatible dimensions.

Errors

• Returns ParameterError if the new data has a different number of channels
• Returns ParameterError if mono/multi-channel layout mismatch occurs

Examples

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

// Create initial audio
let initial_data = array![1.0f32, 2.0, 3.0];
let mut audio = AudioSamples::new_mono(initial_data, 44100);

// Replace with new data
let new_data = AudioData::new_mono(array![4.0f32, 5.0, 6.0, 7.0]);
audio.replace_data(new_data)?;

assert_eq!(audio.samples_per_channel(), 4);
assert_eq!(audio.sample_rate(), 44100); // Preserved

pub fn replace_with_mono(&mut self, data: Array1<T>) -> AudioSampleResult<()>

Replaces the audio data with new mono data from an owned Array1.

This is a convenience method for replacing mono audio data while preserving sample rate and layout metadata.

Arguments

• data - New mono audio data as an owned Array1

Returns

Returns Ok(()) on success, or an error if the current audio is not mono.

Errors

• Returns ParameterError if the current audio is not mono

Examples

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

// Create initial mono audio
let mut audio = AudioSamples::new_mono(array![1.0f32, 2.0], 44100);

// Replace with new mono data
audio.replace_with_mono(array![3.0f32, 4.0, 5.0])?;

assert_eq!(audio.samples_per_channel(), 3);
assert_eq!(audio.sample_rate(), 44100); // Preserved

pub fn replace_with_multi(&mut self, data: Array2<T>) -> AudioSampleResult<()>

Replaces the audio data with new multi-channel data from an owned Array2.

This is a convenience method for replacing multi-channel audio data while preserving sample rate and layout metadata.

Arguments

• data - New multi-channel audio data as an owned Array2 where rows are channels

Returns

Returns Ok(()) on success, or an error if channel count doesn’t match.

Errors

• Returns ParameterError if the current audio is mono
• Returns ParameterError if the new data has different number of channels

Examples

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

// Create initial stereo audio
let mut audio = AudioSamples::new_multi_channel(
    array![[1.0f32, 2.0], [3.0, 4.0]], 44100
);

// Replace with new stereo data (different length is OK)
audio.replace_with_multi(array![[5.0f32, 6.0, 7.0], [8.0, 9.0, 10.0]])?;

assert_eq!(audio.samples_per_channel(), 3);
assert_eq!(audio.num_channels(), 2);
assert_eq!(audio.sample_rate(), 44100); // Preserved

pub fn replace_with_vec(&mut self, samples: Vec<T>) -> AudioSampleResult<()>

Replaces the audio data with new data from a Vec, maintaining current channel layout.

This is a convenience method for replacing audio data with samples from a Vec. The method infers whether to create mono or multi-channel data based on the current AudioSamples configuration.

Arguments

• samples - Vector of samples to replace the current audio data

Returns

Returns Ok(()) on success, or an error if the sample count is incompatible.

Errors

• Returns ParameterError if the sample count is not divisible by current channel count
• Returns ParameterError if the resulting array cannot be created

Examples

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

// Replace mono audio
let mut mono_audio = AudioSamples::new_mono(array![1.0f32, 2.0], 44100);
mono_audio.replace_with_vec(vec![3.0f32, 4.0, 5.0, 6.0])?;
assert_eq!(mono_audio.samples_per_channel(), 4);

// Replace stereo audio (interleaved samples)
let mut stereo_audio = AudioSamples::new_multi_channel(
    array![[1.0f32, 2.0], [3.0, 4.0]], 44100
);
stereo_audio.replace_with_vec(vec![5.0f32, 6.0, 7.0, 8.0, 9.0, 10.0])?;
assert_eq!(stereo_audio.samples_per_channel(), 3); // 6 samples ÷ 2 channels
assert_eq!(stereo_audio.num_channels(), 2);

pub fn replace_with_vec_channels( &mut self, samples: Vec<T>, expected_channels: usize, ) -> AudioSampleResult<()>

Replaces the audio data with new data from a Vec, validating against a specific channel count.

This method is similar to replace_with_vec but validates the sample count against the provided expected_channels parameter rather than the current audio configuration. This is useful when the current audio might be a placeholder or when you want to ensure the data matches a specific channel configuration.

Arguments

• samples - Vector of samples to replace the current audio data
• expected_channels - Expected number of channels for validation

Returns

Returns Ok(()) on success, or an error if validation fails.

Errors

• Returns ParameterError if the sample count is not divisible by expected_channels
• Returns ParameterError if the current audio doesn’t match expected_channels
• Returns ParameterError if the resulting array cannot be created

Examples

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

// Create placeholder stereo audio
let mut audio = AudioSamples::new_multi_channel(
    array![[0.0f32, 0.0], [0.0, 0.0]], 44100
);

// Replace with data that must be stereo (2 channels)
let samples = vec![1.0f32, 2.0, 3.0, 4.0]; // 4 samples = 2 samples per channel
audio.replace_with_vec_channels(samples, 2)?;

assert_eq!(audio.samples_per_channel(), 2);
assert_eq!(audio.num_channels(), 2);

pub fn as_mono(&self) -> Option<&MonoData<'a, T>>

Returns a reference to the underlying mono array if this is mono audio.

Returns

Some reference to the mono array if this is mono audio, None otherwise.

pub fn as_multi_channel(&self) -> Option<&MultiData<'a, T>>

Returns a reference to the underlying multi-channel array if this is multi-channel audio.

Returns

Some reference to the multi-channel array if this is multi-channel audio, None otherwise.

pub fn as_mono_mut(&mut self) -> Option<&mut MonoData<'a, T>>

Returns a mutable reference to the underlying mono array if this is mono audio.

Returns

Some mutable reference to the mono array if this is mono audio, None otherwise.

pub fn as_multi_channel_mut(&mut self) -> Option<&mut MultiData<'a, T>>

Returns a mutable reference to the underlying multi-channel array if this is multi-channel audio.

Returns

Some mutable reference to the multi-channel array if this is multi-channel audio, None otherwise.

Trait Implementations

impl<'a, T: AudioSample> AsMut<AudioSamples<'a, T>> for StereoAudioSamples<'a, T>

fn as_mut(&mut self) -> &mut AudioSamples<'a, T>

Converts this type into a mutable reference of the (usually inferred) input type.

impl<'a, T: AudioSample> AsRef<AudioSamples<'a, T>> for StereoAudioSamples<'a, T>

fn as_ref(&self) -> &AudioSamples<'a, T>

Converts this type into a shared reference of the (usually inferred) input type.

impl<T: AudioSample> DerefMut for StereoAudioSamples<'_, T>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<T: AudioSample> From<StereoAudioSamples<'static, T>> for AudioSamples<'static, T>

fn from(stereo: StereoAudioSamples<'static, T>) -> Self

Converts to this type from the input type.

impl<T: AudioSample> TryFrom<AudioSamples<'static, T>> for StereoAudioSamples<'static, T>

Zero-copy conversion from owned AudioSamples to StereoAudioSamples

type Error = AudioSampleError

The type returned in the event of a conversion error.

fn try_from(audio: AudioSamples<'static, T>) -> Result<Self, Self::Error>

Performs the conversion.

impl<'a, T: AudioSample> Deref for StereoAudioSamples<'a, T>

type Target = AudioSamples<'a, T>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.