Enum AudioSampleError 

#[non_exhaustive]
pub enum AudioSampleError {
    Conversion(ConversionError),
    Parameter(ParameterError),
    Layout(LayoutError),
    Processing(ProcessingError),
    Feature(FeatureError),
    Parse {
        type_name: String,
        context: String,
    },
    EmptyData,
    InvalidNumberOfSamples {
        total_samples: usize,
        channels: u32,
    },
    Fmt(Error),
    Unsupported(String),
}

Root error type for all audio sample operations.

Purpose

AudioSampleError is the single error type returned by every fallible public API in this crate. It groups failures into five sub-domains so that callers can handle broad categories with a single match arm while retaining the ability to inspect specific variants when required.

Intended Usage

Prefer matching on the inner sub-type rather than the outer variant wherever the specific failure domain matters. Propagate errors out of functions using the ? operator together with the AudioSampleResult return type.

Invariants

The enum is #[non_exhaustive], meaning new variants may be added in future minor versions. Always include a catch-all arm when matching exhaustively.

Feature-gated variants

The Spectrogram variant is only present when the transforms feature is enabled. It wraps errors originating from the spectrograms crate.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Conversion(ConversionError)

Errors related to type conversions and casting operations.

Parameter(ParameterError)

Errors related to invalid parameters or configuration.

Layout(LayoutError)

Errors related to memory layout, array structure, or data organization.

Processing(ProcessingError)

Errors that occur during audio processing operations.

Feature(FeatureError)

Errors related to missing or disabled features.

Parse

Errors related to parsing of any of the various audio_samples support types.

Fields

type_name: String

Type name of the type we failed to parse

context: String

User provided context

EmptyData

Error indicating that audio data is empty when non-empty data is required.

InvalidNumberOfSamples

Error indicating mismatch between total samples and channel count.

Occurs when the total number of samples is not evenly divisible by the number of channels, indicating malformed or corrupted audio data.

Fields

total_samples: usize

Total number of samples

channels: u32

Number of channels

Fmt(Error)

Error indicating a formatting failure during display or debug output.

Unsupported(String)

Error indicating an unsupported operation or configuration.

Used when a requested operation is valid in principle but not implemented for the given combination of inputs (e.g., certain multi-channel operations, unsupported sample types, or platform-specific limitations).

Implementations

impl AudioSampleError

pub fn unsupported<S>(msg: S) -> Self

where S: ToString,

Creates an crate::AudioSampleError::Unsupported with the given message.

Use this when a caller requests an operation that is valid in principle but not implemented for the given combination of inputs (e.g. multi-channel STFT).

Arguments

• msg — Human-readable description of the unsupported operation.

Returns

AudioSampleError::Unsupported(msg.to_string()).

Examples

use audio_samples::AudioSampleError;

let err = AudioSampleError::unsupported("multi-channel MFCC is not supported");
assert!(matches!(err, AudioSampleError::Unsupported(_)));

pub const fn invalid_number_of_samples( total_samples: usize, channels: u32, ) -> Self

Creates an AudioSampleError::InvalidNumberOfSamples error.

Use this when total_samples cannot be distributed evenly across channels, or when the combination is otherwise incoherent for the requested layout.

Arguments

• total_samples — The total number of interleaved samples provided.
• channels — The number of audio channels requested.

Returns

AudioSampleError::InvalidNumberOfSamples { total_samples, channels }.

Examples

use audio_samples::AudioSampleError;

// 5 samples cannot be divided evenly into 2 channels
let err = AudioSampleError::invalid_number_of_samples(5, 2);
assert!(matches!(err, AudioSampleError::InvalidNumberOfSamples { .. }));

pub fn parse<T, S>(msg: S) -> Self

where S: ToString,

Creates an AudioSampleError::Parse error for the type T.

The type name of T is captured automatically via std::any::type_name and embedded in the returned error for diagnostic purposes.

Arguments

• msg — Human-readable description of the parse failure.

Type Parameters

• T — The type that could not be parsed. Its name is recorded in the type_name field of the returned error.

Returns

AudioSampleError::Parse { type_name: std::any::type_name::<T>(), context: msg }.

Examples

use audio_samples::AudioSampleError;

let err = AudioSampleError::parse::<f32, _>("expected a finite float");
assert!(matches!(err, AudioSampleError::Parse { .. }));

pub fn layout<S>(msg: S) -> Self

where S: ToString,

Creates an crate::AudioSampleError::Layout wrapping a LayoutError::ShapeError.

Convenience constructor for shape-related layout errors where the specific operation name is not available at the call site. The operation field is set to "unknown".

Arguments

• msg — Human-readable description of the shape problem.

Returns

AudioSampleError::Layout(LayoutError::ShapeError { operation: "unknown", info: msg }).

Examples

use audio_samples::{AudioSampleError, LayoutError};

let err = AudioSampleError::layout("expected 2-D array, got 3-D");
assert!(matches!(err, AudioSampleError::Layout(LayoutError::ShapeError { .. })));

Trait Implementations

impl Clone for AudioSampleError

fn clone(&self) -> AudioSampleError

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AudioSampleError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for AudioSampleError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for AudioSampleError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<ConversionError> for AudioSampleError

fn from(source: ConversionError) -> Self

Converts to this type from the input type.

impl From<Error> for AudioSampleError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<FeatureError> for AudioSampleError

fn from(source: FeatureError) -> Self

Converts to this type from the input type.

impl From<LayoutError> for AudioSampleError

fn from(source: LayoutError) -> Self

Converts to this type from the input type.

impl From<ParameterError> for AudioSampleError

fn from(source: ParameterError) -> Self

Converts to this type from the input type.

impl From<ProcessingError> for AudioSampleError

fn from(source: ProcessingError) -> Self

Converts to this type from the input type.

impl From<ShapeError> for AudioSampleError

fn from(err: ShapeError) -> Self

Converts to this type from the input type.