plughost-core 0.2.6

Shared types and offline render rules for plughost
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
use std::fmt;

/// Format-independent error categories. These describe the failure, not an automatic retry policy.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum FailureKind {
    /// Caller input violated a host contract.
    InvalidInput,
    /// The format or plugin does not implement the requested operation.
    Unsupported,
    /// The requested plugin or native object was not found.
    NotFound,
    /// A module or plugin instance could not be loaded or initialized.
    Load,
    /// The requested processing configuration could not be applied.
    Configuration,
    /// Processing was requested before successful preparation.
    NotPrepared,
    /// The instance or its owning handle is closed.
    Closed,
    /// Processing cannot continue until the reported restart condition is handled.
    RestartRequired,
    /// The operation requires the editor to be closed.
    EditorOpen,
    /// The saved state belongs to another plugin identity.
    StateMismatch,
    /// Native state could not be saved, decoded, or restored.
    State,
    /// A plugin processing call or its output failed validation.
    Processing,
    /// A native editor operation failed.
    Editor,
    /// The host could not complete a platform or resource operation.
    Host,
    /// A helper response or shared-memory message violated the internal protocol.
    Protocol,
    /// The helper exited unexpectedly or was terminated.
    Crashed,
    /// An operation exceeded its configured deadline.
    TimedOut,
    /// The application cancelled the operation, which terminated the helper.
    Cancelled,
}

/// A portable category with the original diagnostic message, including native codes when provided.
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub struct Failure {
    /// Portable category for programmatic handling.
    pub kind: FailureKind,
    /// Human-readable diagnostic; do not parse it as a stable error code.
    pub message: String,
}

impl Failure {
    /// Constructs a category and diagnostic report.
    #[must_use]
    pub fn new(kind: FailureKind, message: impl Into<String>) -> Self {
        Self {
            kind,
            message: message.into(),
        }
    }
}

impl fmt::Display for Failure {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(&self.message)
    }
}

impl std::error::Error for Failure {}

const EVENT_CAPACITY: &str =
    "the block or pending edit queue exceeds MAX_BLOCK_EVENTS or MAX_BLOCK_SYSEX_BYTES";
const EVENT_PORT_COUNT: &str = "the event routing exceeds the maximum ports per slot or chain";
const DUPLICATE_EVENT_PORT: &str = "event output port ID occurs more than once in one slot";
const EVENT_ROUTE: &str = "the event route does not name an available source";
const EVENT_PORT: &str = "the event names an event port the chain does not have";
const AUDIO_SLOT_COUNT: &str = "the audio configuration needs one routing entry per plugin";
const AUDIO_BUS_COUNT: &str = "the audio configuration exceeds the maximum buses per direction";
const AUDIO_CHANNEL_COUNT: &str =
    "the audio configuration exceeds the maximum active channels per direction";
const DUPLICATE_AUDIO_BUS: &str = "audio bus ID occurs more than once in one direction";
const AUDIO_BUS_LAYOUT: &str = "an active audio bus must have a nonempty layout";
const AUDIO_ROUTE: &str = "the audio route does not name an available source";
const CHANNEL_ADAPTATION: &str =
    "the explicit channel adaptation does not match the source and target layouts";
const BLOCK_EVENTS: &str = "events must be notes, expressions in their ranges, MIDI 1.0 channel messages or complete \
     system exclusive messages, in offset order and inside the block or render input";
const AUDIO_BUFFERS: &str = "audio buffers must match the bus channel count and contain equal frame \
     counts, at most the prepared maximum block size";
const AUDIO_SAMPLE_FORMAT: &str =
    "audio sample precision does not match the prepared configuration";
const STATE_SIZE: &str = "plugin component and controller state together exceed the maximum size";
const STATE_BYTES: &str = "the bytes are not a plugin state this plughost version can read";
const PARAMETER_CHOICE_PAGE: &str =
    "parameter choice pages need a valid start index and a nonzero entry count within the maximum";
const PRESET_SIZE: &str = "the preset file exceeds the maximum size";
const AUTOMATION: &str =
    "automation must be ordered, normalized, inside the block and address a loaded slot";
