Struct AudioHandle 

pub struct AudioHandle { /* private fields */ }

A running audio stream driving a Plugin.

Dropping the handle stops playback (the underlying device stream is released). While it lives, the plugin keeps running on the audio thread; use Self::lock to send MIDI or change parameters from your control thread.

Implementations

impl AudioHandle

pub fn lock(&self) -> MutexGuard<'_, Plugin>

Lock the running plugin to send MIDI, change parameters, etc.

Recovers automatically if the audio thread previously panicked while holding the lock (poisoned mutex), so control calls keep working.

pub fn try_lock(&self) -> Option<MutexGuard<'_, Plugin>>

Try to lock the plugin without blocking, returning None if the audio callback currently holds the lock (it is held for the duration of each process_audio call).

Use this on a UI/render thread for best-effort, per-frame reads (VU meters, output-MIDI drain, parameter sync): skipping a frame when the audio thread is mid-block is invisible, and it keeps the UI thread from stalling on the (unfair) mutex — which otherwise shows up as input lag.

pub fn send_midi(&self, event: MidiEvent) -> bool

Queue a MIDI event for the plugin without locking the audio thread.

The event is pushed onto a lock-free ring and applied at the start of the next audio block. Prefer this over lock().send_midi_event(..) on a UI thread — it never blocks on the audio mutex. Returns false if the ring is full (the event is dropped).

pub fn send_midi_at(&self, event: MidiEvent, sample_offset: i32) -> bool

Queue a MIDI event scheduled at sample_offset samples into the next block, for sample-accurate sequencing, without locking the audio thread. A negative offset is floored to 0. Returns false if the ring is full.

pub fn midi_sink(&self) -> MidiSink

Obtain a MidiSink: a cheap, cloneable, Send handle that can queue MIDI to this running plugin from another thread.

Unlike AudioHandle itself (which is not Send, as it owns the device stream), the sink can be moved into a background thread or callback — e.g. a MIDI input device callback (see crate::midi_input). It shares the same lock-free command ring as Self::send_midi.

pub fn set_parameter(&self, id: u32, value: f64) -> bool

Queue a normalized parameter change (0.0..=1.0) without locking the audio thread. Applied at the start of the next block. Returns false if the ring is full.

pub fn set_tempo(&self, bpm: f64) -> bool

Queue a transport tempo change (BPM) without locking the audio thread; applied at the start of the next block. bpm must be finite and greater than 0 (an invalid value is rejected, returning false). Returns false if the ring is full.

pub fn set_time_signature(&self, numerator: i32, denominator: i32) -> bool

Queue a transport time-signature change without locking the audio thread; applied at the start of the next block. denominator must be one of 1, 2, 4, 8, 16 and numerator must be positive (an invalid value is rejected, returning false). Returns false if the ring is full.

pub fn set_playing(&self, playing: bool) -> bool

Queue a transport playing-state toggle without locking the audio thread; applied at the start of the next block. Returns false if the ring is full.

pub fn midi_panic(&self) -> bool

Queue an all-notes-off “panic” (CC 123/120/121 on every channel) without locking the audio thread. Returns false if the ring is full.

pub fn output_levels(&self) -> AudioLevels

Read the latest per-channel output peak levels without locking the audio thread.

Each channel reports the maximum peak observed since the previous call (the read resets the accumulator), so polling at UI frame rate never misses a transient between frames. rms is not tracked on this path and is reported as 0; peak_hold mirrors peak (drive your own ballistics, e.g. crate::audio::PeakMeter, from the peak).

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

Drain MIDI the plugin emitted during processing (arpeggiators, MPE, …) without locking the audio thread. Returns the events queued since the last call.

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

Drain parameter changes the plugin made through its own editor without locking the audio thread. Returns (id, normalized_value) pairs queued since the last call.

pub fn plugin(&self) -> Arc<Mutex<Plugin>>

A shared handle to the plugin, e.g. to move into another thread.

pub fn stop(self)

Stop playback now (equivalent to dropping the handle).