Enum DecodeError 

pub enum DecodeError {
    FileNotFound {
        path: PathBuf,
    },
    NoVideoStream {
        path: PathBuf,
    },
    NoAudioStream {
        path: PathBuf,
    },
    UnsupportedCodec {
        codec: String,
    },
    DecoderUnavailable {
        codec: String,
        hint: String,
    },
    DecodingFailed {
        timestamp: Option<Duration>,
        reason: String,
    },
    SeekFailed {
        target: Duration,
        reason: String,
    },
    HwAccelUnavailable {
        accel: HardwareAccel,
    },
    InvalidOutputDimensions {
        width: u32,
        height: u32,
    },
    Ffmpeg {
        code: i32,
        message: String,
    },
    Io(Error),
}

Errors that can occur during decoding operations.

This enum covers all error conditions that may arise when opening, configuring, or decoding media files.

Error Categories

• File errors: FileNotFound
• Stream errors: NoVideoStream, NoAudioStream
• Codec errors: UnsupportedCodec
• Runtime errors: DecodingFailed, SeekFailed
• Hardware errors: HwAccelUnavailable
• Configuration errors: InvalidOutputDimensions
• Internal errors: Ffmpeg, Io

Variants

FileNotFound

File was not found at the specified path.

This error occurs when attempting to open a file that doesn’t exist.

Fields

path: PathBuf

Path that was not found.

NoVideoStream

No video stream exists in the media file.

This error occurs when trying to decode video from a file that only contains audio or other non-video streams.

Fields

path: PathBuf

Path to the media file.

NoAudioStream

No audio stream exists in the media file.

This error occurs when trying to decode audio from a file that only contains video or other non-audio streams.

Fields

path: PathBuf

Path to the media file.

UnsupportedCodec

The codec is not supported by this decoder.

This may occur for uncommon or proprietary codecs that are not included in the FFmpeg build.

Fields

codec: String

Name of the unsupported codec.

DecoderUnavailable

The decoder for a known codec is absent from this FFmpeg build.

Unlike UnsupportedCodec, the codec ID is recognised by FFmpeg but the decoder was not compiled in (e.g. --enable-decoder=exr was omitted from the build).

Fields

codec: String

Short name of the codec (e.g. "exr").

hint: String

Human-readable suggestion for the caller.

DecodingFailed

Decoding operation failed at a specific point.

This can occur due to corrupted data, unexpected stream format, or internal decoder errors.

Fields

timestamp: Option<Duration>

Timestamp where decoding failed (if known).

reason: String

Reason for the failure.

SeekFailed

Seek operation failed.

Seeking may fail for various reasons including corrupted index, seeking beyond file bounds, or stream format limitations.

Fields

target: Duration

Target position of the seek.

reason: String

Reason for the failure.

HwAccelUnavailable

Requested hardware acceleration is not available.

This error occurs when a specific hardware accelerator is requested but the system doesn’t support it. Consider using HardwareAccel::Auto for automatic fallback.

Fields

accel: HardwareAccel

The unavailable hardware acceleration type.

InvalidOutputDimensions

Output dimensions are invalid.

Width and height passed to output_size, output_width, or output_height must be greater than zero and even (required by most pixel formats).

Fields

width: u32

Requested output width.

height: u32

Requested output height.

Ffmpeg

FFmpeg internal error.

This wraps errors from the underlying FFmpeg library that don’t fit into other categories.

Fields

code: i32

Raw FFmpeg error code (negative integer). 0 when no numeric code is available.

message: String

Human-readable error message from av_strerror or an internal description.

Io(Error)

I/O error during file operations.

This wraps standard I/O errors such as permission denied, disk full, or network errors for remote files.

Implementations

impl DecodeError

pub fn decoding_failed(reason: impl Into<String>) -> Self

Creates a new DecodeError::DecodingFailed with the given reason.

Arguments

• reason - Description of why decoding failed.

Examples

use ff_decode::DecodeError;

let error = DecodeError::decoding_failed("Corrupted frame data");
assert!(error.to_string().contains("Corrupted frame data"));
assert!(error.is_recoverable());

pub fn decoding_failed_at( timestamp: Duration, reason: impl Into<String>, ) -> Self

Creates a new DecodeError::DecodingFailed with timestamp and reason.

Arguments

• timestamp - The timestamp where decoding failed.
• reason - Description of why decoding failed.

Examples

use ff_decode::DecodeError;
use std::time::Duration;

let error = DecodeError::decoding_failed_at(
    Duration::from_secs(30),
    "Invalid packet size"
);
assert!(error.to_string().contains("30s"));
assert!(error.is_recoverable());

pub fn seek_failed(target: Duration, reason: impl Into<String>) -> Self

Creates a new DecodeError::SeekFailed.

Arguments

• target - The target position of the failed seek.
• reason - Description of why the seek failed.

Examples

use ff_decode::DecodeError;
use std::time::Duration;

let error = DecodeError::seek_failed(
    Duration::from_secs(60),
    "Index not found"
);
assert!(error.to_string().contains("60s"));
assert!(error.is_recoverable());

pub fn decoder_unavailable( codec: impl Into<String>, hint: impl Into<String>, ) -> Self

Creates a new DecodeError::DecoderUnavailable.

Arguments

• codec — Short codec name (e.g. "exr").
• hint — Human-readable suggestion for the user.

pub fn ffmpeg(code: i32, message: impl Into<String>) -> Self

Creates a new DecodeError::Ffmpeg.

Arguments

• code - The raw FFmpeg error code (negative integer). Pass 0 when no numeric code is available.
• message - Human-readable description of the error.

Examples

use ff_decode::DecodeError;

let error = DecodeError::ffmpeg(-22, "Invalid data found when processing input");
assert!(error.to_string().contains("Invalid data"));
assert!(error.to_string().contains("code=-22"));

pub fn is_recoverable(&self) -> bool

Returns true if this error is recoverable.

Recoverable errors are those where the decoder can continue operating after the error, such as corrupted frames that can be skipped.

Examples

use ff_decode::DecodeError;
use std::time::Duration;

// Decoding failures are recoverable
assert!(DecodeError::decoding_failed("test").is_recoverable());

// Seek failures are recoverable
assert!(DecodeError::seek_failed(Duration::from_secs(1), "test").is_recoverable());

pub fn is_fatal(&self) -> bool

Returns true if this error is fatal.

Fatal errors indicate that the decoder cannot continue and must be recreated or the file reopened.

Examples

use ff_decode::DecodeError;
use std::path::PathBuf;

// File not found is fatal
assert!(DecodeError::FileNotFound { path: PathBuf::new() }.is_fatal());

// Unsupported codec is fatal
assert!(DecodeError::UnsupportedCodec { codec: "test".to_string() }.is_fatal());

Trait Implementations

impl Debug for DecodeError

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

Formats the value using the given formatter.

impl Display for DecodeError

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

Formats the value using the given formatter.

impl Error for DecodeError

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<Error> for DecodeError

fn from(source: Error) -> Self

Converts to this type from the input type.