Repository navigation
Voices and Polyphony
A voice is one sounding note: an exciter, a modal resonator and a force envelope. Corrosion has a fixed pool of 16 voices, owned by VoiceManager in src/voice/manager.rs; each Voice (src/voice/mod.rs) owns everything it can ever need, so starting, stealing and ending a note never allocates. This page covers a voice's life (note-on, release, tail, end), how a slot is chosen and stolen, the sustain pedal, the panic paths, and where the voice mix goes.
A voice has two flags: active (the key is held, or the pedal holds it) and rendering (it still makes sound). A third, pedal_held, marks a key that is up while the sustain pedal keeps the note.
stateDiagram-v2
[*] --> Idle
Idle --> Held: note-on
Held --> PedalHeld: key-up, pedal down
PedalHeld --> Tail: pedal up
Held --> Tail: key-up, pedal up
Tail --> Idle: peak under 1e-4 for 100 ms
Held --> Idle: choke fade ends, or panic, or reset
Tail --> Idle: choke fade ends, or panic, or reset
PedalHeld --> Idle: panic or reset
Tail --> Held: stolen by a new note-on
Held --> Held: stolen by a new note-on
| State | active |
pedal_held |
rendering |
Meaning |
|---|---|---|---|---|
| Idle | false | false | false | Costs nothing; skipped by the manager. |
| Held | true | false | true | Key down. Gets live control updates every block. |
| Pedal-held | true | true | true | Key up, sustain pedal down. Still counts as held. |
| Tail | false | false | true | Released; the exciter's envelope releases and the resonator rings out. |
The transitions:
- Idle → Held on note-on.
- Held → Pedal-held on a key-up while the pedal is down; Held → Tail on a key-up with the pedal up.
- Pedal-held → Tail when the pedal lifts.
- Tail → Idle when the peak stays under 1e-4 for 100 ms.
- Any sounding state → Idle at the end of a choke fade, a panic or a reset.
- Any state goes to Held when its slot is taken for a new note:
note_on_with_controlsresets everything that note needs.
handle_note_event (src/lib.rs) builds a NoteSetup from the parameters (note_setup: profile, macro-biased size, rust and damage, exciter ID, and a VoiceControls snapshot of every per-note parameter) and calls VoiceManager::note_on_addressed. Kit pads call note_on_pad instead (Kit Mode). Both go through start_voice:
- Re-strike under the pedal. Any pedal-held voice on the same key is released first, so repeated notes under the pedal don't pile up.
-
Pick a slot. The first voice with
!is_rendering(); if none,steal_index()(below). -
Channel expression.
apply_channel_expression_togives the slot the current channel pressure, mod wheel and pitch bend, so a note started during a bend starts bent. -
Voice::note_on_with_controls:- sets
activeandrendering, clearspedal_held, the pad flag and gain, and stores note, velocity and the exciter ID (normalized throughExciterType::from_int, so a bad ID plays Hand Strike); - resets peak hold, governor, the tail counter, poly pressure, per-note tuning, voice ID, choke;
- starts Pressure at its target, unsmoothed;
- reseeds every noise source from
note_seed(note, velocity, start_frame), one salted stream per consumer, so a note is deterministic given the frame it starts on; - rebuilds the resonator in place (
ModalResonator::rebuild_in_place) for the profile, size, material transforms, pitch (midi_to_hz), damping, brightness, character and mode-count scale, at the voice's rate. This is the expensive part of a note-on; it reuses buffers preallocated to the largest bank; - sets the interaction parameters (strike position, coupling, wander, anchor) and the Position Envelope amount;
- applies the pitch (channel bend plus tuning);
- configures the force envelope for the exciter's family;
- applies the global Speed and Roughness to a copy of the controls, then sets the parameters of and triggers the one exciter selected (a
matchon 1..16).
- sets
-
Address.
set_address(voice_id, channel)records how the host addressed the note (Note Expression).
start_frame is the manager's frame_counter, which counts samples processed since the last reset.
-
note_offclearsactiveandpedal_heldand releases the force envelope: the Hit one-shot goes to its release ramp, the ADSR to Release, the MSEG to its release stage. The exciters keep running until their envelope reaches 0, so Release and MSEG Release shape the tail. Friction exciters that held a static deflection let go at once; the object rings out from it (up to about +30 dB over the held note on the default patch, a known behaviour). -
Tail. The resonator decays at its own rate. Each sample
peak_holdtakes the larger clamped output and decays byPEAK_DECAY= 0.999 per sample (at 48 kHz). -
End. While
!activeandpeak_hold < TAIL_ENERGY_THRESHOLD(1e-4, −80 dBFS), a counter runs; afterTAIL_DEACTIVATE_FRAMES(4800 at 48 kHz, 100 ms, converted withrate::frames) the voice setsrendering = false. Any louder sample resets the counter. -
resetreturns a voice to idle in place: flags, resonator state, envelopes, expression, address. It doesn't touch the resonator's bank; the next note-on rebuilds it.
When all 16 voices are rendering, steal_index ranks them in four tiers, lowest stolen first:
flowchart TD
a["Every slot is rendering"] --> t0{"any released tail?"}
t0 -->|yes| s0["steal the quietest tail"]
t0 -->|no| t1{"any pedal-held note?"}
t1 -->|yes| s1["steal the quietest pedal-held note"]
t1 -->|no| t2{"any held key at least 100 ms old?"}
t2 -->|yes| s2["steal the quietest of those"]
t2 -->|no| s3["steal the oldest held key"]
| Tier | Voices | Order within the tier |
|---|---|---|
| 0 | released tails (!is_active()) |
quietest peak_hold, oldest on a tie |
| 1 | pedal-held notes | quietest, oldest on a tie |
| 2 | held keys at least STEAL_PROTECTION_SECONDS (0.1 s) old |
quietest, oldest on a tie |
| 3 | younger held keys | oldest |
- "Quietest" uses
comparable_peak_hold, which maps a non-finitepeak_holdto −∞, so a voice that went NaN is reclaimed first and the comparison never panics. - Tier 3 ignores level on purpose: a note that started a few milliseconds ago (a slow bow attack) hasn't reached its peak, so its level says nothing about how audible it will be. 100 ms covers a slow friction attack with margin.
- The protection window is
0.1 × sample_rateframes, so it is 100 ms at any rate (protection_window_is_one_hundred_milliseconds_at_any_rate). - A stolen voice is not faded: the new note's
note_on_with_controlsoverwrites it, and its resonator state starts from the rebuilt bank.
VoiceManager::sustain_down holds the pedal state (CC64, down at 64 or more).
- A key-up goes through
release_key: with the pedal down the voice is markedpedal_held(it staysactiveand still gets live controls); otherwise it is released. - Lifting the pedal (
set_sustain(false)) releases every pedal-held voice. Keys still physically down keep sounding, because they were never marked. - CC123 All Notes Off (
all_notes_off) releases every held key throughrelease_key, so a down pedal still holds them, as MIDI 1.0 specifies. - CC121 Reset All Controllers lifts the pedal (releasing pedal-held notes) and zeroes mod wheel, bend and channel pressure.
- A note-off never matches a pedal-held voice (it already had its key-up).
| Path | Trigger | What happens |
|---|---|---|
| All Sound Off | CC120 |
Corrosion::start_panic fades the plugin's output linearly over 5 ms (PANIC_FADE_SECONDS, computed from the voices' rate). At the end, VoiceManager::silence resets every voice and the frame counter, and the DC blocker, post chain and lookahead limiters are cleared in place. Pedal, mod wheel, bend and pressure keep their values: the message mutes sound, it doesn't move controllers. |
| Host reset | Plugin::reset |
VoiceManager::reset: every voice reset, the frame counter to 0, and the channel state (bend, pressure, mod wheel, pedal) cleared. |
| Choke | host Choke event |
One voice (or every voice on a key) fades over 2 ms and resets (Note Expression). |
The panic fade is on the output, not per voice, so it also fades reverb and echo tails. A note-on during the 5 ms fade starts a voice, but the end of the fade clears it too.
Every sample, VoiceManager::process_sample_stereo(rate, width) advances frame_counter, records the rate, and adds the stereo output of every rendering voice. Nothing divides the sum by the voice count, so one note is as loud alone as in a chord (single_voice_is_not_downmixed_by_empty_slots). The sum goes to the voice-mix DC blocker, then the master drive and the post chain (Signal Chain).
Other manager services:
-
set_sample_raterates every voice, idle ones included, so a note's bank is built at the host rate.Voice::set_rateis a cheap comparison when nothing changed. -
update_live_controlssends the per-block live controls to held, non-pad voices. -
active_notes(held notes, published for the editor's key highlights) andsounding_notes(held or tailing) iterate without allocating.
Each Voice contains one instance of all 16 exciters plus a ModalResonator preallocated to MAX_MODES. Dispatch is a match on the exciter ID, with no trait objects and no allocation. The cost is memory (16 × 16 exciter structs); the gain is a note-on path that only rebuilds data in place. tests/no_alloc.rs checks note-on, stealing, release, live controls and MIDI expression; see Real-Time Safety.
-
src/voice/mod.rs:Voice,VoiceControls, note-on,note_off,reset, tail tracking, the constantsTAIL_ENERGY_THRESHOLD,TAIL_DEACTIVATE_FRAMES,PEAK_DECAY. -
src/voice/manager.rs:VoiceManager,start_voice,steal_index, the pedal,silence,resetand the voice mix. -
src/lib.rs:note_setup,handle_note_event, the CC routing and the panic fade.
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