const NOT_AUTOMATABLE: &str = "parameter cannot be automated";
const TRANSPORT: &str =
    "transport values must be finite, representable, and describe a valid tempo, meter and loop";
const SAMPLE_RATE: &str = "sample rate must be finite and greater than zero";
const BLOCK_SIZE: &str = "maximum block size must be between 1 and i32::MAX";
const OUTPUT_COUNT: &str = "the configuration needs one output layout per plugin";
const EMPTY_CHAIN: &str = "a chain must contain at least one plugin";
const INVALID_SLOT: &str = "the slot does not contain a loaded plugin";
const PARAMETER_VALUE: &str = "parameter value must be finite and normalized to 0..=1";
const PARAMETER_TEXT: &str =
    "parameter text must be accepted by the plugin, NUL-free and within the maximum UTF-8 bytes";
const PLAIN_PARAMETER_VALUE: &str =
    "plain parameter value must be finite and within the native parameter range";
const UNKNOWN_PARAMETER: &str = "the parameter does not exist";
const READ_ONLY_PARAMETER: &str = "the parameter is read-only";
const HOST_IDENTITY: &str =
    "host identity must be NUL-free, with a non-empty name of at most 127 UTF-16 code units";
const PRESET_DISCOVERY_TARGET: &str = "a preset discovery target needs a non-empty, NUL-free provider \
     ID and, for a file location, an absolute, NUL-free Unicode path, each within the text limit";

/// Messages shared by several plughost crates.
pub const MAIN_BUS: &str = "the plugin has no main audio bus for the requested layout";
/// Diagnostic for excessive native output; reset is required before further processing.
pub 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";
/// Diagnostic for a missing native event port.
pub const UNKNOWN_EVENT_PORT: &str = "the plugin has no event port with this ID";
/// Prefix identifying processing-path audit diagnostics.
pub const AUDIT: &str = "real-time audit:";
/// Diagnostic prefix for output event kinds with no portable representation.
pub const UNCONVERTIBLE_OUTPUT_EVENTS: &str = "output events with no portable form (chords, scales, choke, text expression, MIDI 2.0) were not delivered:";
/// Diagnostic for state belonging to another plugin class.
pub const STATE_MISMATCH: &str = "the state belongs to a different plugin class";
/// Diagnostic for a chain without a prepared processing configuration.
pub const CHAIN_NOT_PREPARED: &str = "the chain is not prepared";

