Skip to main content

Crate plughost

Crate plughost 

Source
Expand description

Load and run VST3, Audio Unit, and CLAP plugins from Rust, isolated in helper processes.

Plugin code never runs in the application’s process. A Scanner finds installed plugins, running one short-lived helper per bundle; a Chain loads plugins into one helper and processes audio through them in order. If a plugin crashes or hangs, only its helper ends, and errors report the last known plugin slot when available.

The helper is a small executable the application builds around plughost_helper::run, from the same plughost version. On macOS it is a background .app signed with the Hardened Runtime and the disable-library-validation and allow-unsigned-executable-memory entitlements.

Chain::take_diagnostics drains structured plugin logs and helper operation failures. Startup errors and arbitrary plugin stderr remain on standard error; plugin stdout is discarded.

Chain::prepare_audio selects native buses, explicit routing and f32 or f64 precision; Chain::main_bus_config builds the common serial main-bus configuration. Rendering retains the prepared sample type. For instruments with an empty input slice, specify render::<f32, _> or render::<f64, _> so Rust can infer the output precision.

The detailed API guide covers scanning, cancellation, routing, state, and failure contracts.

§Stereo effect rendering

use std::path::Path;
use plughost::{
    Chain, Events, Layout, PluginRef, RenderOptions, SpawnOptions, render,
};

fn render_effect(
    helper: &Path,
    plugin: PluginRef,
    left: &[f32],
    right: &[f32],
) -> Result<Vec<Vec<f32>>, plughost::Error> {
    let mut chain = Chain::spawn(helper, &[plugin.into()], &SpawnOptions::default())?;
    let config = chain.main_bus_config(48_000.0, 512, Layout::Stereo, &[Layout::Stereo])?;
    chain.prepare_audio(&config)?;
    let output = render(
        &mut chain,
        &[left, right],
        left.len(),
        &Events::new(),
        &RenderOptions::default(),
    )?;
    Ok(output.channels)
}

Modules§

remote
Remote editors: editors a chain started in remote mode (SpawnOptions::remote) shows in a region of a display that the application reads, for someone who is not in front of the machine (macOS only). The application owns the display, reading the region, and sending what it reads.

Structs§

