Repository navigation
Post Chain
Everything that happens to the sound after the voices are summed: one DC blocker, the master drive, the PostProcessingChain (filter, Lorenz drive, FEM body, HRTF spread, Space, diode stage), the output gain and the output limiter. This page covers the routing, the order and why, the quality modes, oversampling, latency and state handling. The stages themselves have their own pages: Filter and Drive, Body, Spread and Space and Output Protection.
The post chain is global: one instance per plugin, not per voice. It runs one stereo frame at a time inside the same per-sample loop as the voices (Corrosion::process_block), and its parameters are set once per host block.
flowchart TD
voices["VoiceManager::process_sample_stereo<br/>sum of rendering voices (L, R)"]
dc["StereoDcBlocker<br/>10 Hz 2nd-order Butterworth"]
master["apply_drive<br/>master Drive, smoothed per sample"]
subgraph chain["PostProcessingChain::process"]
filt["WdfLadderFilter<br/>one per channel"]
lor["LorenzDrive<br/>one per channel"]
body["FemBodyResonator<br/>on (L+R)/2, x body_amount"]
add(("+"))
spread["HrtfSpread"]
space["Space: Off, Factory, Spring or Echo<br/>dry + wet x Space Amount"]
clip["OversampledClipper<br/>diode stage, 1x to 16x"]
filt --> lor --> add
lor -->|"mono sum"| body -->|"same signal to L and R"| add
add --> spread --> space --> clip
end
gain["x Output gain, smoothed per sample"]
panic["All Sound Off fade, only while active"]
lim["limit_frame<br/>Hard clamp or LookaheadLimiter"]
out(["host output, channels 0 and 1"])
voices --> dc --> master --> filt
clip --> gain --> panic --> lim --> out
The same path as a list, in processing order. Everything above the limiter is Corrosion::render_frame_unlimited; the limiter is Corrosion::limit_frame.
-
Voice mix.
VoiceManager::process_sample_stereo(sample_rate, width)sums every voice whoseis_rendering()is true. There is no normalization: 16 loud voices sum to 16 times one. -
Voice-mix DC blocker.
Corrosion::block_mix_dcrunsdsp::StereoDcBlocker(10 Hz,VOICE_MIX_DC_CUTOFF_HZ) on both channels. See Output Protection. -
Master drive.
apply_drive(sample, drive)per channel, with the drive fromdrive_smoother(the Drive parameter plus the Violence macro's bias). See Filter and Drive. -
Filter, per channel:
WdfLadderFilter::process. -
Lorenz drive, per channel:
LorenzDrive::process. -
FEM body, in parallel:
FemBodyResonator::process((L + R) / 2), times the smoothed body amount, added to both channels. -
HRTF spread:
HrtfSpread::process(L, R). - Space: when the mode isn't Off, the selected processor's wet output times Space Amount is added to the dry signal.
-
Diode stage:
OversampledClipper::process_stereo, the chain's last stage. -
Output gain: times
output_gain_smoother.next(). -
Panic fade: only while an All Sound Off fade is running (
panic_frame). -
Output limiter:
apply_output_limiter(Hard) orLookaheadLimiter::process(Lookahead), at the Analog Ceiling.
process() writes the result to output channels 0 and 1. The offline renderer (offline::PresetRenderer) and the web engine (WebEngine::process) call the same process_block, so tools, tests and the web app hear exactly what the plugin outputs.
The reasons below come from the code's own comments; where the code gives none, this page says so.
- The DC blocker comes first so that every nonlinear stage after it (the master drive, the Lorenz drive's tube curve, the diode stage) sees a signal centred on zero. The modal voices leave a static deflection under one-signed forces such as a held bow or a slow mallet contact; an offset like that would make a symmetric curve clip one side first.
-
Filter and drive run per channel ("dual-mono, so the voice engine's stereo image survives",
post_chain.rs). A hard-left voice stays hard left through them (hard_left_input_stays_left). -
The body runs once, on the mono sum, in parallel, and its output is added to both channels at the BODY amount. With BODY at 0 the chain is exactly the chain without a body (
body_zero_matches_chain_without_body). - The diode stage is last in the chain because it is the protection stage: its limit is the ceiling divided by 1.3, which leaves headroom for its own down-sampling filters' overshoot under the output limiter that follows. See Output Protection.
- Output gain comes after the diode stage, so the Output knob doesn't change how hard the diode stage clips. It scales the already-clipped signal into the limiter. Arithmetic from the constants: a signal sitting at the diode limit (ceiling ÷ 1.3) reaches the ceiling at an Output gain of 1.3, about +2.3 dB. Above that, the Hard clamp or the Lookahead limiter does the limiting.
- Filter before drive is not explained in the code.
-
Parameters are set once per block, not per sample: the setters recompute coefficients (the filter's
tan, the body's mode table, the reverb's delay lengths) that must not run at audio rate (begin_block's doc comment). The stages that need it smooth their own controls at audio rate. - The chain runs per sample, not per block. The voices must run per sample (the exciter and resonator are coupled both ways), and the post chain shares that loop. Processing the post chain in blocks is a possible later optimization, not done.
Corrosion::render_frame_unlimited is the boundary between the voice engine and the post chain:
let (left, right) = self.voice_manager.process_sample_stereo(block.sample_rate, block.width);
let (left, right) = self.block_mix_dc(left, right);
let drive_smoothed = self.drive_smoother.next();
let left = apply_drive(left, drive_smoothed);
let right = apply_drive(right, drive_smoothed);
let (left, right) = self.post_chain.process(left, right);
let gain = self.output_gain_smoother.next();-
block.widthis the Width parameter (−2 to 3, default 0.5): the voices' own stereo width, set before the mix. It is a different control from Spread Width, which belongs to the HRTF spread inside the chain. See Voices and Polyphony. -
mix_dc_blocker_enabledis a test-only switch (pub(crate)) that bypasses the DC blocker, to compare against the path without it. -
drive_smootherandoutput_gain_smootherareOnePoleSmoothers insrc/lib.rs(τ 20 ms,current += (target − current)·coeffper sample).begin_blocksets their targets;reset()rebuilds them at their targets.
PostProcessingChain (src/dsp/post_processing/post_chain.rs) owns one instance of each stage. Two filters, two drives and two springs exist because those stages run per channel.
| Stage | Field(s) | Channels | Struct | Details |
|---|---|---|---|---|
| Ladder filter |
filter_left, filter_right
|
per channel | WdfLadderFilter |
Filter and Drive |
| Lorenz drive |
drive_left, drive_right
|
per channel | LorenzDrive |
Filter and Drive |
| Body | body |
mono sum, added to both | FemBodyResonator |
Body, Spread and Space |
| Spread | spread |
stereo in, stereo out | HrtfSpread |
Body, Spread and Space |
| Factory room | factory_reverb |
mono in, same wet on both | FactoryReverb |
Body, Spread and Space |
| Spring |
spring_left, spring_right
|
per channel | SpringReverb |
Body, Spread and Space |
| Echo | factory_echo |
per channel, one struct | FactoryEcho |
Body, Spread and Space |
| Diode stage | clipper |
per channel, shared settings | OversampledClipper |
Output Protection |
The chain also keeps space_mode, space_amount (clamped to 0–1, not smoothed), the BODY mix (body_amount, its target and a primed flag, smoothed with τ 20 ms in process) and quality_mode.
src/dsp/post_processing/mod.rs declares the nine modules and re-exports the public types: FemBodyResonator, HrtfSpread, LookaheadLimiter, LorenzDrive, DiodeMeter, OversampledClipper, PostProcessingChain, PostQualityMode, FactoryEcho, FactoryReverb, SpaceMode, SpringReverb and WdfLadderFilter. src/dsp/mod.rs re-exports them again as dsp::…, and also LOOKAHEAD_SAMPLES as dsp::LOOKAHEAD_LIMITER_SAMPLES.
The plugin has one audio layout: no input, a stereo main output (AUDIO_IO_LAYOUTS). Everything from the voice mix on is stereo.
| Stage | How it treats the two channels |
|---|---|
| Voice mix | stereo; each voice pans or widens itself with Width |
| DC blocker, master drive | the same filter or curve on each channel, separate state |
| Filter, Lorenz drive | dual-mono; both attractors start from the same state and don't depend on the input, so their chaos is identical left and right |
| Body | one resonator on (L + R)/2; the same body signal is added to both channels |
| Spread | mid/side: rebuilds both channels from a delayed, filtered mid plus a scaled side, then crossfeeds |
| Factory room | sums to mono and returns (wet, wet)
|
| Spring | one tank per channel; a left-only input leaves the right tail silent |
| Echo | separate left and right delay lines, no cross-feedback |
| Diode stage | separate half-band and DC memory per channel; one curve and one meter for both |
| Output gain | one gain for both |
| Lookahead limiter | two independent limiters: each channel computes its own gain (not stereo-linked) |
A mono input stays exactly mono: mono_input_stays_mono asserts l == r bit for bit through the filter, drive, body and diode stage, and the spread and every Space mode keep it by construction (a zero side signal, identical wet channels).
Corrosion::begin_block runs once per host block, before any sample. It resolves the macro bias, sets the drive and output-gain smoother targets, configures the output limiters (configure_output_limiters) and calls apply_post_chain_params, which pushes every post-chain parameter into the chain:
| Setter | Parameters (and macro bias) |
|---|---|
set_sample_rate |
the host rate, every block |
set_filter_params |
Filter Cutoff × Brightness factor (clamped 20–20 000 Hz), Filter Resonance, Component Tolerance |
set_drive_params |
Drive Amount + Violence offset (0–5), Bias Starvation, Chaos Depth + Violence offset (0–1) |
set_body_params, set_body_amount
|
Chassis Material, Chassis Volume; BODY ÷ 5 (body_mix) |
set_spread_params |
Spread Width, Listener Proximity |
set_space_mode, set_space_amount
|
Space Mode (0 Off, 1 Factory, 2 Spring, 3 Echo; anything else Off), Space Amount |
set_quality_mode |
Quality Mode (0 Eco, 1 Normal, 2 High, 3 Render; anything else Normal) |
set_factory_params, set_spring_params
|
Factory Size, Machinery Clutter, Wall Impedance; Spring Tension, Spring Wire Stiffness, Spring Tank Size |
set_echo_params |
Delay Time (or the tempo-synced value from sync_rate_to_delay_time), Machinery Movement, High Frequency Damping |
set_clipper_params |
Analog Ceiling, Diode Softness, Diode Asymmetry |
The macro bias comes from resolve_macro_bias (see Parameters). Values move only at block boundaries, so a stage without its own smoother steps once per block. These stages smooth at audio rate:
| Control | Where | Time constant |
|---|---|---|
| Drive (master) |
drive_smoother in src/lib.rs
|
20 ms |
| Output |
output_gain_smoother in src/lib.rs
|
20 ms |
| Filter Cutoff, Filter Resonance | WdfLadderFilter |
20 ms |
| Drive Amount | LorenzDrive |
20 ms |
| BODY | PostProcessingChain::body_amount |
20 ms |
| Machinery Movement | FactoryEcho::movement_smoothed |
20 ms |
| Diode Softness, Diode Asymmetry | OversampledClipper |
20 ms |
Everything else (Space Amount, Spread Width, the reverb and echo sizes and times, Analog Ceiling, Chassis Material and Volume, Chaos Depth, Bias Starvation, Component Tolerance) takes its new value at the next block.
First set snaps. The filter, the Lorenz drive and the BODY mix jump straight to the first values they receive after new() or reset(), so a preset loaded before playback doesn't glide in. The diode stage snaps until it has processed its first sample.
The Quality Mode parameter (QualityMode in src/params.rs) is mapped to PostQualityMode in apply_post_chain_params. Every mode runs every stage. A mode changes two things only: the diode stage's oversampling, and the number of modes each new voice gets.
| Mode | Value | Diode stage oversampling | Half-band stages | Voice mode-count scale |
|---|---|---|---|---|
| Eco | 0 | 1× (curve at the host rate) | 0 | 0.5× |
| Normal (default) | 1 | 4× | 2 | 1.0× |
| High | 2 | 8× | 3 | 1.5× |
| Render | 3 | 16× | 4 | 2.0× |
The oversampling factor comes from PostQualityMode::clipper_oversample_factor and reaches the clipper through set_quality_mode → OversampledClipper::set_oversample_factor. The mode-count scale comes from quality_mode_count_scale in src/lib.rs and is written into VoiceControls::mode_count_scale at note-on (see Modal Resonator).
Two timings. The chain reads the mode every block, so the clipper's oversampling changes at once. Each voice's mode count is fixed at its note-on, so sounding notes keep their density until they end. Switching Eco ↔ Render mid-note changes the clipper immediately and the modal density only for new notes.
The diode stage's figures per mode, as recorded in docs/ARCHITECTURE.md (measured at the default Diode Softness 0.5 and Asymmetry 0.25, 48 kHz; they are not asserted by a test):
| Mode | Alias, 5 kHz sine at 2× the ceiling | Delay at 1 kHz |
|---|---|---|
| Eco | −19.7 dB | −0.015 samples (the 2 Hz DC blocker's phase lead) |
| Normal | −67.0 dB | 4.2 samples |
| High | −94.2 dB | 4.7 samples |
| Render | −105.0 dB | 5.0 samples |
The tests assert bounds only: −40 dB in Normal and −60 dB in Render, with and without the hard clamp after the clipper (clipper_alias_bounds_hold, clipper_alias_bounds_hold_through_the_hard_clamp in src/offline/mod.rs). For CPU figures, see Benchmarks and Performance.
Only the diode stage is oversampled. The ladder filter's saturators, the master drive and the Lorenz drive all run at the host rate, so the harmonics they make above Nyquist fold back and are part of the sound. The whole-chain aliasing harness (offline::analyze_post_chain_aliasing, run by render --suite aliasing: Render quality, Drive Amount 2.5, a 9 kHz tone at 0.85) is therefore dominated by the Lorenz drive, not the clipper. docs/ARCHITECTURE.md records −20.5 dB for it; the test render_mode_alias_ratio_stays_within_budget holds it under −18 dB, and higher_quality_reduces_alias_ratio checks that Render aliases less than Eco.
The oversampling machinery (cascaded 2× polyphase half-band IIR stages) is described on Output Protection.
Output (output_param in src/params.rs) stores a linear gain from 0 to db_to_gain(40.0) (×100, +40 dB), default 1.0 (0 dB). It is shown and typed in dB (v2s_f32_gain_to_db / s2v_f32_gain_to_db, −inf at 0) and uses a gain-skewed range (gain_skew_factor(−60, 40)), which puts −10 dB at the middle of the travel and 0 dB at about 57 %. Storing the gain, not dB, keeps presets and projects at their level. Host automation is stored as normalized positions, so any change to this range or taper moves automated levels, and that can't be migrated (see Presets and Migrations).
The gain is applied after the diode stage and before the limiter (see Why this order). The factory bank uses Output as each preset's level trim (see Factory Bank).
Only the Lookahead limiter adds reported latency.
| Limiter Mode | Reported latency |
|---|---|
| Hard (0, default) | 0 samples |
| Lookahead (1) |
dsp::LOOKAHEAD_LIMITER_SAMPLES = 48 samples at every rate (1 ms at 48 kHz, 0.5 ms at 96 kHz) |
-
Corrosion::prepare(called byinitialize, and by the web host) records the restored Limiter Mode's latency, andinitializereports it withcontext.set_latency_samplesbefore the host settles its delay compensation. -
process()callslatency_change(block.limiter_mode)after each block and reports only when the value differs from the last one reported, because hosts may renegotiate buses on every call. - Not reported: the diode stage's half-band filters delay low frequencies by about 4–5 host samples in Normal to Render (table above). The spread's mid delay (up to 1 ms) is an effect, not latency.
Plugin::reset (the host may call it on the audio thread, so it must not allocate):
- resets the voices, the voice-mix DC blocker and
PostProcessingChain::reset; - rebuilds
drive_smootherat Drive plus the Violence bias, wherebegin_blockwill aim it, so the first note after a reset isn't driven by a ramp from the unbiased Drive; - rebuilds
output_gain_smootherat Output; - resets both Lookahead limiters and clears any panic fade.
PostProcessingChain::reset resets every stage: the filters' integrators and noise (and re-primes their smoothers so the next set snaps), the drives' attractors and starvation gain, the body's state, the spread's delay and filters, all three Space processors' buffers, and the clipper's half-band and DC memory (with its controls snapped to their targets). It also re-primes the BODY smoother. Everything is cleared in place, without allocating.
All Sound Off (CC120) starts a 5 ms linear fade (PANIC_FADE_SECONDS) applied after the output gain. When it reaches zero, panic_frame silences every voice and resets the DC blocker, the post chain and the Lookahead limiters, so the output is exactly zero until the next note. See Voices and Polyphony.
-
The chain is reconfigured every block.
apply_post_chain_paramscallsset_sample_rateand everyset_*method on each block, whether or not anything changed. That recomputes smoothing coefficients, the filter'stan, the body's mode table and the reverb's delay lengths. It is cheap but redundant. The reverb's delays are always derived from their 48 kHz constants, never from the previous delay, so repeated updates can't compound. -
A new chain's clipper is at 16×.
PostProcessingChain::new()recordsPostQualityMode::Normalbut doesn't callset_oversample_factor, andOversampledClipper::new()starts at 16×. The plugin callsset_quality_modein every block, so this only matters to code that builds a chain by hand (tests, benchmarks,offline::analyze_post_chain_aliasing_at_quality, which sets the mode). -
Changing Quality clears the clipper's filter memory.
set_oversample_factorresets the half-band and DC state when the number of stages changes, which gives a short discontinuity if audio is playing. - Space Amount and Space Mode switch hard. Space Amount has no smoother, so automating it steps once per block. Only the selected Space processor runs: the others keep their buffers frozen, so switching back to a mode replays the tail it held when it was left, and switching away cuts the wet signal in one sample. See Body, Spread and Space.
- Clamps inside stages shape loud signals. The filter's stage saturators (soft above 0.7, at most 1), the Lorenz drive's output clamp (±1 whenever Drive Amount is above 0.001), the body's ±10 per mode and ±1 overall, and the spread's ±1.5 are guards, not the protection stage. A voice mix above ±1 is already reshaped before it reaches the diode stage.
-
Bit-identity claims need a switch. Tests that prove a default is unchanged use test-only switches such as
mix_dc_blocker_enabled,LorenzDrive::starvation_stage_enabledandOversampledClipper::dc_stage_enabled. Keep them when you change those stages.
History: the per-block parameter path and the shared process_block are described in docs/ARCHITECTURE.md and the render-through-the-post-chain change.
-
src/dsp/post_processing/mod.rs: the post-processing modules and their public re-exports. -
src/dsp/post_processing/post_chain.rs:PostProcessingChain(stage order, BODY smoothing, Space routing, reset) andPostQualityMode; routing tests. -
src/lib.rs:begin_block,apply_post_chain_params,render_frame_unlimited,limit_frame,prepare,latency_change,reset, the panic fade and the quality mode-count scale. -
src/params.rs:QualityMode, the Output, Limiter Mode and post-chain parameter constructors and defaults. -
src/offline/mod.rs: the aliasing analyzers and the alias-bound tests. -
benches/performance.rs: thepost_processing_chain,post_processing_chain_ecoandpost_processing_chain_idlebenchmarks.
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