Skip to content

Post Chain

github-actions[bot] edited this page Nov 19, 2026 · 1 revision

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.

The whole output path

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
Loading

The same path as a list, in processing order. Everything above the limiter is Corrosion::render_frame_unlimited; the limiter is Corrosion::limit_frame.

  1. Voice mix. VoiceManager::process_sample_stereo(sample_rate, width) sums every voice whose is_rendering() is true. There is no normalization: 16 loud voices sum to 16 times one.
  2. Voice-mix DC blocker. Corrosion::block_mix_dc runs dsp::StereoDcBlocker (10 Hz, VOICE_MIX_DC_CUTOFF_HZ) on both channels. See Output Protection.
  3. Master drive. apply_drive(sample, drive) per channel, with the drive from drive_smoother (the Drive parameter plus the Violence macro's bias). See Filter and Drive.
  4. Filter, per channel: WdfLadderFilter::process.
  5. Lorenz drive, per channel: LorenzDrive::process.
  6. FEM body, in parallel: FemBodyResonator::process((L + R) / 2), times the smoothed body amount, added to both channels.
  7. HRTF spread: HrtfSpread::process(L, R).
  8. Space: when the mode isn't Off, the selected processor's wet output times Space Amount is added to the dry signal.
  9. Diode stage: OversampledClipper::process_stereo, the chain's last stage.
  10. Output gain: times output_gain_smoother.next().
  11. Panic fade: only while an All Sound Off fade is running (panic_frame).
  12. Output limiter: apply_output_limiter (Hard) or LookaheadLimiter::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.

Why this order

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.

Where the voice mix enters

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.width is 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_enabled is a test-only switch (pub(crate)) that bypasses the DC blocker, to compare against the path without it.
  • drive_smoother and output_gain_smoother are OnePoleSmoothers in src/lib.rs (τ 20 ms, current += (target − current)·coeff per sample). begin_block sets their targets; reset() rebuilds them at their targets.

Inside PostProcessingChain

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.

Mono and stereo handling

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).

Parameters and smoothing

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.

Quality modes

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.

Oversampling

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 gain

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).

Latency

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 by initialize, and by the web host) records the restored Limiter Mode's latency, and initialize reports it with context.set_latency_samples before the host settles its delay compensation.
  • process() calls latency_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.

Reset, panic and the first block

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_smoother at Drive plus the Violence bias, where begin_block will aim it, so the first note after a reset isn't driven by a ramp from the unbiased Drive;
  • rebuilds output_gain_smoother at 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.

Traps

  • The chain is reconfigured every block. apply_post_chain_params calls set_sample_rate and every set_* method on each block, whether or not anything changed. That recomputes smoothing coefficients, the filter's tan, 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() records PostQualityMode::Normal but doesn't call set_oversample_factor, and OversampledClipper::new() starts at 16×. The plugin calls set_quality_mode in 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_factor resets 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_enabled and OversampledClipper::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.

Source files

  • 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) and PostQualityMode; 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: the post_processing_chain, post_processing_chain_eco and post_processing_chain_idle benchmarks.

Clone this wiki locally