/// A request rejected before changing the plugin or its processing configuration.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum InputError {
    /// Routing entries do not match the number of loaded plugin slots.
    AudioSlotCount,
    /// A direction exceeds `MAX_AUDIO_BUSES`.
    AudioBusCount,
    /// A direction exceeds `MAX_AUDIO_CHANNELS` active channels.
    AudioChannelCount,
    /// A native bus ID occurs more than once in one direction.
    DuplicateAudioBus {
        /// Native ID associated with the invalid request.
        id: u64,
    },
    /// An active bus requested the empty layout.
    AudioBusLayout {
        /// Native ID associated with the invalid request.
        id: u64,
    },
    /// An active input bus names a missing or inactive source.
    AudioRoute {
        /// Zero-based destination plugin slot.
        slot: usize,
        /// Native destination input bus ID.
        bus: u64,
    },
    /// The requested conversion does not match the two layouts.
    ChannelAdaptation {
        /// Layout supplied by the source.
        source: crate::Layout,
        /// Layout requested by the destination.
        target: crate::Layout,
    },
    /// Channel counts or per-channel frame lengths do not match the prepared buses, or a block
    /// has more frames than the prepared maximum block size.
    AudioBuffers,
    /// Sample precision differs from the prepared configuration.
    AudioSampleFormat,
    /// Aggregate component and controller state exceeds `MAX_STATE_BYTES`.
    StateSize,
    /// Bytes given to `PluginState::from_bytes` are not a state that plughost wrote, or are one
    /// of a later format version.
    StateBytes,
    /// A discrete-choice page has an invalid start index or count.
    ParameterChoicePage,
    /// Native preset bytes exceed `MAX_PRESET_BYTES`.
    PresetSize,
    /// Transport contains a non-finite, unrepresentable, or inconsistent value.
    Transport,
    /// Automation is unordered, out of range, outside the block, or names a missing slot.
    Automation,
    /// The addressed parameter does not support sample-timed automation.
    NotAutomatable {
        /// Native ID associated with the invalid request.
        id: u64,
    },
    /// Host text contains NUL, or its name is empty or exceeds 127 UTF-16 code units.
    HostIdentity,
    /// A preset discovery provider ID is empty, contains NUL or exceeds
    /// [`PRESET_DISCOVERY_TEXT_BYTES`](crate::PRESET_DISCOVERY_TEXT_BYTES), or its file location
    /// is not an absolute Unicode path within that size and without NUL.
    PresetDiscoveryTarget,
    /// A chain was created or configured without a plugin.
    EmptyChain,
    /// The sample rate is not finite and greater than zero.
    SampleRate,
    /// Maximum block size is outside `1..=i32::MAX`.
    BlockSize,
    /// The legacy configuration does not provide one output layout per plugin.
    OutputCount,
    /// The plugin has no main audio bus with the requested layout.
    MainBus,
    /// The slot index does not address a loaded plugin.
    Slot,
    /// The parameter value is not finite and normalized to `0..=1`.
    ParameterValue,
    /// Display text is excessive, contains NUL, or is rejected by the plugin.
    ParameterText,
    /// The native-unit parameter value is non-finite or outside the native range.
    PlainParameterValue,
    /// The requested parameter ID does not exist.
    UnknownParameter {
        /// Native ID associated with the invalid request.
        id: u64,
    },
    /// A host edit addressed a read-only parameter.
    ReadOnlyParameter {
        /// Native ID associated with the invalid request.
        id: u64,
    },
    /// Combined automation/events or SysEx bytes exceed the per-block capacity.
    EventCapacity,
    /// An event routing direction exceeds `MAX_EVENT_PORTS`.
    EventPortCount,
    /// An output port ID occurs more than once in a slot.
    DuplicateEventPort {
        /// Native ID associated with the invalid request.
        id: u64,
    },
    /// An event input route names an unavailable source.
    EventRoute {
        /// Zero-based destination plugin slot.
        slot: usize,
        /// Native destination event input port ID.
        port: u64,
    },
    /// An event names an external port the chain does not expose.
    EventPort {
        /// Invalid zero-based external event port index.
        port: usize,
    },
    /// Events that are not valid, in offset order, or inside the block, or for a render before
    /// the end of its input.
    Events,
    /// A bundle or preset path cannot be represented by the helper's Unicode path protocol.
    PathEncoding,
    /// A realtime quantum is zero frames or exceeds the prepared maximum block size.
    RealtimeQuantum,
    /// A realtime latency is not one, two or three quanta.
    RealtimeLatency,
    /// A dry fallback needs as many output channels as input channels.
    RealtimeDry,
    /// No remote editor region was set, or the one given does not have a finite position and a
    /// positive size within an existing display.
    RemoteRegion,
    /// The slot has no open remote editor.
    RemoteEditor,
}

