Expand description
Shared types and offline render rules for plughost.
See the integration guide for end-to-end processing, routing, scanning, and recovery contracts.
Modules§
- remote
- Remote editors: editors a remote-mode helper shows in a region of a display that the application reads, for someone who is not in front of the machine. The application owns the display, reading the region, and sending what it reads.
- render
- Offline render rules shared by every processing path: the output is aligned with the input by removing the reported latency, and the tail after the input is rendered as well.
Structs§
- Audio
BusConfig - Requested layout and activation for one native audio bus.
- Audio
BusInfo - A native bus snapshot. An unknown layout is not inferred from its channel count. IDs are scoped to a direction and the selected native configuration.
- Audio
Config - Requested native buses. Buses omitted from a direction are inactive. Native layout/precision negotiation follows validation; successful preparation returns the complete negotiated map.
- Audio
Configuration - A named native bus configuration, such as a CLAP audio-port configuration.
- Audio
Input Route - An input bus request together with its source and explicit channel conversion.
- Automation
Event - A point on one slot’s automation lane. Offsets are relative to the supplied block/render. Points hold their value until the next point; simultaneous points preserve input order.
- BarPosition
- Caller-supplied start and numbering of the current musical bar.
- Block
Context - Explicit block duration, independent of the presence of audio channels.
- Bypass
State - Native bypass support and its last queried state.
- Capabilities
- A snapshot for the current platform and plugin configuration. Static scan metadata does not establish these capabilities. Unknown is distinct from explicitly unsupported.
- Capability
Report - Native plugin evidence and the isolated Chain API’s implementation for the queried slot. A feature needs both sides to support it. This does not describe the in-process API’s limits.
- Change
Batch - Timing notifications coalesce by slot, retaining last-observed order. Intermediate values
are not an audit trail. On overflow use
snapshotto replace the entire consumer view. - ClassId
- A plugin class identifier in its format’s canonical form, so that two IDs of one class
compare equal however they were written. It comes with its format in a
PluginId. For VST3 it is the 32-digit hexadecimal class ID in the form.vstpresetfiles use, and for Audio Units the component type, subtype, and manufacturer codes as 24 hexadecimal digits; both are kept in upper case. For CLAP it is the plugin ID as given. - Diagnostic
- One bounded diagnostic record with optional plugin and slot context.
- Diagnostic
Batch - Records drained since the last snapshot. Loss is explicit; this is not an audit log.
- Discovered
Preset - One native preset discovered by a CLAP provider.
- Event
- An event on an event port at a sample offset: from the start of the block when processing
blocks, and from the start of the input when rendering. Each format receives it in its own
form; see
EventData. Events are kept in anEvents, which holds the system exclusive bytes an event borrows. - Event
Config - The event ports a slot’s native preparation activates.
- Event
Input Route - One source delivered to a native event input port. Several routes to one port merge in offset order; at equal offsets, events keep the order of the routes, then their source order.
- Event
Port Info - A native event port. IDs are scoped to a direction;
indexis the native position that directly hosted plugins use as aEvent::port. - Events
- Events in the order they were pushed: fixed records, with the system exclusive bytes of all of
them in one area, so a system exclusive message costs no allocation of its own. Iterating
gives
Events that borrow those bytes. - Events
Iter - The events of an
Events, in order. - Factory
Preset - A named native factory preset or program.
- Failure
- A portable category with the original diagnostic message, including native codes when provided.
- Host
Identity - Identity of the application hosting the plugins. VST3 receives the name; CLAP receives all three fields. Audio Units have no equivalent identity callback in the current host API.
- Loop
Region - Musical positions are quarter notes, including for compound meters.
- Note
- A note, or the notes a note off addresses. A note with an ID is told apart from other notes on the same key by it; without one, it addresses notes by port, channel and key, as MIDI does.
- Note
Expression - A change of one expression of the notes it addresses, which applies from its offset until the next change of the same expression. With an ID it addresses that note; without one, every note on its port, channel and key.
- Parameter
Change - A normalized parameter value that takes effect at a sample offset within a block.
- Parameter
Choice - One discrete parameter choice and its native display conversion.
- Parameter
Choice Page - A bounded slice of a discrete parameter’s native choices.
- Parameter
Details - A fresh query. Endpoints describe the normalized mapping, not a linear scale.
- Parameter
Event Batch - Overflow loses ordering continuity: cancel open gestures and requery metadata and values.
- Parameter
Flags - Native parameter properties. All flags default to false.
- Parameter
Group - One native unit or group in a parameter’s root-to-leaf hierarchy.
- Parameter
Info - Native parameter identity, labels, normalized default, and edit capabilities.
- Plugin
Id - The identity of a plugin class, independent of where it is installed: its format and class
ID. Store it, not a path, with the work that uses the plugin, and find the installed class
again with the scanner’s
Catalog::resolve. - Plugin
Info - A plugin class as its format describes it.
- Plugin
Ref - A plugin class to load: its identity and where it is installed. VST3 and CLAP classes live in a bundle; Audio Units have none, the system registry finds them. Build it with the format’s constructor, or take it from the scanner’s catalog.
- Plugin
State - A plugin’s saved state with the identity of the class it belongs to. Its contents are opaque:
store it with
PluginState::to_bytesand read it back withPluginState::from_bytes, which later plughost versions keep reading. Where it is stored is up to the application. - Plugin
Timing - A plugin’s timing as its owning thread last read it. The latency is the one the plugin was activated with: it changes only when the plugin is prepared again or reset, so processing and rendering keep one alignment in between. The tail follows the plugin’s reports.
- Preset
Discovery - Presets found at one provider location. A file in a crawled directory that the provider refused is listed with its failure instead of failing the other files.
- Preset
Discovery Target - One provider and location to inspect without loading an audio instance.
- Preset
File Failure - One preset file’s discovery failure, without failing the surrounding directory.
- Preset
File Type - File type advertised by a CLAP preset provider.
- Preset
Flags - What a CLAP preset provider says of a location’s, soundpack’s or preset’s content. Bits that later CLAP versions define are kept, though they have no name here.
- Preset
Info - Plugin identity and metadata read from a native preset container.
- Preset
Location Info - Named discovery location advertised by a CLAP provider.
- Preset
Plugin Id - Native plugin ABI and identity to which a discovered preset applies.
- Preset
Provider Info - A CLAP module’s preset provider and its advertised discovery metadata.
- Preset
Soundpack - Native metadata for a provider’s soundpack.
- Process
Config - Processing configuration for a plugin’s main input and output buses.
- Routed
Chain Config - Explicit serial-chain configuration, validated before native preparation.
- Slot
Audio Config - Audio and event routing for a single plugin slot.
- Slot
Change - Latest timing observation for one plugin in a chain.
- Slot
Event Config - A slot’s event routing. Native event ports not named here are left inactive where the format allows. The last slot’s collected outputs, in this order, are the chain’s event outputs.
- Time
Signature - Musical meter; numerator must be nonzero and denominator a power of two.
- Transport
- A snapshot at the first sample of a block.
Nonefields are unavailable, never synthesized. A seek is a discontinuity between consecutive snapshots. Loop wrapping is caller-owned.
Enums§
- Audio
BusRole - Native distinction between a main bus and an additional bus.
- Audio
Direction - Direction of an audio or event port relative to its plugin.
- Audio
Source - Source of one slot’s input bus in a serial chain.
- Channel
Adaptation - Explicit channel adaptation. Surround layouts are never inferred, reordered or downmixed.
- Diagnostic
Severity - Severity reported by the plugin or host, including CLAP’s two misbehavior categories.
- Event
Data - What an event carries.
- Event
Source - Where a slot’s event input port takes events from.
- Expression
Kind - The expressions a single note has, with the value ranges CLAP defines for them. VST3 receives the first six as note expression values and pressure as poly pressure.
- Factory
Preset Id - Native factory program identity, scoped to one plugin class.
- Failure
Kind - Format-independent error categories. These describe the failure, not an automatic retry policy.
- Input
Error - A request rejected before changing the plugin or its processing configuration.
- Layout
- Channel layout of an audio bus. Each layout has one channel order, listed on its variant. Formats whose native order differs are mapped explicitly; a layout a format cannot express is refused rather than approximated.
- Message
- A decoded channel message. Channels are 0..=15; data values are 7-bit except the 14-bit pitch bend (8192 is the center).
- Parameter
Event - Notifications reported by the plugin, in observed order, but for two merges: a value reported for an ID replaces the one queued for it when no gesture of that ID or metadata change came between them, and a values change replaces the one queued before it. Values are normalized to 0..=1.
- Plugin
Format - Native plugin ABI used for discovery and loading.
- Plugin
Kind - Broad native classification used in discovery results.
- Preset
Location - Native CLAP provider location used both for discovery and preset loading.
- Preset
Metadata - Native file metadata, kept separate from a plugin’s opaque state.
- Process
Mode - The processing mode reported to the plugin. Offline rendering is not paced to wall-clock time;
Realtimeonly changes what the plugin is told, for plugins that misbehave in offline mode. - Render
Error - Errors from the offline render rules.
- Sample
Format - Floating-point precision of the prepared audio buffers.
- State
Purpose - Why a state is being saved or applied. Unsupported native contexts are explicit errors.
- Support
- Evidence from a native query, not a guarantee that an operation will succeed.
Constants§
- CHANGE_
CAPACITY - Maximum retained timing changes before consumers must resynchronize.
- DIAGNOSTIC_
CAPACITY - Maximum retained records per buffer and per helper snapshot.
- DIAGNOSTIC_
MESSAGE_ BYTES - Maximum UTF-8 bytes retained from one diagnostic message.
- MAX_
ALIGNMENT_ BYTES - Maximum sample storage in one prepared chain’s external-input alignment delays and host bypass delays (256 MiB). Preparation or staged state replacement fails before committing if the external-input delays, with the host bypass delays of the slots whose host bypass is on, exceed the budget; a slot whose host bypass is off gets its delay only while it fits, and cannot turn host bypass on without it. During replacement both the old bank and its prepared replacement may coexist.
- MAX_
AUDIO_ BUSES - Bus enumeration and configuration are bounded before allocation or native iteration.
- MAX_
AUDIO_ CHANNELS - Maximum active channel count in one direction, including all buses.
- MAX_
BLOCK_ EVENTS - Maximum events one processing block takes, counting automation points too: each automation point and each event (a MIDI message, a system exclusive message, a note on or off, or a note expression) is one record. For a chain this is the aggregate across all slots, and overflow rejects the block before DSP. A plugin’s event output in one block is bounded by the same count. Render timelines may contain more events provided every submitted block fits.
- MAX_
BLOCK_ SYSEX_ BYTES - Maximum system exclusive bytes, counting each message’s F0 and F7, that one block’s events may carry: the chain’s input, and each plugin’s output. They are kept apart from the fixed-size event records.
- MAX_
EVENT_ PORTS - Maximum external event inputs of a chain, and event routes or collected outputs of one slot.
- MAX_
FACTORY_ PRESETS - Maximum native factory program catalog returned by one plugin instance.
- MAX_
NOTE_ ID - The largest note ID. IDs are the non-negative 32-bit integers CLAP and VST3 use.
- MAX_
PRESET_ BYTES - Bound for encoded preset files, separate from opaque project state and the IPC frame limit.
- MAX_
STATE_ BYTES - Maximum aggregate processor and controller payload for one project state (128 MiB). This does not include the plugin’s identity strings or serialization framing.
- PARAMETER_
CHOICE_ PAGE_ SIZE - Maximum number of discrete choices returned by a single page request.
- PARAMETER_
EVENT_ CAPACITY - Maximum queued parameter notifications. Past it the oldest record is dropped, but not a metadata change.
- PARAMETER_
TEXT_ BYTES - Bound for caller text and native UTF-8 displays (VST3 has its own String128 output bound).
- PRESET_
DISCOVERY_ TEXT_ BYTES - Maximum UTF-8 bytes accepted for one provider text field.
Traits§
- Sample
- An audio sample type the plugin formats can process:
f32orf64. It is sealed: only this crate implements it, so a sample’sFORMATalways names its own type.