AudioBusConfig
Requested layout and activation for one native audio bus.
AudioBusInfo
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.
AudioConfiguration
A named native bus configuration, such as a CLAP audio-port configuration.
AudioInputRoute
An input bus request together with its source and explicit channel conversion.
AutomationEvent
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.
AutomationRamp
Linear in normalized value, inclusive endpoints. Expanded into exact sample points for one bounded block at a time. Native parameter metadata quantizes discrete parameters.
BarPosition
Caller-supplied start and numbering of the current musical bar.
BlockContext
Explicit block duration, independent of the presence of audio channels.
BundleScan
One discovered bundle and its outcome, provenance, and automatic exclusion status.
BypassState
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.
CapabilityReport
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.
Catalog
Ordered discovery results for native bundles and the Audio Unit registry.
Chain
Plugins processed in order, isolated in their own helper process. If a plugin crashes or hangs, the chain’s methods return Error::Crashed or Error::TimedOut (or Error::Cancelled after a Chain::canceller ended the hang), and the application decides whether to Chain::recover, or Chain::recover_realtime for a chain with a realtime endpoint.
ChainCanceller
Cancels the calls a chain is making on one helper generation, from any thread. Clones cancel the same generation; a recovered chain has its own canceller, and cancelling after the helper ended does nothing.
ChainSlot
One plugin of a chain to start, with what its fresh instance takes before the chain is returned. Build it with ChainSlot::new (or from a PluginRef) and the with_ methods.
ChainSnapshot
What recovery restores of a chain’s plugins, from Chain::snapshot, in chain order.
ChangeBatch
Timing notifications coalesce by slot, retaining last-observed order. Intermediate values are not an audit trail. On overflow use snapshot to 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 .vstpreset files 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.
Delivery
What a stream delivers at once: aligned output audio, and the output events processed since the previous delivery. Event offsets count from the start of the input, in the processing timeline; they are not shifted by the latency removed from the audio.
Diagnostic
One bounded diagnostic record with optional plugin and slot context.
DiagnosticBatch
Records drained since the last snapshot. Loss is explicit; this is not an audit log.
DiscoveredPreset
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 an Events, which holds the system exclusive bytes an event borrows.
EventConfig
The event ports a slot’s native preparation activates.
EventInputRoute
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.
EventPortInfo
A native event port. IDs are scoped to a direction; index is the native position that directly hosted plugins use as a Event::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.
EventsIter
The events of an Events, in order.
FactoryPreset
A named native factory preset or program.
Failure
A portable category with the original diagnostic message, including native codes when provided.
HelperMonitor
Observes one helper generation, even while the chain sends no requests. Clones share a sticky exit status; a recovered chain has a new monitor. Waiting belongs on an application/control thread.
HostIdentity
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.
LoopRegion
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.
NoteExpression
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.
ParameterChange
A normalized parameter value that takes effect at a sample offset within a block.
ParameterChoice
One discrete parameter choice and its native display conversion.
ParameterChoicePage
A bounded slice of a discrete parameter’s native choices.
ParameterDetails
A fresh query. Endpoints describe the normalized mapping, not a linear scale.
ParameterEventBatch
Overflow loses ordering continuity: cancel open gestures and requery metadata and values.
ParameterFlags
Native parameter properties. All flags default to false.
ParameterGroup
One native unit or group in a parameter’s root-to-leaf hierarchy.
ParameterInfo
Native parameter identity, labels, normalized default, and edit capabilities.
PluginId
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.
PluginInfo
A plugin class as its format describes it.
PluginRef
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.
PluginState
A plugin’s saved state with the identity of the class it belongs to. Its contents are opaque: store it with PluginState::to_bytes and read it back with PluginState::from_bytes, which later plughost versions keep reading. Where it is stored is up to the application.
PluginTiming
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.
PresetDirectory
One standard or caller-selected search root. The directory need not exist yet.
PresetDiscovery
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.
PresetDiscoveryTarget
One provider and location to inspect without loading an audio instance.
PresetFile
A candidate with the format’s file extension, not yet parsed or class-validated. Paths retain the caller’s root (relative roots produce relative paths).
PresetFileFailure
One preset file’s discovery failure, without failing the surrounding directory.
PresetFileType
File type advertised by a CLAP preset provider.
PresetFlags
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.
PresetInfo
Plugin identity and metadata read from a native preset container.
PresetLocationInfo
Named discovery location advertised by a CLAP provider.
PresetPluginId
Native plugin ABI and identity to which a discovered preset applies.
PresetProviderInfo
A CLAP module’s preset provider and its advertised discovery metadata.
PresetSoundpack
Native metadata for a provider’s soundpack.
RealtimeConfig
The shape of a realtime endpoint.
RealtimeEndpoint
The audio callback’s side of a chain’s realtime endpoint, from crate::Chain::realtime_endpoint. Move it to the callback’s thread and call process_audio_f32 or process_audio_f64 there, in the chain’s prepared precision, once per callback. Drop it on a control thread: dropping releases shared memory. crate::Chain::recover_realtime moves the endpoint to the chain it recovers in a new helper, while the callback keeps this value.
RealtimeFailure
The last quantum the helper reported failed.
RealtimeStatus
What a realtime endpoint did since it was created, read from the control thread.
RenderInput
Borrowed planar audio, events, and automation for a render or session segment.
RenderOptions
Offline tail policy and duration limit.
RenderProgress
Output-only report of work completed and audio delivered by a streaming render.
RenderSchedule
Borrowed render-relative transport and automation lanes. The default has no changes.
RenderSession
One continuous DSP render: push any number of input segments, then flush latency/tail once. Construction does not reset the processor. Use a fresh/reset processor for an independent render. After cancellation or a native failure, drop the session and reset before reuse.
Rendered
Owned output of a completed render, with audio aligned by removing native latency.
RoutedChainConfig
Explicit serial-chain configuration, validated before native preparation.
ScanControl
A shared stop handle for scanner operations. Cancellation is permanent for this handle; create a fresh one for a later independent scan. Clones control the same operation group.
ScanItem
One admitted item. Retain a clone to skip it from another thread. A late skip only affects this item, never a future item at the same path or a different item in the worker.
ScanPolicy
Explicit scan selection. The default allows all items; individual rules override it. Bundle paths must match the paths returned by discovery (no canonicalization is performed). Audio Unit IDs are compared case-insensitively. The last rule for an identity wins. This policy is not persisted in the native cache and does not restrict Chain loading.
Scanner
Configures metadata discovery, supervised native scans, caching, and selection policy. Each native bundle scan runs in a short-lived helper; discovery alone does not load it.
SlotAudioConfig
Audio and event routing for a single plugin slot.
SlotChange
Latest timing observation for one plugin in a chain.
SlotEventConfig
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.
SpawnOptions
How Chain::spawn starts a chain: the host identity it presents to plugins, which recovered chains keep, and its timeouts. Start from SpawnOptions::default and set the fields to change.
TimeSignature
Musical meter; numerator must be nonzero and denominator a power of two.
Timeouts
How long each kind of operation may go without a response from the helper. Start from Timeouts::default and change the fields that need other values. A duration too long to end at a representable instant, such as Duration::MAX, waits without a deadline.
Transport
A snapshot at the first sample of a block. None fields are unavailable, never synthesized. A seek is a discontinuity between consecutive snapshots. Loop wrapping is caller-owned.
TransportChange
Replaces the transport at this render-relative sample. None withdraws time information.

