av_decoders/error.rs
1use thiserror::Error;
2
3/// Errors that can occur during video decoding operations.
4///
5/// This enum represents all possible error conditions that may arise when
6/// decoding video files using the av-decoders library. Errors range from
7/// file I/O issues to unsupported video formats and decoder-specific problems.
8#[derive(Debug, Clone, Error)]
9pub enum DecoderError {
10 /// Indicates that the end of the video file has been reached.
11 ///
12 /// This is returned when attempting to read frames beyond the end of the video stream.
13 /// This is typically not an error condition but rather a normal end-of-stream indicator.
14 #[error("end of video file reached")]
15 EndOfFile,
16
17 /// Failed to read or open the input video file.
18 ///
19 /// This error occurs when the decoder cannot access the specified file,
20 /// either due to file permissions, file not found, or other I/O related issues.
21 #[error("failed to open input file ({cause})")]
22 FileReadError {
23 /// The underlying cause of the error
24 cause: String,
25 },
26
27 /// Error in the `VapourSynth` script execution.
28 ///
29 /// This error is returned when there's a problem with the `VapourSynth` script itself,
30 /// such as syntax errors, invalid filter chains, or script logic issues.
31 /// Only available when the `vapoursynth` feature is enabled.
32 #[cfg(feature = "vapoursynth")]
33 #[error("Vapoursynth script error ({cause})")]
34 VapoursynthScriptError {
35 /// The underlying cause of the error
36 cause: String,
37 },
38
39 /// Internal `VapourSynth` error.
40 ///
41 /// This represents errors that occur within the `VapourSynth` core or plugins,
42 /// typically indicating issues with the `VapourSynth` installation or environment.
43 /// Only available when the `vapoursynth` feature is enabled.
44 #[cfg(feature = "vapoursynth")]
45 #[error("Vapoursynth internal error ({cause})")]
46 VapoursynthInternalError {
47 /// The underlying cause of the error
48 cause: String,
49 },
50
51 /// Failure to set Vapoursynth script arguments.
52 ///
53 /// Only available when the `vapoursynth` feature is enabled.
54 #[cfg(feature = "vapoursynth")]
55 #[error("error setting Vapoursynth script args ({cause})")]
56 VapoursynthArgsError {
57 /// The underlying cause of the error
58 cause: String,
59 },
60
61 /// Internal FFmpeg error.
62 ///
63 /// This error occurs when FFmpeg encounters an internal problem during
64 /// decoding operations, such as codec issues or corrupted video data.
65 /// Only available when the `ffmpeg` feature is enabled.
66 #[cfg(feature = "ffmpeg")]
67 #[error("FFMpeg internal error ({cause})")]
68 FfmpegInternalError {
69 /// The underlying cause of the error
70 cause: String,
71 },
72
73 /// Internal FFMS2 error.
74 ///
75 /// This error occurs when FFMS2 encounters an internal problem during
76 /// decoding operations, such as codec issues or corrupted video data.
77 /// Only available when the `ffms2` feature is enabled.
78 #[cfg(feature = "ffms2")]
79 #[error("FFMS2 internal error ({cause})")]
80 Ffms2InternalError {
81 /// The underlying cause of the error
82 cause: String,
83 },
84
85 /// Generic decoder error for issues not covered by specific error types.
86 ///
87 /// This is a catch-all error for various decoding problems that don't fit
88 /// into other categories, providing additional context through the cause string.
89 #[error("internal decoder error ({cause})")]
90 GenericDecodeError {
91 /// The underlying cause of the error
92 cause: String,
93 },
94
95 /// No video stream found in the input file.
96 ///
97 /// This error is returned when the input file doesn't contain any decodeable
98 /// video streams, or when all video streams are in unsupported formats.
99 #[error("no decodeable video stream found in file")]
100 NoVideoStream,
101
102 /// No suitable decoder available for the input file.
103 ///
104 /// This occurs when none of the available decoders can handle the input format.
105 /// Consider enabling additional features like `ffmpeg` or `vapoursynth` to
106 /// support more video formats.
107 #[error(
108 "no decoder found which can decode this file--perhaps you need to enable the ffmpeg or vapoursynth feature"
109 )]
110 NoDecoder,
111
112 /// The current decoder does not support the function which is being called.
113 #[error("this function is not supported by the decoder in use")]
114 UnsupportedDecoder,
115
116 /// Variable format video clips are not supported.
117 ///
118 /// This error is returned when the video file contains streams with changing
119 /// pixel formats throughout the video, which is currently not supported by
120 /// this library.
121 #[error("variable format clips are not currently supported")]
122 VariableFormat,
123
124 /// Variable resolution video clips are not supported.
125 ///
126 /// This error occurs when the video resolution changes during playback,
127 /// which is not currently supported. All frames must have the same dimensions.
128 #[error("variable resolution clips are not currently supported")]
129 VariableResolution,
130
131 /// Variable framerate video clips are not supported.
132 ///
133 /// This error is returned when the video has a variable framerate (VFR),
134 /// where the time between frames is not constant. Only constant framerate
135 /// videos are currently supported.
136 #[error("variable framerate clips are not currently supported")]
137 VariableFramerate,
138
139 /// Unsupported chroma subsampling format.
140 ///
141 /// This error occurs when the video uses a chroma subsampling scheme that
142 /// is not supported by the decoder. The `x` and `y` values indicate the
143 /// horizontal and vertical subsampling factors respectively.
144 #[error("unsupported chroma subsampling ({x}, {y})")]
145 UnsupportedChromaSubsampling {
146 /// The horizontal chroma subsampling which triggered the error
147 x: usize,
148 /// The vertical chroma subsampling which triggered the error
149 y: usize,
150 },
151
152 /// Unsupported video format.
153 ///
154 /// This error is returned when the video uses a pixel format or codec
155 /// that is not supported by the current decoder configuration.
156 #[error("unsupported video format {fmt}")]
157 UnsupportedFormat {
158 /// The video format which triggered the error
159 fmt: String,
160 },
161}