ff_preview/
error.rs

1//! Error types for ff-preview.
2
3use std::path::PathBuf;
4
5use ff_format::{ErrorSeverity, MediaError};
6use thiserror::Error;
7
8/// Errors that can occur during preview and proxy operations.
9#[derive(Debug, Error)]
10pub enum PreviewError {
11    /// The media file was not found at the specified path.
12    #[error("file not found: path={path}")]
13    FileNotFound {
14        /// Path that was not found.
15        path: PathBuf,
16    },
17
18    /// The media file has no video stream.
19    #[error("no video stream found: path={path}")]
20    NoVideoStream {
21        /// Path to the media file.
22        path: PathBuf,
23    },
24
25    /// A seek operation failed.
26    #[error("seek failed: target={target:?} reason={reason}")]
27    SeekFailed {
28        /// Target timestamp of the failed seek.
29        target: std::time::Duration,
30        /// Human-readable reason for the failure.
31        reason: String,
32    },
33
34    /// An underlying decode error occurred.
35    #[error("decode failed: {0}")]
36    Decode(#[from] ff_decode::DecodeError),
37
38    /// A raw `FFmpeg` error.
39    ///
40    /// `code` is the negative integer returned by the `FFmpeg` API, or `0` when no
41    /// numeric code is available. `message` is from `av_strerror` or an internal
42    /// description.
43    #[error("ffmpeg error: {message} (code={code})")]
44    Ffmpeg {
45        /// Raw `FFmpeg` error code (negative i32). `0` when no numeric code is available.
46        code: i32,
47        /// Human-readable message from `av_strerror` or an internal description.
48        message: String,
49    },
50
51    /// A probe error while analysing the media file.
52    #[error("probe failed: {0}")]
53    Probe(#[from] ff_probe::ProbeError),
54
55    /// A proxy generation pipeline error.
56    #[cfg(feature = "proxy")]
57    #[error("pipeline failed: {0}")]
58    Pipeline(#[from] ff_pipeline::PipelineError),
59
60    /// An I/O error during file operations.
61    #[error("io error: {0}")]
62    Io(#[from] std::io::Error),
63
64    /// A seek target lies outside the valid range of the timeline.
65    #[error("seek out of range: pts={pts:?}")]
66    SeekOutOfRange {
67        /// The requested presentation timestamp that fell outside all clips.
68        pts: std::time::Duration,
69    },
70
71    /// The background decode thread panicked and could not be recovered.
72    ///
73    /// The buffer cannot continue decoding; recover at the application level by
74    /// rebuilding it (e.g. reopen the file). This replaces an earlier internal
75    /// panic on the same condition.
76    #[error("decode thread poisoned: the background decoder panicked and cannot be recovered")]
77    DecodeThreadPoisoned,
78}
79
80impl MediaError for PreviewError {
81    fn severity(&self) -> ErrorSeverity {
82        match self {
83            Self::Decode(e) => e.severity(),
84            Self::Probe(e) => e.severity(),
85            #[cfg(feature = "proxy")]
86            Self::Pipeline(e) => e.severity(),
87            Self::SeekFailed { .. } | Self::DecodeThreadPoisoned => ErrorSeverity::Recoverable,
88            Self::Ffmpeg { .. } | Self::SeekOutOfRange { .. } => ErrorSeverity::Other,
89            Self::FileNotFound { .. } | Self::NoVideoStream { .. } | Self::Io(_) => {
90                ErrorSeverity::Fatal
91            }
92        }
93    }
94}
95
96#[cfg(test)]
97mod tests {
98    use super::*;
99
100    #[test]
101    fn preview_io_should_be_fatal() {
102        let e: PreviewError = std::io::Error::other("x").into();
103        assert!(e.is_fatal() && !e.is_recoverable());
104    }
105
106    #[test]
107    fn preview_seek_failed_should_be_recoverable() {
108        let e = PreviewError::SeekFailed {
109            target: std::time::Duration::from_secs(1),
110            reason: "x".into(),
111        };
112        assert!(e.is_recoverable() && !e.is_fatal());
113    }
114
115    #[test]
116    fn preview_decode_thread_poisoned_should_be_recoverable() {
117        let e = PreviewError::DecodeThreadPoisoned;
118        assert!(e.is_recoverable() && !e.is_fatal());
119        assert!(
120            e.to_string().contains("poisoned"),
121            "message must name the condition: {e}"
122        );
123    }
124
125    #[test]
126    fn preview_decode_should_delegate_recoverable() {
127        // A recoverable inner DecodeError must remain recoverable through the wrapper.
128        let e = PreviewError::Decode(ff_decode::DecodeError::decoding_failed("x"));
129        assert!(e.is_recoverable() && !e.is_fatal());
130    }
131}
ff_preview/error.rs

ff_preview/
error.rs
