Struct Plugin 

pub struct Plugin { /* private fields */ }

VST3 plugin instance

Implementations

impl Plugin

pub fn info(&self) -> &PluginInfo

Get plugin information

pub fn sample_rate(&self) -> f64

The sample rate (Hz) this plugin was configured with at load.

pub fn block_size(&self) -> usize

The maximum block size (frames per process_audio call) configured at load.

pub fn reconfigure(&mut self, sample_rate: f64, block_size: usize) -> Result<()>

Reconfigure the plugin for a new sample rate and/or maximum block size, re-running the plugin’s setupProcessing and rebuilding its audio buffers.

Use this when the audio device’s sample rate changes mid-session instead of reloading. The plugin must not be processing: call Self::stop_processing first, reconfigure, then Self::start_processing again. Returns an error if called while processing, on an invalid sample rate / zero block size, or under process isolation (not yet marshalled).

pub fn set_process_mode(&mut self, mode: ProcessMode) -> Result<()>

Switch the plugin between real-time and offline processing, re-running the plugin’s setupProcessing so it can adjust quality / look-ahead for a faster-than-real-time bounce.

Like Self::reconfigure, the plugin must not be processing: call Self::stop_processing first. Returns an error if called while processing, or under process isolation (not marshalled across the boundary).

pub fn bus_arrangements(&self) -> Result<BusArrangements>

Query the current speaker arrangement of each audio input/output bus.

pub fn set_bus_arrangements( &mut self, inputs: &[SpeakerArrangement], outputs: &[SpeakerArrangement], ) -> Result<()>

Request specific speaker arrangements for the audio buses (e.g. force stereo, or a surround layout). The slices give one SpeakerArrangement per input bus and per output bus, in bus-index order.

Re-runs the plugin’s setupProcessing, so the plugin must not be processing (call Self::stop_processing first). A plugin may decline a requested layout and keep its own; re-query with Self::bus_arrangements to see what was actually applied. Errors while processing or under process isolation (not marshalled).

pub fn get_parameters(&self) -> Result<Vec<Parameter>>

Get all parameters

pub fn set_parameter(&mut self, id: u32, value: f64) -> Result<()>

Set a parameter value by ID

pub fn set_parameter_at( &mut self, id: u32, value: f64, sample_offset: i32, ) -> Result<()>

Set a parameter value at a specific sample offset within the next process block.

This is the sample-accurate building block for automation: call it once per sub-block point (e.g. from ParameterAutomation::points_for_block) and the plugin receives the changes at their offsets in the next process_audio. Like Self::set_parameter, value is normalized 0.0..=1.0.

sample_offset is clamped to the block. Under process isolation the offset is now carried across the boundary and applied by the helper’s in-process plugin.

pub fn get_units(&self) -> Result<Vec<PluginUnit>>

Enumerate the plugin’s units and their program lists (IUnitInfo).

Returns an empty list for plugins that don’t implement IUnitInfo, and (for now) for plugins running under process isolation. The root unit (id 0) is typically present.

pub fn latency_samples(&self) -> u32

The plugin’s reported processing latency in samples (e.g. from look-ahead or oversampling), via IAudioProcessor::getLatencySamples. Use it to delay-compensate when aligning the plugin’s output with other signals. 0 if it reports none, or for plugins running under process isolation (not bridged).

pub fn tail_samples(&self) -> u32

The plugin’s reported tail length in samples (how long it keeps producing output after input stops — e.g. reverb/delay), via IAudioProcessor::getTailSamples. 0 means no tail; u32::MAX means an infinite tail. 0 for isolated plugins (not bridged).

pub fn midi_cc_to_parameter( &self, bus: i32, channel: i16, cc: u16, ) -> Option<u32>

Resolve a MIDI controller to the parameter it’s mapped to, via the plugin’s IMidiMapping (getMidiControllerAssignment).

bus is the event input bus index (usually 0), channel the 0-based MIDI channel, and cc the MIDI controller number (0–127, or the VST3 specials such as 128 aftertouch / 129 pitch-bend). Returns the parameter id the controller drives, or None if the plugin doesn’t implement IMidiMapping, the controller is unmapped, or the plugin is process-isolated (not bridged).

