Skip to main content

DecodeError

Enum DecodeError 

Source
#[non_exhaustive]
pub enum DecodeError { UnsupportedContainer { tag: FourCc, }, UnsupportedCodec { codec: CodecId, }, UnsupportedSampleFormat { format: CodecId, bits_per_sample: u16, }, UnsupportedChannelLayout { channels: u16, }, Malformed { expected: &'static str, offset: u64, }, Truncated { expected: u64, available: u64, }, ContainerCodecMismatch { declared: CodecId, found: CodecId, }, Resample(ResamplerError), }
Expand description

Every way decoding can fail.

The variant list is closed by design rather than grown as codecs land. Each variant decibri surfaces has to be registered by name, code and sample instance in the error_identity! table in decibri’s error.rs, and that macro has no catch-all arm, so a variant added later is a change in two crates and a new stable code on decibri’s frozen error surface. Settling the list while the crate is empty costs nothing; growing it later costs a version bump in both crates.

The four Unsupported* variants are split rather than folded into one for the reason recorded on CodecId: “unsupported” alone does not tell a caller which encoding they hit or what to do about it.

This enum is #[non_exhaustive]: consumers pattern-matching on it must include a _ => catch-all arm so future variant additions are not source-breaking.

Variants (Non-exhaustive)§

This enum is marked as 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.
§

UnsupportedContainer

The container format was not recognised.

Carries the identifying bytes that were seen at the start of the input, so a caller can tell “this is not audio at all” from “this is audio in a container this build does not carry”.

Fields

§tag: FourCc

The leading bytes read where a container magic was expected.

§

UnsupportedCodec

The container parsed and named a codec this build does not support.

Distinct from UnsupportedContainer: the file is well-formed and its structure was understood. Only the payload encoding is out of reach.

Fields

§codec: CodecId

The codec identity exactly as the container stated it.

§

UnsupportedSampleFormat

A recognised codec in a sample format this build does not support.

Distinct from UnsupportedCodec: the codec itself is carried, but not at this width or in this representation, 24-bit PCM where only 16- and 32-bit are implemented, for instance.

Fields

§format: CodecId

The format tag, in the form the container stated it.

§bits_per_sample: u16

Bits per sample as declared by the container.

§

UnsupportedChannelLayout

The channel count or layout is not one this build can decode.

Fields

§channels: u16

The channel count the container declared.

§

Malformed

A parse failure: the bytes at a known position were not what the format requires there.

Distinct from Truncated, which is about running out of input rather than finding the wrong input.

Fields

§expected: &'static str

What the parser required at that position, as a short literal.

§offset: u64

Byte offset from the start of the input where the parse failed.

§

Truncated

The input ended part-way through a frame, a header or a declared length.

From a file this means the file is short. From a stream it means the stream was finished while a frame was still incomplete: a stream that simply has not received the rest yet is not an error, and the stream adapter holds the partial frame instead of reporting one.

Fields

§expected: u64

How much of the incomplete item was needed. Bytes on every path but one: a FLAC stream holding fewer samples than its streaminfo declares reports the two counts in interchannel samples, because samples are the unit the declaration is in.

§available: u64

How much was actually available, in the same unit as expected.

§

ContainerCodecMismatch

The container declares one codec and the payload is another.

Reached when both identities parse and disagree, a WAVE header claiming integer PCM over a payload whose frames are mu-law, say. Reported separately from the Unsupported* variants because nothing here is unsupported: the file is internally inconsistent and no single decoder choice is correct.

Fields

§declared: CodecId

What the container’s header said the payload is.

§found: CodecId

What the payload actually turned out to be.

§

Resample(ResamplerError)

Rate conversion failed.

The only variant that chains a source. This crate contains no resampling logic; it calls decibri-resampler and passes its failure through unaltered.

Trait Implementations§

Source§

impl Debug for DecodeError

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Display for DecodeError

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Error for DecodeError

Source§

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

Returns the lower-level source of this error, if any. Read more
1.0.0 · Source§

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

1.0.0 · Source§

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

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

Source§

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. Read more
Source§

impl From<ResamplerError> for DecodeError

Source§

fn from(source: ResamplerError) -> Self

Converts to this type from the input type.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToString for T
where T: Display + ?Sized,

Source§

fn to_string(&self) -> String

Converts the given value to a String. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.