impl fmt::Display for InputError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::EventCapacity => f.write_str(EVENT_CAPACITY),
            Self::EventPortCount => {
                write!(f, "{EVENT_PORT_COUNT} ({})", crate::MAX_EVENT_PORTS)
            }
            Self::DuplicateEventPort { id } => write!(f, "{DUPLICATE_EVENT_PORT} ({id})"),
            Self::EventRoute { slot, port } => {
                write!(f, "{EVENT_ROUTE} (slot {slot}, input port {port})")
            }
            Self::EventPort { port } => write!(f, "{EVENT_PORT} ({port})"),
            Self::Events => f.write_str(BLOCK_EVENTS),
            Self::AudioSlotCount => f.write_str(AUDIO_SLOT_COUNT),
            Self::AudioBusCount => write!(f, "{AUDIO_BUS_COUNT} ({})", crate::MAX_AUDIO_BUSES),
            Self::AudioChannelCount => {
                write!(f, "{AUDIO_CHANNEL_COUNT} ({})", crate::MAX_AUDIO_CHANNELS)
            }
            Self::DuplicateAudioBus { id } => write!(f, "{DUPLICATE_AUDIO_BUS} ({id})"),
            Self::AudioBusLayout { id } => write!(f, "{AUDIO_BUS_LAYOUT} ({id})"),
            Self::AudioRoute { slot, bus } => {
                write!(f, "{AUDIO_ROUTE} (slot {slot}, input bus {bus})")
            }
            Self::ChannelAdaptation { source, target } => {
                write!(f, "{CHANNEL_ADAPTATION} ({source:?} to {target:?})")
            }
            Self::AudioBuffers => f.write_str(AUDIO_BUFFERS),
            Self::AudioSampleFormat => f.write_str(AUDIO_SAMPLE_FORMAT),
            Self::StateSize => write!(f, "{STATE_SIZE} ({} MiB)", crate::MAX_STATE_BYTES >> 20),
            Self::StateBytes => f.write_str(STATE_BYTES),
            Self::ParameterChoicePage => write!(
                f,
                "{PARAMETER_CHOICE_PAGE} ({})",
                crate::PARAMETER_CHOICE_PAGE_SIZE
            ),
            Self::PresetSize => write!(f, "{PRESET_SIZE} ({} MiB)", crate::MAX_PRESET_BYTES >> 20),
            Self::Automation => f.write_str(AUTOMATION),
            Self::NotAutomatable { id } => write!(f, "{NOT_AUTOMATABLE} ({id})"),
            Self::Transport => f.write_str(TRANSPORT),
            Self::HostIdentity => f.write_str(HOST_IDENTITY),
            Self::PresetDiscoveryTarget => f.write_str(PRESET_DISCOVERY_TARGET),
            Self::EmptyChain => f.write_str(EMPTY_CHAIN),
            Self::SampleRate => f.write_str(SAMPLE_RATE),
            Self::BlockSize => f.write_str(BLOCK_SIZE),
            Self::OutputCount => f.write_str(OUTPUT_COUNT),
            Self::MainBus => f.write_str(MAIN_BUS),
            Self::Slot => f.write_str(INVALID_SLOT),
            Self::ParameterText => write!(f, "{PARAMETER_TEXT} ({})", crate::PARAMETER_TEXT_BYTES),
            Self::PlainParameterValue => f.write_str(PLAIN_PARAMETER_VALUE),
            Self::ParameterValue => f.write_str(PARAMETER_VALUE),
            Self::UnknownParameter { id } => write!(f, "{UNKNOWN_PARAMETER} ({id})"),
            Self::ReadOnlyParameter { id } => write!(f, "{READ_ONLY_PARAMETER} ({id})"),
            Self::PathEncoding => f.write_str(PATH_ENCODING),
            Self::RealtimeQuantum => f.write_str(REALTIME_QUANTUM),
            Self::RealtimeLatency => f.write_str(REALTIME_LATENCY),
            Self::RealtimeDry => f.write_str(REALTIME_DRY),
            Self::RemoteRegion => f.write_str(REMOTE_REGION),
            Self::RemoteEditor => f.write_str(REMOTE_EDITOR),
        }
    }
}

impl std::error::Error for InputError {}

const PATH_ENCODING: &str = "plugin bundle and preset paths must be valid Unicode";
const REALTIME_QUANTUM: &str =
    "a realtime quantum must be at least one frame and at most the prepared maximum block size";
const REALTIME_LATENCY: &str = "a realtime latency must be one, two or three quanta";
const REALTIME_DRY: &str = "a dry fallback needs as many output channels as input channels";
const REMOTE_EDITOR: &str = "the slot has no open remote editor";
const REMOTE_REGION: &str = "a remote editor needs a region set, with a finite position and a positive size within an existing display";