pub fn get_parameter(&self, id: u32) -> Result<f64>

Get a parameter value by ID

pub fn format_parameter(&self, id: u32, normalized: f64) -> Result<String>

Format a parameter value as the plugin itself would display it.

VST3 keeps all parameter values normalized (0.0–1.0) and delegates human-readable formatting to the plugin’s controller. This asks the plugin to render normalized for parameter id, returning exactly what its own UI would show — e.g. "440.00 Hz", "-6.0 dB", "Sine". Prefer this over Parameter::format_value, which can only approximate without the plugin’s internal mapping.

pub fn set_parameter_by_name(&mut self, name: &str, value: f64) -> Result<()>

Set a parameter by name

pub fn find_parameter(&self, name: &str) -> Result<Parameter>

Find a parameter by name

pub fn send_midi_note( &mut self, note: u8, velocity: u8, channel: MidiChannel, ) -> Result<()>

Send a MIDI note on event

pub fn send_midi_note_off( &mut self, note: u8, channel: MidiChannel, ) -> Result<()>

Send a MIDI note off event

pub fn send_midi_cc( &mut self, controller: u8, value: u8, channel: MidiChannel, ) -> Result<()>

Send a MIDI control change event

pub fn send_midi_event(&mut self, event: MidiEvent) -> Result<()>

Send a generic MIDI event

pub fn send_midi_event_at( &mut self, event: MidiEvent, sample_offset: i32, ) -> Result<()>

Schedule a MIDI event at a sample offset within the next process_audio block.

Use this for sample-accurate sequencing: an event sent with sample_offset = N takes effect N frames into the next processed block, rather than at its start. Keep the offset within the upcoming block’s frame count (Plugin::block_size is the maximum); a negative offset is treated as 0, and an offset past the block end is plugin-defined.

Under process isolation the offset is not marshalled across the boundary — the event is delivered at block start (offset 0), same as Self::send_midi_event.

pub fn start_processing(&mut self) -> Result<()>

Start audio processing

pub fn stop_processing(&mut self) -> Result<()>

Stop audio processing

pub fn process_audio(&mut self, buffers: &mut AudioBuffers) -> Result<()>

Process audio buffers

pub fn get_output_levels(&self) -> AudioLevels

Get current output levels.

Recovers automatically if the audio thread panicked while holding the lock (poisoned mutex) rather than propagating the panic to the caller — metering must never take down a UI thread polling it.

pub fn is_processing(&self) -> bool

Check if the plugin is currently processing

pub fn on_parameter_change<F>(&mut self, callback: F)

where F: Fn(u32, f64) + Send + 'static,

Set a callback for parameter changes

pub fn on_audio_process<F>(&mut self, callback: F)

where F: Fn(&AudioLevels) + Send + 'static,

Set a callback for audio processing (called after each process cycle)

pub fn has_editor(&self) -> bool

Check if the plugin has an editor GUI

pub fn open_editor(&mut self, parent: WindowHandle) -> Result<()>

Open the plugin editor window

pub fn close_editor(&mut self) -> Result<()>

Close the plugin editor window

pub fn get_editor_size(&self) -> Result<(i32, i32)>

Get the preferred editor size

pub fn update_parameters<F>(&mut self, f: F) -> Result<()>

