1use std::fmt;
2
3#[derive(Clone, Copy, Debug, PartialEq, Eq)]
5#[non_exhaustive]
6pub enum FailureKind {
7 InvalidInput,
9 Unsupported,
11 NotFound,
13 Load,
15 Configuration,
17 NotPrepared,
19 Closed,
21 RestartRequired,
23 EditorOpen,
25 StateMismatch,
27 State,
29 Processing,
31 Editor,
33 Host,
35 Protocol,
37 Crashed,
39 TimedOut,
41 Cancelled,
43}
44
45#[derive(Clone, Debug, PartialEq, Eq)]
47#[non_exhaustive]
48pub struct Failure {
49 pub kind: FailureKind,
51 pub message: String,
53}
54
55impl Failure {
56 #[must_use]
58 pub fn new(kind: FailureKind, message: impl Into<String>) -> Self {
59 Self {
60 kind,
61 message: message.into(),
62 }
63 }
64}
65
66impl fmt::Display for Failure {
67 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
68 f.write_str(&self.message)
69 }
70}
71
72impl std::error::Error for Failure {}
73
74const EVENT_CAPACITY: &str =
75 "the block or pending edit queue exceeds MAX_BLOCK_EVENTS or MAX_BLOCK_SYSEX_BYTES";
76const EVENT_PORT_COUNT: &str = "the event routing exceeds the maximum ports per slot or chain";
77const DUPLICATE_EVENT_PORT: &str = "event output port ID occurs more than once in one slot";
78const EVENT_ROUTE: &str = "the event route does not name an available source";
79const EVENT_PORT: &str = "the event names an event port the chain does not have";
80const AUDIO_SLOT_COUNT: &str = "the audio configuration needs one routing entry per plugin";
81const AUDIO_BUS_COUNT: &str = "the audio configuration exceeds the maximum buses per direction";
82const AUDIO_CHANNEL_COUNT: &str =
83 "the audio configuration exceeds the maximum active channels per direction";
84const DUPLICATE_AUDIO_BUS: &str = "audio bus ID occurs more than once in one direction";
85const AUDIO_BUS_LAYOUT: &str = "an active audio bus must have a nonempty layout";
86const AUDIO_ROUTE: &str = "the audio route does not name an available source";
87const CHANNEL_ADAPTATION: &str =
88 "the explicit channel adaptation does not match the source and target layouts";
89const BLOCK_EVENTS: &str = "events must be notes, expressions in their ranges, MIDI 1.0 channel messages or complete \
90 system exclusive messages, in offset order and inside the block or render input";
91const AUDIO_BUFFERS: &str = "audio buffers must match the bus channel count and contain equal frame \
92 counts, at most the prepared maximum block size";
93const AUDIO_SAMPLE_FORMAT: &str =
94 "audio sample precision does not match the prepared configuration";
95const STATE_SIZE: &str = "plugin component and controller state together exceed the maximum size";
96const STATE_BYTES: &str = "the bytes are not a plugin state this plughost version can read";
97const PARAMETER_CHOICE_PAGE: &str =
98 "parameter choice pages need a valid start index and a nonzero entry count within the maximum";
99const PRESET_SIZE: &str = "the preset file exceeds the maximum size";
100const AUTOMATION: &str =
101 "automation must be ordered, normalized, inside the block and address a loaded slot";
102const NOT_AUTOMATABLE: &str = "parameter cannot be automated";
103const TRANSPORT: &str =
104 "transport values must be finite, representable, and describe a valid tempo, meter and loop";
105const SAMPLE_RATE: &str = "sample rate must be finite and greater than zero";
106const BLOCK_SIZE: &str = "maximum block size must be between 1 and i32::MAX";
107const OUTPUT_COUNT: &str = "the configuration needs one output layout per plugin";
108const EMPTY_CHAIN: &str = "a chain must contain at least one plugin";
109const INVALID_SLOT: &str = "the slot does not contain a loaded plugin";
110const PARAMETER_VALUE: &str = "parameter value must be finite and normalized to 0..=1";
111const PARAMETER_TEXT: &str =
112 "parameter text must be accepted by the plugin, NUL-free and within the maximum UTF-8 bytes";
113const PLAIN_PARAMETER_VALUE: &str =
114 "plain parameter value must be finite and within the native parameter range";
115const UNKNOWN_PARAMETER: &str = "the parameter does not exist";
116const READ_ONLY_PARAMETER: &str = "the parameter is read-only";
117const HOST_IDENTITY: &str =
118 "host identity must be NUL-free, with a non-empty name of at most 127 UTF-16 code units";
119const PRESET_DISCOVERY_TARGET: &str = "a preset discovery target needs a non-empty, NUL-free provider \
120 ID and, for a file location, an absolute, NUL-free Unicode path, each within the text limit";
121
122pub const MAIN_BUS: &str = "the plugin has no main audio bus for the requested layout";
124pub const OUTPUT_EVENT_CAPACITY: &str = "the plugin produced more events or system exclusive bytes in one block than MAX_BLOCK_EVENTS or MAX_BLOCK_SYSEX_BYTES allow; reset before processing again";
126pub const UNKNOWN_EVENT_PORT: &str = "the plugin has no event port with this ID";
128pub const AUDIT: &str = "real-time audit:";
130pub const UNCONVERTIBLE_OUTPUT_EVENTS: &str = "output events with no portable form (chords, scales, choke, text expression, MIDI 2.0) were not delivered:";
132pub const STATE_MISMATCH: &str = "the state belongs to a different plugin class";
134pub const CHAIN_NOT_PREPARED: &str = "the chain is not prepared";
136
137#[derive(Clone, Copy, Debug, PartialEq, Eq)]
139#[non_exhaustive]
140pub enum InputError {
141 AudioSlotCount,
143 AudioBusCount,
145 AudioChannelCount,
147 DuplicateAudioBus {
149 id: u64,
151 },
152 AudioBusLayout {
154 id: u64,
156 },
157 AudioRoute {
159 slot: usize,
161 bus: u64,
163 },
164 ChannelAdaptation {
166 source: crate::Layout,
168 target: crate::Layout,
170 },
171 AudioBuffers,
174 AudioSampleFormat,
176 StateSize,
178 StateBytes,
181 ParameterChoicePage,
183 PresetSize,
185 Transport,
187 Automation,
189 NotAutomatable {
191 id: u64,
193 },
194 HostIdentity,
196 PresetDiscoveryTarget,
200 EmptyChain,
202 SampleRate,
204 BlockSize,
206 OutputCount,
208 MainBus,
210 Slot,
212 ParameterValue,
214 ParameterText,
216 PlainParameterValue,
218 UnknownParameter {
220 id: u64,
222 },
223 ReadOnlyParameter {
225 id: u64,
227 },
228 EventCapacity,
230 EventPortCount,
232 DuplicateEventPort {
234 id: u64,
236 },
237 EventRoute {
239 slot: usize,
241 port: u64,
243 },
244 EventPort {
246 port: usize,
248 },
249 Events,
252 PathEncoding,
254 RealtimeQuantum,
256 RealtimeLatency,
258 RealtimeDry,
260 RemoteRegion,
263 RemoteEditor,
265}
266
267impl fmt::Display for InputError {
268 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
269 match self {
270 Self::EventCapacity => f.write_str(EVENT_CAPACITY),
271 Self::EventPortCount => {
272 write!(f, "{EVENT_PORT_COUNT} ({})", crate::MAX_EVENT_PORTS)
273 }
274 Self::DuplicateEventPort { id } => write!(f, "{DUPLICATE_EVENT_PORT} ({id})"),
275 Self::EventRoute { slot, port } => {
276 write!(f, "{EVENT_ROUTE} (slot {slot}, input port {port})")
277 }
278 Self::EventPort { port } => write!(f, "{EVENT_PORT} ({port})"),
279 Self::Events => f.write_str(BLOCK_EVENTS),
280 Self::AudioSlotCount => f.write_str(AUDIO_SLOT_COUNT),
281 Self::AudioBusCount => write!(f, "{AUDIO_BUS_COUNT} ({})", crate::MAX_AUDIO_BUSES),
282 Self::AudioChannelCount => {
283 write!(f, "{AUDIO_CHANNEL_COUNT} ({})", crate::MAX_AUDIO_CHANNELS)
284 }
285 Self::DuplicateAudioBus { id } => write!(f, "{DUPLICATE_AUDIO_BUS} ({id})"),
286 Self::AudioBusLayout { id } => write!(f, "{AUDIO_BUS_LAYOUT} ({id})"),
287 Self::AudioRoute { slot, bus } => {
288 write!(f, "{AUDIO_ROUTE} (slot {slot}, input bus {bus})")
289 }
290 Self::ChannelAdaptation { source, target } => {
291 write!(f, "{CHANNEL_ADAPTATION} ({source:?} to {target:?})")
292 }
293 Self::AudioBuffers => f.write_str(AUDIO_BUFFERS),
294 Self::AudioSampleFormat => f.write_str(AUDIO_SAMPLE_FORMAT),
295 Self::StateSize => write!(f, "{STATE_SIZE} ({} MiB)", crate::MAX_STATE_BYTES >> 20),
296 Self::StateBytes => f.write_str(STATE_BYTES),
297 Self::ParameterChoicePage => write!(
298 f,
299 "{PARAMETER_CHOICE_PAGE} ({})",
300 crate::PARAMETER_CHOICE_PAGE_SIZE
301 ),
302 Self::PresetSize => write!(f, "{PRESET_SIZE} ({} MiB)", crate::MAX_PRESET_BYTES >> 20),
303 Self::Automation => f.write_str(AUTOMATION),
304 Self::NotAutomatable { id } => write!(f, "{NOT_AUTOMATABLE} ({id})"),
305 Self::Transport => f.write_str(TRANSPORT),
306 Self::HostIdentity => f.write_str(HOST_IDENTITY),
307 Self::PresetDiscoveryTarget => f.write_str(PRESET_DISCOVERY_TARGET),
308 Self::EmptyChain => f.write_str(EMPTY_CHAIN),
309 Self::SampleRate => f.write_str(SAMPLE_RATE),
310 Self::BlockSize => f.write_str(BLOCK_SIZE),
311 Self::OutputCount => f.write_str(OUTPUT_COUNT),
312 Self::MainBus => f.write_str(MAIN_BUS),
313 Self::Slot => f.write_str(INVALID_SLOT),
314 Self::ParameterText => write!(f, "{PARAMETER_TEXT} ({})", crate::PARAMETER_TEXT_BYTES),
315 Self::PlainParameterValue => f.write_str(PLAIN_PARAMETER_VALUE),
316 Self::ParameterValue => f.write_str(PARAMETER_VALUE),
317 Self::UnknownParameter { id } => write!(f, "{UNKNOWN_PARAMETER} ({id})"),
318 Self::ReadOnlyParameter { id } => write!(f, "{READ_ONLY_PARAMETER} ({id})"),
319 Self::PathEncoding => f.write_str(PATH_ENCODING),
320 Self::RealtimeQuantum => f.write_str(REALTIME_QUANTUM),
321 Self::RealtimeLatency => f.write_str(REALTIME_LATENCY),
322 Self::RealtimeDry => f.write_str(REALTIME_DRY),
323 Self::RemoteRegion => f.write_str(REMOTE_REGION),
324 Self::RemoteEditor => f.write_str(REMOTE_EDITOR),
325 }
326 }
327}
328
329impl std::error::Error for InputError {}
330
331const PATH_ENCODING: &str = "plugin bundle and preset paths must be valid Unicode";
332const REALTIME_QUANTUM: &str =
333 "a realtime quantum must be at least one frame and at most the prepared maximum block size";
334const REALTIME_LATENCY: &str = "a realtime latency must be one, two or three quanta";
335const REALTIME_DRY: &str = "a dry fallback needs as many output channels as input channels";
336const REMOTE_EDITOR: &str = "the slot has no open remote editor";
337const REMOTE_REGION: &str = "a remote editor needs a region set, with a finite position and a positive size within an existing display";
338
339const INPUT: &str = "invalid render input";
340const LATENCY_CHANGED: &str = "the processor's latency changed during rendering";
341const LATENCY_NOT_APPLIED: &str = "a plugin announced a new latency that is not applied yet; reset \
342 or prepare the chain again before rendering";
343const TAIL_DURATION: &str = "maximum tail seconds must be finite and non-negative";
344const SILENCE_THRESHOLD: &str = "silence threshold must be finite and non-negative";
345const SILENCE_HOLD: &str = "silence hold seconds must be finite and non-negative";
346const RENDER_LENGTH: &str =
347 "render duration or sample buffer length exceeds the representable range";
348const SESSION_CLOSED: &str = "the render session is no longer active";
349const NON_FINITE_OUTPUT: &str = "the processor output a NaN or infinite sample";
350pub(crate) const MESSAGE_TOO_LARGE: &str = "the message exceeds the maximum size";
351pub(crate) const MALFORMED_MESSAGE: &str = "the message could not be decoded";
352pub(crate) const MALFORMED_MENU: &str = "a menu's items do not form a tree within the depth limit";
353
354#[derive(Clone, Debug, PartialEq, Eq)]
356#[non_exhaustive]
357pub enum RenderError {
358 SessionClosed,
360 Input(InputError),
367 TailDuration,
369 SilenceThreshold,
371 SilenceHold,
373 LengthOverflow,
375 LatencyChanged {
377 before: u32,
379 after: u32,
381 },
382 LatencyNotApplied,
385 NonFiniteOutput {
389 frame: usize,
391 },
392}
393
394impl RenderError {
395 pub fn kind(&self) -> FailureKind {
397 match self {
398 Self::SessionClosed => FailureKind::Closed,
399 Self::Input(_)
400 | Self::TailDuration
401 | Self::SilenceThreshold
402 | Self::SilenceHold
403 | Self::LengthOverflow => FailureKind::InvalidInput,
404 Self::LatencyChanged { .. } => FailureKind::Configuration,
405 Self::LatencyNotApplied => FailureKind::RestartRequired,
406 Self::NonFiniteOutput { .. } => FailureKind::Processing,
407 }
408 }
409}
410
411impl fmt::Display for RenderError {
412 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
413 match self {
414 RenderError::SessionClosed => f.write_str(SESSION_CLOSED),
415 RenderError::Input(_) => f.write_str(INPUT),
416 RenderError::TailDuration => f.write_str(TAIL_DURATION),
417 RenderError::SilenceThreshold => f.write_str(SILENCE_THRESHOLD),
418 RenderError::SilenceHold => f.write_str(SILENCE_HOLD),
419 RenderError::LengthOverflow => f.write_str(RENDER_LENGTH),
420 RenderError::LatencyChanged { before, after } => {
421 write!(f, "{LATENCY_CHANGED} ({before} to {after} samples)")
422 }
423 RenderError::LatencyNotApplied => f.write_str(LATENCY_NOT_APPLIED),
424 RenderError::NonFiniteOutput { frame } => {
425 write!(f, "{NON_FINITE_OUTPUT} (at output frame {frame})")
426 }
427 }
428 }
429}
430
431impl std::error::Error for RenderError {
432 fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
433 match self {
434 RenderError::Input(error) => Some(error),
435 _ => None,
436 }
437 }
438}