const INPUT: &str = "invalid render input";
const LATENCY_CHANGED: &str = "the processor's latency changed during rendering";
const LATENCY_NOT_APPLIED: &str = "a plugin announced a new latency that is not applied yet; reset \
     or prepare the chain again before rendering";
const TAIL_DURATION: &str = "maximum tail seconds must be finite and non-negative";
const SILENCE_THRESHOLD: &str = "silence threshold must be finite and non-negative";
const SILENCE_HOLD: &str = "silence hold seconds must be finite and non-negative";
const RENDER_LENGTH: &str =
    "render duration or sample buffer length exceeds the representable range";
const SESSION_CLOSED: &str = "the render session is no longer active";
const NON_FINITE_OUTPUT: &str = "the processor output a NaN or infinite sample";
pub(crate) const MESSAGE_TOO_LARGE: &str = "the message exceeds the maximum size";
pub(crate) const MALFORMED_MESSAGE: &str = "the message could not be decoded";
pub(crate) const MALFORMED_MENU: &str = "a menu's items do not form a tree within the depth limit";

/// Errors from the offline render rules.
#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum RenderError {
    /// The streaming render session has already finished, been cancelled or failed.
    SessionClosed,
    /// A shared processing or control input contract was violated, including input channels
    /// that do not match the processor or do not all have the requested number of frames
    /// ([`InputError::AudioBuffers`]) and render events
    /// that are not valid, not in offset order or not before the end of the input
    /// ([`InputError::Events`]). Events on ports the processor lacks fail its
    /// [`Process::validate_events`](crate::render::Process::validate_events).
    Input(InputError),
    /// Maximum tail duration is not finite and non-negative.
    TailDuration,
    /// Silence threshold is not finite and non-negative.
    SilenceThreshold,
    /// Silence hold duration is not finite and non-negative.
    SilenceHold,
    /// Render duration or sample storage exceeds the representable range.
    LengthOverflow,
    /// The processor’s latency changed during a render.
    LatencyChanged {
        /// Latency at render start, in frames.
        before: u32,
        /// New latency, in frames.
        after: u32,
    },
    /// A plugin announced a new latency before the render started, and the processor has not
    /// applied it yet.
    LatencyNotApplied,
    /// The processor output a NaN or infinite sample, first at `frame` of the output after the
    /// removed latency (for a session, of the `push` or `finish` call), whatever the tail policy.
    /// Output from the start of the failing block on is not delivered.
    NonFiniteOutput {
        /// The first output frame holding one, in any channel.
        frame: usize,
    },
}

impl RenderError {
    /// Classifies a render error without deriving a retry policy.
    pub fn kind(&self) -> FailureKind {
        match self {
            Self::SessionClosed => FailureKind::Closed,
            Self::Input(_)
            | Self::TailDuration
            | Self::SilenceThreshold
            | Self::SilenceHold
            | Self::LengthOverflow => FailureKind::InvalidInput,
            Self::LatencyChanged { .. } => FailureKind::Configuration,
            Self::LatencyNotApplied => FailureKind::RestartRequired,
            Self::NonFiniteOutput { .. } => FailureKind::Processing,
        }
    }
}

impl fmt::Display for RenderError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            RenderError::SessionClosed => f.write_str(SESSION_CLOSED),
            RenderError::Input(_) => f.write_str(INPUT),
            RenderError::TailDuration => f.write_str(TAIL_DURATION),
            RenderError::SilenceThreshold => f.write_str(SILENCE_THRESHOLD),
            RenderError::SilenceHold => f.write_str(SILENCE_HOLD),
            RenderError::LengthOverflow => f.write_str(RENDER_LENGTH),
            RenderError::LatencyChanged { before, after } => {
                write!(f, "{LATENCY_CHANGED} ({before} to {after} samples)")
            }
            RenderError::LatencyNotApplied => f.write_str(LATENCY_NOT_APPLIED),
            RenderError::NonFiniteOutput { frame } => {
                write!(f, "{NON_FINITE_OUTPUT} (at output frame {frame})")
            }
        }
    }
}

impl std::error::Error for RenderError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            RenderError::Input(error) => Some(error),
            _ => None,
        }
    }
}