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§
- 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
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.
- Automation
Ramp - 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.
- Block
Context - Explicit block duration, independent of the presence of audio channels.
- Bundle
Scan - One discovered bundle and its outcome, provenance, and automatic exclusion status.
- 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.
- 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::CrashedorError::TimedOut(orError::Cancelledafter aChain::cancellerended the hang), and the application decides whether toChain::recover, orChain::recover_realtimefor a chain with a realtime endpoint. - Chain
Canceller - 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.
- Chain
Slot - 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 aPluginRef) and thewith_methods. - Chain
Snapshot - What recovery restores of a chain’s plugins, from
Chain::snapshot, in chain order. - 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. - 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.
- 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.
- Helper
Monitor - 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.
- 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
Directory - One standard or caller-selected search root. The directory need not exist yet.
- 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 - 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).
- 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.
- Realtime
Config - The shape of a realtime endpoint.
- Realtime
Endpoint - The audio callback’s side of a chain’s realtime endpoint, from
crate::Chain::realtime_endpoint. Move it to the callback’s thread and callprocess_audio_f32orprocess_audio_f64there, in the chain’s prepared precision, once per callback. Drop it on a control thread: dropping releases shared memory.crate::Chain::recover_realtimemoves the endpoint to the chain it recovers in a new helper, while the callback keeps this value. - Realtime
Failure - The last quantum the helper reported failed.
- Realtime
Status - What a realtime endpoint did since it was created, read from the control thread.
- Render
Input - Borrowed planar audio, events, and automation for a render or session segment.
- Render
Options - Offline tail policy and duration limit.
- Render
Progress - Output-only report of work completed and audio delivered by a streaming render.
- Render
Schedule - Borrowed render-relative transport and automation lanes. The default has no changes.
- Render
Session - 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.
- Routed
Chain Config - Explicit serial-chain configuration, validated before native preparation.
- Scan
Control - 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.
- Scan
Item - 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.
- Scan
Policy - 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.
- 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.
- Spawn
Options - How
Chain::spawnstarts a chain: the host identity it presents to plugins, which recovered chains keep, and its timeouts. Start fromSpawnOptions::defaultand set the fields to change. - Time
Signature - 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::defaultand change the fields that need other values. A duration too long to end at a representable instant, such asDuration::MAX, waits without a deadline. - 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. - Transport
Change - Replaces the transport at this render-relative sample.
Nonewithdraws time information.
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.
- Error
- Failures in helper supervision, native operations, input validation, or rendering.
Use
Error::kindfor a stable category andstd::error::Error::sourcefor details. - 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.
- Fallback
- What the endpoint plays while the helper’s output is missing.
- Fallback
Reason - Why a callback played the fallback.
- 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.
- Preset
Search Error - Why a preset search root could not be searched.
- 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. - Realtime
Output - What a callback played.
- Render
Error - Errors from the offline render rules.
- Render
Status - Whether rendering completed, stopped at a caller cancellation boundary, or ended a tail at its maximum.
- Sample
Format - Floating-point precision of the prepared audio buffers.
- Scan
Action - Whether scanning may include a bundle or registered Audio Unit.
- Scan
Event - 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.
- Scan
Outcome - The result of scanning one bundle.
- Scan
Stage - Last progress milestone for an admitted item. Progress renews the scan stall deadline.
- Scan
Target - The bundle or registry currently being inspected.
- Session
State - Lifecycle of a continuous render session.
- Source
- How a bundle result was obtained.
- 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.
- Tail
- The tail length a processor reports.
- Tail
Policy - 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:
f32orf64. It is sealed: only this crate implements it, so a sample’sFORMATalways 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
.vstpresetor.aupresetfiles, 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
framessamples ofinput(one slice per input channel, none for an instrument) through the processor, witheventsplaced by offset from the start of the input, in offset order and beforeframes. - 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.