Repository navigation
Plugin Lifecycle
Corrosion is a NIH-plug plugin. NIH-plug wraps one Rust struct, Corrosion in src/lib.rs, as a CLAP and a VST3 plugin; the host talks to the wrapper, and the wrapper calls a handful of trait methods. This page goes through those methods in the order a host uses them: construction, state restore (filter_state), initialize, reset, the process loop with its MIDI and CC handling, the editor's note path, and the export details.
sequenceDiagram
participant Host
participant W as NIH-plug wrapper
participant C as Corrosion
Host->>W: create instance
W->>C: Corrosion::default()
opt project or preset state restored
W->>C: filter_state(state)
W->>W: restore parameters and persisted fields
end
W->>C: initialize(layout, buffer config)
C-->>W: report latency
W->>C: reset()
loop every audio buffer
W->>C: process(buffer, context)
end
opt user opens the window
W->>C: editor()
end
In words:
- The wrapper builds the plugin with
Corrosion::default(). All memory the plugin will ever use on the audio thread is allocated here. - When the host restores a saved project, the wrapper first passes the raw state to
filter_state, which migrates old projects, then restores parameters by ID and the persisted fields (editor-state,kit). -
initializerates the voices for the host's sample rate, reports the latency of the restored Limiter Mode and rebuilds the kit's pad table. The code relies on NIH-plug callinginitializeagain after a later state restore (see Kit Mode). -
resetclears all sound state in place. Hosts may call it on the audio thread. -
processruns once per audio buffer. -
editorcreates the egui window when the user opens it (only with theguifeature).
| Item | Value | Notes |
|---|---|---|
NAME |
"Corrosion" |
|
VENDOR |
"Corrosion Contributors" |
plugin_vendor_is_corrosion_contributors pins it. |
URL, EMAIL
|
empty | |
VERSION |
env!("CARGO_PKG_VERSION") |
0.2.0 today, from Cargo.toml. |
AUDIO_IO_LAYOUTS |
one layout: no main input, 2 output channels, no aux ports | An instrument. |
MIDI_INPUT |
MidiConfig::MidiCCs |
Notes plus CCs, pitch bend, channel and poly pressure. |
SysExMessage, BackgroundTask
|
() |
No SysEx, no background tasks. |
The plugin doesn't override SAMPLE_ACCURATE_AUTOMATION, so NIH-plug doesn't split blocks at parameter changes: parameters are read once per block (see Parameters).
Corrosion::default() builds:
| Field | What it is |
|---|---|
params |
Arc<CorrosionParams>, shared with the editor and the wrapper. |
voice_manager |
VoiceManager::new(): 16 voices, each owning one resonator preallocated to its largest bank and an instance of all 16 exciters. |
post_chain |
PostProcessingChain::new(), with the Space buffers sized for 192 kHz (space::MAX_SAMPLE_RATE). |
drive_smoother, output_gain_smoother
|
OnePoleSmoothers (20 ms) starting at the Drive and Output values. |
lookahead_left, lookahead_right
|
Two LookaheadLimiters at LIMITER_THRESHOLD (0.9661). |
reported_latency_samples |
0, the last latency reported to the host. |
panic_gain, panic_step
|
1 and 0: no All Sound Off in progress. |
diode_meter |
Arc<DiodeMeter>: the clipper's reduction for the editor's limiter dot. |
editor_notes |
Arc<EditorNotes>: the editor keyboard's 256-slot note ring, allocated once. |
editor_note_state |
EditorNoteState: which notes the editor has on, as the audio thread sees it. |
mix_dc_blocker |
StereoDcBlocker at 10 Hz, rated for 48 kHz until initialize. |
mix_dc_blocker_enabled |
true; a test-only switch to bypass the blocker. |
Nothing here is resized later. That is the base of the real-time contract: process() and note-on never allocate (Real-Time Safety).
A DAW project stores the plugin's state as parameter values by ID plus persisted fields. When it reopens, NIH-plug restores that state directly, never through the preset loader, so the preset migrations in presets::migrate_preset_json don't run. Plugin::filter_state(state: &mut PluginState) is NIH-plug's hook to rewrite the state before it is applied. Corrosion runs four migrations, in this order:
| Function | Triggers when | Writes |
|---|---|---|
migrate_host_wander_rate |
no position_wander_rate, and position_envelope is present |
position_wander_rate = presets::legacy_wander_rate(position_envelope) (0.1 + envelope·4.9) and position_envelope = 0. Position Envelope used to set the wander's rate. |
migrate_host_onset_level |
no mseg_onset_level, and mseg_onset is present |
mseg_onset_level = presets::legacy_onset_level(mseg_onset). Onset Time used to set the level too. |
migrate_host_diode_stage |
the state has parameters but no diode_asymmetry
|
diode_softness = 0, diode_asymmetry = 0: a hard, symmetric knee, the closest to the old clipper. An empty state (nothing saved) is left to the defaults. |
migrate_host_old_kit_mode |
no persisted kit field, and play_mode is Kit (1) |
play_mode = Tonal (0). The old Kit mode mapped note ranges to objects; without pads, the project would be silent. |
Each migration is a no-op on state that already has its field, so it is safe to run on every restore. host_state_tests in src/lib.rs cover each one in both directions.
Trap: host automation recorded against an old meaning can't be migrated, because it never passes through filter_state. A change of meaning is BREAKING for automation, and must be called out as such. A new migration for a changed parameter needs both paths: migrate_preset_json for preset files (Presets and Migrations) and a migrate_host_* function here.
fn initialize(&mut self, _layout: &AudioIOLayout, buffer_config: &BufferConfig,
context: &mut impl InitContext<Self>) -> boolIt calls Corrosion::prepare(buffer_config.sample_rate) and reports the returned latency with context.set_latency_samples. It always returns true. prepare is the host-independent part, which the browser engine also calls:
-
Rate the voices.
VoiceManager::set_sample_raterates every voice, idle ones included, so a note-on builds its mode bank once, at the host rate, and its exciter starts at that rate. Without it the first note after a rate change would be built at the old rate and retuned. - Rate the voice-mix DC blocker.
-
Record the latency.
LOOKAHEAD_LIMITER_SAMPLES(48) if the restored Limiter Mode is Lookahead, else 0, stored inreported_latency_samples. It is reported here, before the host's delay compensation is settled, rather than left to the firstprocess()call;process()reports only later changes.lookahead_latency_is_reported_at_initializationchecks it. -
Rebuild the kit table.
params.kit_table.load(¶ms.kit)turns the restoredKitStateinto ready-to-play pads. This allocates, which is fine here:initializeruns off the audio thread, and the code comments that NIH-plug holds the plugin lock, soprocesscan't run at the same time.
The post chain isn't rated here; begin_block sets its rate at the start of every block.
NIH-plug calls reset() after initialize and whenever the host asks for a reset (the code's own comment says "when playback starts/stops"). Hosts may call it on the audio thread, so it must not allocate. It:
- resets every voice and the channel expression (
VoiceManager::reset: bend, pressure, mod wheel to 0, the sustain pedal up, the frame counter to 0); - clears the voice-mix DC blocker, the post chain and both lookahead limiters in place;
- rebuilds the two smoothers at their targets. The drive smoother starts at Drive plus the Violence bias, where
begin_blockaims it, so the first note after a reset isn't driven by a ramp from the unbiased value; - cancels any panic fade.
Because the frame counter restarts at 0 and each note's noise is seeded from its note, velocity and start frame, a render from a reset is deterministic. plugin_reset_with_sounding_space_is_alloc_free_and_silent checks the reset.
flowchart TD
start(["process(buffer, aux, context)"])
ev["first event, sample rate and tempo<br/>from the context"]
open["observe_editor_open<br/>gui feature only"]
pb["process_block<br/>write each frame to channels 0 and 1"]
meter["diode_meter.publish(reduction dB)"]
lat{"latency changed?"}
set["context.set_latency_samples"]
done(["ProcessStatus::Normal"])
start --> ev --> open --> pb --> meter --> lat
lat -->|yes| set --> done
lat -->|no| done
Step by step:
-
Read the context. The first queued event (
context.next_event()), the sample rate (transport().sample_rate, cast tou32) and the tempo (transport().tempo,Noneif the host gives none; it drives the echo's tempo sync). -
Watch the editor window (
guifeature only). NIH-plug keeps the editor state after the window closes, so the audio side detects a close itself:EditorNoteState::observe_editor_opencompareseditor_state.is_open()with last block's value and, on the open-to-closed edge, asks for a release of every note the editor started. -
Render.
process_block(block_len, rate, tempo, &mut next_event, fetch_next, write), the whole audio path (described on Signal Chain). Thewriteclosure stores each limited frame into output channel 0 (left) and 1 (right).process_blockreturns the block'sBlockSetup(rate, Width, limiter mode and threshold). -
Publish the diode meter.
post_chain.take_clipper_reduction_db()gives the largest reduction of the block in dB;DiodeMeter::publishkeeps the maximum since the editor last read it, in anAtomicU32(non-negative float bits order like the values, sofetch_maxworks). -
Report latency changes.
latency_change(limiter_mode)returnsSome(samples)only when the target latency differs fromreported_latency_samples; only then isset_latency_samplescalled, because hosts may renegotiate their buses on every call.mode_change_while_playing_is_reported_oncechecks this. -
Return
ProcessStatus::Normal. The plugin never asks to be suspended; idle voices already cost nothing.
process_block is generic over the event source and the output sink, so process(), the offline renderer (offline::PresetRenderer, 512-sample blocks) and the browser engine (WebEngine) share it:
-
begin_block(sample_rate, tempo): re-rate voices if the rate changed, set the DC blocker's rate, the drive and output-gain smoother targets, configure the limiters, push post-chain parameters (with macro biases and the tempo-synced echo time), and send live controls to held voices. -
handle_editor_notes(): drain the editor's note ring. - For each sample:
process_pending_eventshandles every event withtiming() <= samplethroughhandle_note_event, thenrender_frame_unlimitedandlimit_framemake the frame, andwrite(index, limited, unlimited)stores it. The unlimited frame (after output gain, before the limiter) lets level measurements count limiter hits. - After the loop,
editor_notes.publish_held(voice_manager.active_notes())publishes the held notes as a 128-bit mask for the editor's key highlights.
handle_note_event(plugin, event) is one match on NIH-plug's NoteEvent. Every arm is allocation-free.
| Event | Action |
|---|---|
NoteOn |
Velocity converted from NIH-plug's 0..1 to the voices' 0..127 scale (note_event_velocity_to_voice_velocity). In Kit mode: the key's pad from kit_table.get(note) plays, or nothing if the key has none (Kit Mode). In Tonal and Drone: note_setup snapshots the live parameters for the Object parameter's profile, and VoiceManager::note_on_addressed starts a voice that remembers the event's voice ID and channel. |
NoteOff |
note_off_addressed: the held voice with the event's voice ID, else the oldest held voice on that key and channel. A down sustain pedal holds it instead of releasing it. |
PolyTuning |
set_note_tuning: semitones added to the channel bend on the addressed voice(s). |
Choke |
choke: the addressed voice(s) fade out in 2 ms and are freed. |
PolyPressure |
set_poly_pressure_addressed: per-note pressure on the addressed voice. |
MidiPitchBend |
Normalized 0..1 (0.5 is centre) to (value − 0.5)·2·PITCH_BEND_RANGE_SEMITONES, ±2 semitones, on every sounding voice and stored for new notes. |
MidiChannelPressure |
Channel pressure on every sounding voice, stored for new notes. |
MidiCC 1 |
Mod wheel, stored and sent to every sounding voice. |
MidiCC 64 |
Sustain pedal: down when the normalized value is 0.5 or more (MIDI 64 and up). Lifting it releases every pedal-held note. |
MidiCC 123 |
All Notes Off: every held key is released as if lifted, so a down pedal still holds them (MIDI 1.0 behaviour). |
MidiCC 120 |
All Sound Off: start_panic, a 5 ms fade, then every voice, tail, the post chain and the limiters are cleared. Controllers keep their values. |
MidiCC 121 |
Reset All Controllers: pedal up, mod wheel, pitch bend and channel pressure to 0. |
| anything else | Ignored, including other CCs and the other CLAP note expressions (volume, pan, vibrato, brightness, expression). |
The voice-side details (addressing rules, stealing, the pedal and the panic) are on Voices and Polyphony and Note Expression. midi_control_tests in src/lib.rs covers the CCs, including controller_messages_are_alloc_free.
The editor's on-screen keyboard and computer keys play notes on the GUI thread; the voices live on the audio thread. src/gui_notes.rs connects them without locks on the audio side and without any GUI dependency, so the CI lane tests it.
flowchart LR
subgraph gui["GUI thread"]
strip["Keyboard strip,<br/>computer keys"]
sender["NoteSender<br/>holders per note,<br/>VecDeque backlog"]
strip --> sender
end
subgraph shared["Arc EditorNotes"]
ring["256-slot AtomicU32 ring<br/>head, tail"]
flag["release_all flag"]
mask["held mask<br/>2 × AtomicU64"]
end
subgraph audio["Audio thread"]
state["EditorNoteState<br/>notes the editor has on"]
handle["handle_note_event<br/>channel 0, no voice ID"]
state --> handle
end
sender -->|"try_push"| ring
sender -->|"on drop"| flag
ring -->|"drain each block"| state
flag --> state
handle -.->|"publish_held after the block"| mask
mask -.->|"key highlights"| strip
The same path as a list:
-
EditorNotes(shared through anArc): a ring ofQUEUE_CAPACITY= 256AtomicU32slots withheadandtailcounters, arelease_allflag and the held-note mask (twoAtomicU64, 128 bits).- Each event packs into one word: bit 16 set for a note-on, velocity (1–127) in bits 8–14, the note in bits 0–6.
-
try_push(GUI) takes a producer mutex, refuses whenhead − tail ≥ 256, stores the word and publishesheadwithRelease. The mutex only serialises producers (a host may briefly hold two editor instances); the audio thread never takes it. -
drain(audio) readsheadwithAcquire, hands each word to the handler oldest first, and advancestail.
-
NoteSender(GUI side) tracks why each note is held, as bits per note (NoteSource::Mouse,NoteSource::Key), so a note held by both the mouse and a key stops only when both let go. Events that don't fit in the ring wait in aVecDequebacklog and are retried on every press, release and frame, so none is lost. Computer keysA W S E D F T G Y H U J Kmap to notes fromkey_base(C4 = 60, or C2 = 36 in Kit mode); a key's release stops the note its press started even if the base moved. Dropping the sender (the window closing) releases what it holds and setsrelease_all. -
EditorNoteState(audio side, aCopyvalue insideCorrosion) mirrors which notes the editor turned on.drainupdates that mask for each event and passes the event on; ifrelease_allwas set, it then sends a note-off for every note in the mask and clears it. Host notes are not in the mask, so a release-all leaves them alone. -
handle_editor_notesturns each event into aNoteEventon channel 0 with no voice ID and timing 0, and callshandle_note_event. Editor notes therefore play at the block's first sample, afterbegin_blockand before the host's events of that block.
Trap: an editor note-off is a plain-MIDI note-off (key and channel 0), so it releases the oldest held voice on that key and channel. If a host note on channel 0 started earlier on the same key, that one is released first. editor_note_drain_is_alloc_free (in tests/no_alloc.rs) covers the drain's real-time safety; editor_keyboard_tests in src/lib.rs covers ordering and release-all.
Plugin::editor returns gui::create_editor(params, editor_state, diode_meter, editor_notes) with the gui feature, else None. The editor reads parameters through the Arc, writes them through NIH-plug's ParamSetter, writes the kit (params.kit and params.kit_table) directly, pushes notes into editor_notes, and takes the diode meter each frame. See Editor.
impl ClapPlugin for Corrosion { /* CLAP_ID "com.corrosion.corrosion", features Instrument, Synthesizer */ }
#[cfg(not(target_arch = "wasm32"))]
impl Vst3Plugin for Corrosion { /* VST3_CLASS_ID *b"CorrosionAudio01", subcategories Instrument, Synth */ }-
CLAP_IDis"com.corrosion.corrosion", with description "Industrial physical modeling synthesizer" and no manual or support URL. -
VST3_CLASS_IDis the 16 bytesb"CorrosionAudio01". Never change it, norCLAP_ID: hosts identify the plugin in saved projects by these IDs, and a new ID orphans every project that uses Corrosion. That holds even when other metadata, such asVENDOR, changes. -
nih_export_clap!(Corrosion)andnih_export_vst3!(Corrosion)produce the entry points, both under#[cfg(not(target_arch = "wasm32"))]: the browser build has no plugin host. - The VST3 export sits in a private module,
vst3_export, with#[allow(semicolon_in_expressions_from_non_local_macros)]. NIH-plug's VST3 macro trips that future-incompatibility lint on Rust 1.99+, and anallowon the macro call itself is ignored. The entry point is#[no_mangle], so the module path doesn't change the exported symbol.
How the library becomes .clap and .vst3 bundles is on Building and Bundling.
| Thread | Calls |
|---|---|
| Host main thread (through the wrapper) |
default, filter_state, initialize, editor, parameter changes from the host |
| Audio thread |
process, and reset when the host calls it there |
| Editor (GUI) thread | parameter changes through ParamSetter, KitTable::set and load, NoteSender pushes, DiodeMeter::take
|
The audio thread shares state with the others only through atomics (EditorNotes, DiodeMeter, the KitTable seqlock, NIH-plug's parameter atomics) and the RwLock<KitState> that only prepare reads, outside process.
-
src/lib.rs:Corrosion, thePlugin,ClapPluginandVst3Pluginimpls,filter_stateand themigrate_host_*functions,prepare,process_block,handle_note_event, the exports. -
src/gui_notes.rs:EditorNotes,NoteSender,EditorNoteStateand the key mapping. -
src/offline/preset.rs:PresetRenderer, the offline caller ofprocess_block. -
src/presets/mod.rs:legacy_wander_rateandlegacy_onset_level, shared by the preset and host migrations.
Corrosion Internals is generated from docs/internals/ in the repository. Edits made here are overwritten on the next publish: change the pages there, in a pull request.
Start
Plugin
Engine
- Modal resonator
- Objects
- Exciters
- Hit exciters
- Friction exciters
- Specialty exciters
- Interaction bus and contact
- Envelopes and modulation
- Material transformations
- DSP utilities
- Sample-rate rule
Post chain
State
Front ends
Quality
Process