plugindev

Plugin Development (nih-plug + egui)

Prime directive

If your project already has a working plugin codebase, grep it before designing any new subsystem:

rg -l <topic> src/

Copy existing idioms and adapt names. This saves re-deriving RT-safety, thread sync, and persistence patterns.

For deeper reference on any topic below, see references/patterns.md in this skill's directory.

Real-time safety (audio thread)

nih-plug's assert_process_allocs panics on any heap allocation during process(). Keep the feature on — it catches real bugs. Wrap known false positives:

use nih_plug::util::permit_alloc;

// parking_lot mutex drop (unlock_slow may allocate)
permit_alloc(|| drop(shared));

// Arc clone/drop
permit_alloc(|| { voice.sample = Some(Arc::clone(sample)); });
permit_alloc(|| { self.data = None; });  // Arc::drop

// thread spawn, channel bounded, HashSet insert — all need permit_alloc

Rule of thumb: any op touching an allocator (Arc refcount, Vec growth, HashMap, spawn, formatted tracing) must be wrapped. Plain scalar/atomic ops are free.

Audio <-> GUI sync (three layers)

1. Hot state -> atomics. Wrap in Arc<SyncStruct> shared with GUI. Use AtomicUsize/AtomicBool/AtomicU8 for step pos, playing, trigger counts, tempo (BPM*10 as u32). Lock-free both directions.

2. Bulk state -> Arc<parking_lot::Mutex<SharedState>>. Audio thread uses try_lock(), never lock(). If contended, skip MIDI/sequencer for this buffer — a few ms gap is inaudible vs blocking the RT thread. Always permit_alloc(|| drop(guard)).

3. GUI render -> DisplaySnapshot. Per frame: brief lock, copy metadata + waveforms into a plain struct, drop the lock, render from snapshot. No lock held during egui layout.

Handoff of large results (scanned library, loaded preset) -> crossbeam-channel::bounded(1), try_recv() in process().

DAW persistence

#[persist = "plugin-state"]
pub plugin_state: Arc<parking_lot::Mutex<String>>,  // JSON blob