Repository navigation
Signal Chain
This page follows one sample from a MIDI note to the plugin's output. It names every stage in order, says what each does and why it sits where it does, and then opens up the per-voice loop that runs inside the first stage. Each stage has its own page with the details; this one is the map.
The whole audio path is per sample. The exciter and the resonator push on each other every sample (a two-way interaction, see Interaction Bus and Contact), so the voice can't be processed in blocks, and the post chain runs per sample too for simplicity. Parameters, by contrast, are read once per host block; stages that need smooth changes glide between block values at audio rate.
flowchart TD
midi(["MIDI notes and CCs<br/>host events + editor keyboard"])
vm["VoiceManager<br/>16 voices"]
subgraph voice["Each sounding voice: Voice::process_sample_stereo"]
env["Force envelope<br/>AR, ADSR or MSEG"]
exc["Exciter<br/>1 of 16 models"]
res["ModalResonator<br/>1 of 9 objects"]
shape["Rattle, velocity high-pass boost,<br/>clamp to ±1, expression and pad gain"]
env --> exc
exc -->|"force"| res
res -->|"displacement, velocity"| exc
res --> shape
end
sum["Sum of voices"]
dc["Voice-mix DC blocker<br/>10 Hz, 2nd order"]
drive["Master drive<br/>apply_drive"]
subgraph post["PostProcessingChain::process"]
filt["Ladder filter, per channel"]
lor["Lorenz drive, per channel"]
body["FEM body on the mono sum,<br/>added to both channels"]
spread["HRTF spread"]
space["Space: Off, Factory, Spring, Echo"]
clip["Oversampled diode clipper"]
filt --> lor --> body --> spread --> space --> clip
end
gain["Output gain"]
panic["All Sound Off fade<br/>only while a panic runs"]
lim["Limiter: Hard clamp or Lookahead<br/>at the Analog Ceiling"]
out(["Stereo output"])
midi --> vm --> env
shape --> sum --> dc --> drive --> filt
clip --> gain --> panic --> lim --> out
The same chain, as a list:
-
MIDI in. Host note events and CCs, plus notes from the editor's on-screen keyboard, go to
handle_note_eventinsrc/lib.rs, which starts, releases or modulates voices in theVoiceManager. - Voices. Each of the 16 voices that is sounding runs its own loop: force envelope → exciter ⇄ resonator → damage rattle → velocity high-pass boost → clamp to ±1 → expression gain and kit-pad gain. Details below.
-
Sum.
VoiceManager::process_sample_stereoadds the voices. The sum is not normalized. -
Voice-mix DC blocker.
dsp::StereoDcBlocker, a 10 Hz second-order Butterworth high-pass per channel. -
Master drive.
apply_drive, the Drive knob (plus the Violence macro), smoothed per sample. -
Post chain.
PostProcessingChain::process: ladder filter and Lorenz drive per channel, the FEM body on the mono sum added to both channels, HRTF spread, Space, then the oversampled diode clipper. - Output gain. The Output parameter, smoothed per sample.
- Panic fade. Only while an All Sound Off (CC120) is running.
- Limiter. A hard clamp to ±Analog Ceiling, or the Lookahead limiter with the same ceiling.
The host calls Plugin::process once per buffer. Everything below the host API is one function, Corrosion::process_block, which the offline renderer (offline::PresetRenderer, in 512-sample blocks) and the browser engine also call. So tests, preset renders and the web app hear exactly what the plugin outputs.
sequenceDiagram
participant Host
participant P as process()
participant B as process_block()
participant V as VoiceManager
Host->>P: buffer and events
P->>B: block length, rate, tempo
B->>B: begin_block (read parameters once)
B->>V: editor keyboard notes (handle_editor_notes)
loop every sample
B->>V: host events due at this sample
B->>B: render_frame_unlimited
B->>B: limit_frame
end
B->>B: publish held notes for the editor
P->>Host: diode meter, latency change if any
As steps:
-
begin_blockreads every parameter once: it re-rates the voices if the host rate changed, sets the smoother targets for drive and output gain, configures both limiters, pushes the post-chain parameters (with macro biases) and sends the live controls to held voices. These setters recompute coefficients (filtertan, body frequencies, reverb delays) that must not run per sample. -
handle_editor_notesplays what the editor keyboard queued, as channel-0 notes at the block's first sample, before the host's events. - Per sample:
process_pending_eventshandles every host event whose timing is at or before this sample (sample-accurate notes), thenrender_frame_unlimitedmakes one frame (steps 2 to 8 of the chain) andlimit_frameapplies the limiter. - After the block, the held notes are published for the editor's key highlights;
process()then publishes the diode meter and reports a latency change if the Limiter Mode changed.
Parameter changes are not sample-accurate: the plugin doesn't set NIH-plug's SAMPLE_ACCURATE_AUTOMATION, so a change lands at the start of the next block. The Plugin Lifecycle page covers process() in full.
Up to 16 voices (MAX_VOICES) sound at once. Only voices with is_rendering() true are processed, so idle voices cost nothing. Each returns a stereo pair; the manager adds them with no normalization, so one voice is not turned down when others play. A single voice's output is clamped to ±1 before its expression gain, which can raise it to 1.8 (pressure plus mod wheel), and a kit pad's level multiplies it further. Dense chords can therefore sum well past 1.0; the clipper and the limiter at the end of the chain handle that.
The voices also hold the voice-level stereo image: the resonator pans its modes alternately left and right by the Width parameter (see the voice loop). This is separate from the post chain's HRTF spread.
Each mode of the resonator responds to a constant force with a constant deflection. A one-signed force, such as a bow's pressure or a felt mallet's long contact, therefore leaves a static offset under the ringing. dsp::StereoDcBlocker removes it from the stereo sum before anything nonlinear sees it:
- second-order Butterworth high-pass, cutoff
VOICE_MIX_DC_CUTOFF_HZ= 10 Hz, bilinear with a prewarped cutoff; - coefficients and state in
f64: at 10 Hz the poles sit about 0.001 inside the unit circle, where anf32direct form would amplify its own rounding noise; - rated in
prepare(frominitialize) and in everybegin_block(a no-op when the rate is unchanged), cleared byreset()and at the end of a panic.
Why here: the master drive, the Lorenz drive and the diode clipper are all asymmetric. Fed an offset, they would shift their operating point and change the sound with the offset rather than with the music. Blocking it first keeps every nonlinearity centred. DC that later stages create (the asymmetric curves) is theirs to handle; the diode clipper has its own 2 Hz blocker. Corrosion::mix_dc_blocker_enabled is a test-only switch to compare with the unblocked path.
apply_drive(sample, drive) runs on each channel with the drive from drive_smoother, a OnePoleSmoother with a 20 ms time constant (TAU_SECONDS). Its target is Drive plus the Violence macro's offset ((v − 0.5)·1.0), clamped to 0..5.
- The shaper scales the input by
1 + 4·drive(DRIVE_GAIN_SCALE= 4), then applies an asymmetric soft-knee curve: linear below 0.3 (positive) or 0.25 (negative), a smoothstep knee up to 0.8 or 0.7, then an exponential approach capped at 1.2 or 1.1. - The output is a crossfade: shaped share
min(drive, 1), dry share the rest. Above 1 only the input gain keeps rising, so more drive means more saturation, not more level. The result is clamped to ±1.5 (DRIVE_OUTPUT_CLAMP). - At drive 0 the function returns the input unchanged.
reset() starts the smoother at its biased target, so the first note after a reset isn't driven by a ramp.
PostProcessingChain::process runs six stages per frame. Every quality mode runs every stage; quality changes only the clipper's oversampling (and, in the voices, the number of modes). See Post Chain for routing and quality modes.
| Order | Stage | Signal | What it does | Page |
|---|---|---|---|---|
| 1 |
WdfLadderFilter ×2 |
per channel | Four-pole ladder low-pass with soft saturation between stages; cutoff and resonance glide at audio rate. Cutoff is the parameter times the Brightness macro's factor 2^((b − 0.5)·2), clamped to 20 Hz–20 kHz. |
Filter and Drive |
| 2 |
LorenzDrive ×2 |
per channel | Soft tube curve whose gain a Lorenz attractor modulates; Drive Amount, Bias Starvation, Chaos Depth (Violence adds to the first and last). | Filter and Drive |
| 3 | FemBodyResonator |
mono sum (L + R)/2
|
Eight modal body resonators. The result times the body mix (Body / 5, smoothed with a 20 ms time constant) is added to both channels, in parallel with the dry signal. |
Body, Spread and Space |
| 4 | HrtfSpread |
stereo | Delays the mid signal by up to 1 ms with Spread Width, shapes it with proximity filters, adds the side back, crossfeeds. | Body, Spread and Space |
| 5 | Space | stereo | Off; Factory (a Schroeder reverb fed (L + R)/2, same wet on both sides); Spring (one tank per channel); Echo (stereo delay). The wet signal times Space Amount is added to the dry. |
Body, Spread and Space |
| 6 | OversampledClipper |
stereo | The diode stage: a tanh knee per polarity limited at Analog Ceiling ÷ 1.3, oversampled 1×/4×/8×/16× by quality mode through half-band IIR filters, with a 2 Hz DC blocker. | Output Protection |
Why this order:
- Filter and drive come first and stay per channel, so the voices' stereo image survives them (
hard_left_input_stays_leftinpost_chain.rschecks this). - The body is a property of the whole instrument, not of one channel, so it runs once on the mono sum and is added back in parallel. At Body 0 the chain equals the chain without the body (
body_zero_matches_chain_without_body). - Spread and Space come after the body, so the body's resonance is placed and reverberated with the rest.
- The clipper is last in the chain: it is the stage that bounds the level, and its limit is set under the ceiling so the down-sampling filters' overshoot still lands under the limiter.
The Output parameter stores a linear gain from 0 to +40 dB (shown in dB, see Parameters). output_gain_smoother (20 ms) follows it per sample. It comes after the clipper and before the limiter: Output can make the plugin quieter or louder, and whatever it does, the limiter still holds the ceiling. The clipper limits at the ceiling ÷ 1.3, so above roughly +2.3 dB of Output (20·log10 1.3) clipped peaks reach the limiter.
When a CC120 arrives, start_panic sets a linear fade over PANIC_FADE_SECONDS = 5 ms (240 samples at 48 kHz). render_frame_unlimited checks panic_step > 0.0 and only then calls panic_frame, a #[cold], #[inline(never)] function, so the normal path pays one comparison. At the end of the fade it clears the voices (VoiceManager::silence), the DC blocker, the post chain and both lookahead limiters in place, and outputs exactly zero. Details on Voices and Polyphony.
limit_frame applies the Limiter Mode, both at the Analog Ceiling (parameter 0.5–1.0, default 0.9661 ≈ −0.3 dBFS; the code clamps it to 0.1–1.0):
-
Hard (0, default):
apply_output_limiter, a clamp to±ceiling. No latency. -
Lookahead (1): one
LookaheadLimiterper channel, unlinked. Each delays its input byLOOKAHEAD_SAMPLES= 48 samples (1 ms at 48 kHz; the count is fixed, so it is 0.5 ms at 96 kHz), takes the peak of its window, attacks instantly toceiling / peak, releases with a 50 ms one-pole, and clamps the result to the ceiling as a last guard. The 48 samples are reported to the host as latency.
Either way no output sample exceeds the ceiling. Output Protection covers both limiters and the clipper.
The four macros (Mass, Corrosion, Violence, Macro Brightness, each 0..1, neutral at 0.5) don't have a stage of their own. resolve_macro_bias turns them into offsets and factors that act at several points of the chain. With m, c, v, b the macro values minus 0.5:
| Target | Bias | Applied |
|---|---|---|
| Exciter masses (Hand, Mallet, Stick, Pipe, Chain, drag Exciter, Particle) | × max(1 + m, 0.1)
|
note-on (apply_macro_bias_to_controls) |
| Size | × max(1 + 0.5·m, 0.1), then clamped to 0.05–10 |
note-on |
| Resonator damping | + 0.4·c, clamped 0–1 |
note-on and live on held notes |
| Resonator brightness | + −0.4·c + 0.6·b, clamped 0–1 |
note-on and live on held notes |
| Rust | + 2·c, clamped 0–5 |
note-on |
| Damage | + 4·v, clamped 0–10 |
note-on |
| Master drive | + v, clamped 0–5 |
per block, smoothed |
| Drive Amount (Lorenz) | + 0.4·v, clamped 0–5 |
per block |
| Chaos Depth | + 0.4·v, clamped 0–1 |
per block |
| Filter cutoff | × 2^(2·b) (±2 octaves), clamped 20–20 000 Hz |
per block |
At 0.5 every bias is exactly neutral (neutral_macros_produce_neutral_bias). The mass factors are not clamped to the exciter parameters' ranges.
Voice::process_sample_stereo(sample_rate, width) is called once per sample for every rendering voice. It is the hottest code in the plugin after the resonator's mode loop. In order:
-
Gate. Return
(0, 0)at once if the voice isn't rendering. -
Rate check.
set_ratecompares the rate with the cached one; only a change re-derives the per-sample constants (VoiceRateConstants) and re-rates all 16 exciters. -
Exciter force (
process_exciter):- Move the smoothed Pressure gain toward its target (10 ms time constant,
PRESSURE_SMOOTHING_S). At rest this adds exactly zero. - If the key is up and every envelope is idle, return 0: nothing excites the object any more.
- Read the resonator's displacement and velocity from the last sample.
- Advance the force envelope of the exciter's family: one-shot AR for Hit exciters, ADSR for Specialty, the 6-stage MSEG for Friction (see Envelopes and Modulation).
- If Position Envelope is on, move the strike position with the envelope before the resonator prepares this sample.
- Turn on the resonator's ring-bound tracking while the envelope is above 0 (the drive governor needs it). An envelope at 0 returns 0.
- Dispatch on
exciter_type(amatchon 1..16, no trait objects). Position-driven exciters get aContactPrediction(this sample's displacement asfree + compliance·F) and solve their contact implicitly; Bow, Stiff Point, Corrugated Drag, Tension Rise and Pneumatic Jet read the resonator's velocity; Wire Brush and Electromagnetic Hum read its displacement. - Multiply by the envelope and
force_scale()(the exciter'sEXCITER_DRIVE_LEVEL, the test-onlydrive_scale, the governor gain and the Pressure gain), then cap the force so the resonator's ring bound can't pass 0.9 (GOVERNOR_CEILING).
- Move the smoothed Pressure gain toward its target (10 ms time constant,
-
Resonator.
ModalResonator::process_sample_stereo(force, rate, width)spreads the force over the modes by the strike-position weights and the coupling blend, advances every mode, and pans each mode bywidth · index / count, alternating sides between even and odd modes (gains0.5·(1 ∓ pan), so left plus right is the mono sum). It also stores the displacement and velocity the exciter reads next sample. See Modal Resonator. -
Governor.
update_governorfollows the ring bound (1 ms attack, 200 ms release) and above 0.7 sets the force gain to(0.7 / level)^8for the next sample. - Sanitize. A non-finite sample, or one smaller than 1e-30, becomes 0, per channel.
-
Damage rattle.
rattle_noiseadds white noise, the same value to both channels, when Damage is above 0 and the mono level(L + R)/2is above0.02 + (1 − min(damage, 1))·0.15. See Material Transformations. -
Velocity high-pass boost. A one-pole low-pass (pole 0.8 at 48 kHz, corner near 1.7 kHz) runs on the mono signal plus rattle; the difference (a high-pass) times
1.5 · velocity / 127is added to both channels. Harder notes come out brighter. -
Clamp. Each channel is clamped to ±1. The largest value before the clamp is kept in
pre_clamp_peakfor tests. -
Expression and pad gain. Multiply by
1 + 0.5·max(channel pressure, poly pressure) + 0.3·mod wheel(up to 1.8) and by the kit pad's gain (1 for a normal voice). See Note Expression and Kit Mode. -
Denormal flush.
x + 1e-20 − 1e-20on each channel. -
Peak and tail tracking.
peak_holdtakes the larger clamped channel and decays by 0.999 per sample at 48 kHz (a time constant of about 21 ms). When the key is up andpeak_holdstays underTAIL_ENERGY_THRESHOLD= 1e-4 forTAIL_DEACTIVATE_FRAMES(4800 at 48 kHz, 100 ms), the voice stops rendering.peak_holdalso ranks voices for stealing. -
Choke fade. If a host choke is running, the frame is scaled by the choke's linear ramp (
choke_gain, out of line), and the voice resets to idle on its last sample.
Voice::process_sample(sample_rate) is the mono twin, used by tests and benchmarks through VoiceManager::process_sample. It is the same loop without per-mode panning: the resonator returns the full mode sum, so its level is the sum of the stereo pair, not either channel.
Traps:
- The per-mode work in step 4 dominates CPU. Data a mode needs only occasionally must not go into
SecondOrderMode; see Modal Resonator and Benchmarks and Performance. - Steps 10 and 11 come after the clamp, so the voice output is not bounded by 1. Code that assumes it is (a meter, a test bound) must account for the expression and pad gains.
- The rattle and the high-pass act on the mono signal and add the same value to both channels, so they are centred whatever Width does.
-
src/lib.rs:process_block,begin_block,render_frame_unlimited,limit_frame, the master drive, the macro biases, the panic fade. -
src/voice/mod.rs:Voice::process_sample_stereoandprocess_sample, the force envelopes, the governor, the expression gain. -
src/voice/manager.rs: the voice sum. -
src/dsp/mod.rs: the DSP module's re-exports (PostProcessingChain,StereoDcBlocker,LookaheadLimiter,LOOKAHEAD_LIMITER_SAMPLES, the exciters and resonators). -
src/dsp/post_processing/post_chain.rs: the post chain's stage order and body mix. -
src/dsp/utils/dc_blocker.rs: the voice-mix DC blocker. -
src/dsp/post_processing/lookahead_limiter.rs: the Lookahead limiter. -
src/dsp/resonators/core.rs:ModalResonator::process_sample_stereoand its per-mode panning.
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