where F: FnOnce(&mut ParameterUpdate<'_>) -> Result<()>,

Create a batch parameter update

pub fn midi_panic(&mut self) -> Result<()>

Send MIDI panic (all notes off, all sounds off, reset controllers)

pub fn get_parameter_changes(&self) -> Vec<(u32, f64)>

Get parameter changes from plugin GUI Returns a vector of (parameter_id, normalized_value) pairs This should be called regularly to pick up parameter changes made through the plugin’s GUI

pub fn take_output_midi(&self) -> Vec<MidiEvent>

Take the MIDI events the plugin has emitted (e.g. from an arpeggiator or MPE controller) since the last call, draining the internal buffer.

Output MIDI is captured while the plugin processes audio, so poll this regularly (e.g. each UI frame) while the plugin is playing. Returns an empty vector if the plugin emits nothing, or for plugins running under process isolation (output MIDI across the boundary is not captured yet).

pub fn save_state(&self) -> Result<Vec<u8>>

Save the plugin’s current state (parameters, internal settings, loaded preset) to an opaque byte blob.

The bytes are the plugin’s own serialized state — treat them as opaque and pair them with the plugin’s identity (PluginInfo::uid); they only mean something to the same plugin. Persist them to restore a patch later with Self::load_state, or to snapshot a session. Call this on the main thread (see the threading model).

Works both in-process and across process isolation (the state blob is marshalled over the IPC boundary). Returns an error for plugins that don’t implement state saving.

pub fn load_state(&mut self, data: &[u8]) -> Result<()>

Restore plugin state from a blob produced by Self::save_state on the same plugin. Applies to both the processor and the controller, so parameter values and the editor reflect the restored state.

Passing bytes from a different plugin has undefined results (the plugin decides what to do with bytes it doesn’t recognize). Call this on the main thread.

pub fn save_preset<P: AsRef<Path>>(&self, path: P) -> Result<()>

Save this plugin’s state to a file as a PluginPreset (JSON: the plugin’s uid and name plus the opaque state blob). The embedded uid lets Self::load_preset reject a preset saved from a different plugin.

pub fn load_preset<P: AsRef<Path>>(&mut self, path: P) -> Result<()>

Load a PluginPreset file written by Self::save_preset and apply its state. Returns an error if the preset’s uid doesn’t match this plugin (loading another plugin’s state is undefined).

pub fn save_vstpreset<P: AsRef<Path>>(&self, path: P) -> Result<()>

Save this plugin’s state to a standard Steinberg .vstpreset file.

Unlike Self::save_preset (a JSON wrapper specific to this library), the .vstpreset container is the interchange format shared by VST3 hosts and plugins, so the file can be read by other hosts (and by the plugin’s own preset browser). It wraps the same opaque bytes from Self::save_state in a single "Comp" (component state) chunk, tagged with this plugin’s class id (PluginInfo::uid) so a loader can reject presets from a different plugin. Call this on the main thread.

pub fn load_vstpreset<P: AsRef<Path>>(&mut self, path: P) -> Result<()>

Load a Steinberg .vstpreset file and apply its component state to this plugin.

Parses the .vstpreset container written by Self::save_vstpreset (or another VST3 host), extracts the "Comp" (component state) chunk and passes it to Self::load_state. Returns an error if the file’s magic is invalid, or if its class id doesn’t match this plugin (loading another plugin’s state is undefined). Call this on the main thread.

pub fn isolation_pid(&self) -> Option<u32>

The OS process id of the isolated helper hosting this plugin, or None if it runs in-process. Useful for monitoring an isolated plugin’s resource use.

pub fn recovery_count(&self) -> u64

How many times this plugin has been recovered (helper respawned + reloaded), via either Self::recover or automatic recovery (Vst3HostBuilder::auto_recover_plugins).

A recovery reloads the plugin from defaults — parameter values and loaded state are NOT replayed. With auto-recover on, a crash is otherwise invisible (the call returns Ok), so poll this count to detect that a reset happened and re-apply a saved save_state snapshot.

pub fn output_channel_count(&self) -> usize

Total number of output audio channels across the plugin’s output buses.

Reflects the plugin’s actual bus layout (mono / stereo / surround / multi-bus), not a stereo assumption — useful for sizing meters or output buffers. Returns 2 if unknown.

pub fn take_editor_resize_request(&self) -> Option<(i32, i32)>

Poll for an editor resize the plugin requested via VST3’s IPlugFrame since the last call, as (width, height) in pixels, or None.

Plugins with resizable editors call back to ask the host to resize the window hosting their view. Poll this on your UI thread (e.g. each frame) while the editor is open and resize your editor container to match. Only the in-process editor path reports this.

pub fn recover(&mut self) -> Result<()>

Recover a process-isolated plugin whose helper has crashed.

When an isolated plugin’s helper process dies, calls return Error::PluginCrashed and the host itself stays alive. This respawns the helper and reloads the plugin from the same path and audio settings, restarting processing if it was running.

The reloaded plugin starts from its default state — parameter values and any loaded preset are lost. Snapshot with Self::save_state beforehand and Self::load_state after recovering to preserve them. Returns an error for in-process plugins (an in-process crash takes down the whole host) and if the reload itself fails.