Enums§

AudioBusRole
Native distinction between a main bus and an additional bus.
AudioDirection
Direction of an audio or event port relative to its plugin.
AudioSource
Source of one slot’s input bus in a serial chain.
ChannelAdaptation
Explicit channel adaptation. Surround layouts are never inferred, reordered or downmixed.
DiagnosticSeverity
Severity reported by the plugin or host, including CLAP’s two misbehavior categories.
Error
Failures in helper supervision, native operations, input validation, or rendering. Use Error::kind for a stable category and std::error::Error::source for details.
EventData
What an event carries.
EventSource
Where a slot’s event input port takes events from.
ExpressionKind
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.
FactoryPresetId
Native factory program identity, scoped to one plugin class.
FailureKind
Format-independent error categories. These describe the failure, not an automatic retry policy.
Fallback
What the endpoint plays while the helper’s output is missing.
FallbackReason
Why a callback played the fallback.
InputError
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).
ParameterEvent
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.
PluginFormat
Native plugin ABI used for discovery and loading.
PluginKind
Broad native classification used in discovery results.
PresetLocation
Native CLAP provider location used both for discovery and preset loading.
PresetMetadata
Native file metadata, kept separate from a plugin’s opaque state.
PresetSearchError
Why a preset search root could not be searched.
ProcessMode
The processing mode reported to the plugin. Offline rendering is not paced to wall-clock time; Realtime only changes what the plugin is told, for plugins that misbehave in offline mode.
RealtimeOutput
What a callback played.
RenderError
Errors from the offline render rules.
RenderStatus
Whether rendering completed, stopped at a caller cancellation boundary, or ended a tail at its maximum.
SampleFormat
Floating-point precision of the prepared audio buffers.
ScanAction
Whether scanning may include a bundle or registered Audio Unit.
ScanEvent
Callbacks run on scanner workers and may overlap with explicit parallelism. They must return promptly for cancellation to proceed; dispatch UI work instead of blocking the scanner.
ScanOutcome
The result of scanning one bundle.
ScanStage
Last progress milestone for an admitted item. Progress renews the scan stall deadline.
ScanTarget
The bundle or registry currently being inspected.
SessionState
Lifecycle of a continuous render session.
Source
How a bundle result was obtained.
StatePurpose
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.
Tail
The tail length a processor reports.
TailPolicy
Rule for determining how much post-input audio to deliver.

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§

Process
A prepared processor the render rules can drive.
Sample
An audio sample type the plugin formats can process: f32 or f64. It is sealed: only this crate implements it, so a sample’s FORMAT always names its own type.

Functions§

default_directories
The standard VST3 and CLAP folders of the platform, highest priority first, and the folders in CLAP_PATH. Applications add their own plugin folders.
discover_preset_files
Recursively finds .vstpreset or .aupreset files, sorted by their complete path. Extension matching is ASCII case-insensitive; file contents are not read.
discover_presets
Queries metadata at one provider-declared location, preset/container file, or directory. A directory is crawled for the provider’s file types in one helper, and a file the provider refuses is listed in failed_files. A crash or timeout ends only this short-lived helper and fails the whole query; query the files of such a directory one by one to isolate the file.
preset_providers
Lists CLAP providers and declared preset locations. Provider code runs only in a scan helper.
render
Renders frames samples of input (one slice per input channel, none for an instrument) through the processor, with events placed by offset from the start of the input, in offset order and before frames.
render_stream
Delivers aligned output without retaining the whole result. Memory is bounded by the prepared block size plus the configured silence hold. Cancellation is checked before each submitted block; delivered samples remain valid. DSP state has advanced by processed_frames. Reset before a new independent render. This function does not reset the caller’s processor implicitly.
render_with_schedule
Renders a caller-defined timeline in bounded blocks, splitting at transport changes and the combined event budget. Ramps expand into exact sample points within each block. Native adapters preserve point semantics, subdividing internally when required by their format. Seeks change the transport only; call reset explicitly to discard DSP history.
standard_preset_directories
Standard roots in format/priority order. No filesystem scan or directory creation occurs.