Repository navigation
Parameters
Every control a host can automate is a field of CorrosionParams in src/params.rs: 149 parameters, plus two persisted fields that are not parameters and the kit's audio-side table. This page explains how a parameter is declared and built, how IDs, names, ranges and display work, where smoothing happens, which controls act live and which only at note-on, and how the integer enums map to models and modes.
flowchart LR
ctor["constructor<br/>size_param(value)"]
def["CorrosionParams::default()"]
preset["Preset::into_params()"]
host["host and editor<br/>set normalized values"]
blk["begin_block<br/>once per block"]
non["note_setup<br/>at each note-on"]
dsp["voices and post chain"]
ctor --> def
ctor --> preset
def --> host
host --> blk --> dsp
host --> non --> dsp
As steps:
- A constructor function,
<id>_param(value)(for examplesize_param,filter_cutoff_param,output_param), sets the parameter's display name, range, clamp and formatters. -
CorrosionParams::default()calls it with the default;Preset::into_params(andPresetParameters::apply_to) calls the same function with the preset's value. So a parameter built from a preset displays exactly like the live one (preset_built_parameters_display_like_the_live_onesintests/preset_roundtrip.rs). - The host, the editor (through NIH-plug's
ParamSetter) and preset loading change values. - The audio thread reads plain values with
.value(): once per block inbegin_block, or at note-on innote_setup(src/lib.rs).
#[derive(Params)] on CorrosionParams generates NIH-plug's Params impl. Each parameter field carries #[id = "..."]:
#[id = "size"]
pub size: FloatParam,- The ID is the contract. Hosts store automation and project state by ID, and preset files store values by the same names. Never rename an ID; change a meaning only with migrations (see Plugin Lifecycle and Presets and Migrations).
-
Display names are unique. Hosts list parameters by name;
parameter_names_are_uniquefails on a duplicate. Shared labels in the editor (two "Brightness" knobs) get distinct host names: "Resonator Brightness" and "Macro Brightness", "Brush Wire Stiffness" and "Spring Wire Stiffness", "Onset Time" and "Onset Level". -
Field order is
param_map()order. The browser engine addresses parameters by index in that order, so the web engine and editor must be built from the same source (they always are). - There are no
#[nested]groups; the editor's panels are defined insrc/gui/controls.rs, not here.
There are exactly 149 constructor functions, one per parameter. Adding a parameter means, at least:
- a constructor in
params.rsand a field with#[id], built inDefault; - a field in the preset format (
PresetParametersinsrc/presets/mod.rs), set infrom_paramsandapply_to; - reading it where it acts: a
VoiceControlsfield filled innote_setup, or a setter inbegin_block/apply_post_chain_params; - an editor control (
editor_covers_every_parameterfails otherwise;HOST_ONLY_PARAMSinsrc/gui/editor.rs, empty today, lists exceptions with reasons) and its ⓘ help inhelp_for; - a decision for kits: post-chain and master parameters go in
NON_PAD_PARAMS(src/kit/mod.rs); - the user Wiki data and clip plan (Site and User Wiki Tooling), and a factory reseed for the schema (Factory Bank).
Most parameters are linear FloatParams shown through significant_display: five significant digits, trailing zeros removed (significant_text). Five, not seven, leaves room for the normalized-to-plain round trip, so text read back shows the same text; clap-validator's param-conversions checks exactly that, and parameter_text_round_trips repeats it over 20 000 values per parameter. Parameters with their own formatting:
| Parameter | Stored | Shown | Notes |
|---|---|---|---|
Output (output) |
linear gain 0 to db_to_gain(40)
|
dB, -inf at 0 |
FloatRange::Skewed with gain_skew_factor(-60, 40): −10 dB at mid travel, 0 dB at about 57 %, −20..+6 dB over about 19 %. Parsed from typed dB. |
Pressure (exciter_pressure) |
0..1 | dB of 2^((p − 0.5)·4), −12..+12 |
Typing "6 dB" or a plain 0–1 value both parse. |
Speed (exciter_speed) |
0..1 |
× of 2^((s − 0.5)·2), ×0.5..×2 |
Accepts "×1.5", "x1.5" or 0–1. |
Roughness (exciter_roughness) |
0..1 |
× of r / 0.3, ×0..×3.33 |
Neutral at 0.3, not 0.5. |
Wander Rate (position_wander_rate) |
0.1..5 Hz | Hz, 2 decimals | Skewed (skew_factor(-1.5)): slow rates get more travel. |
Sync Rate (sync_rate) |
0..1 | "Off" below 0.05, then six equal bands 1/16, 1/8, 1/4, 1/2, 1/1, 2/1 |
sync_division serves both the echo and the display, so the display names what plays. Typing a division picks its band's middle. |
Filter Cutoff (filter_cutoff) |
20..20 000 | number | Skewed, factor 0.5. |
| Exciter, Object, Quality Mode, Note Mode, Limiter Mode, UI Scale | integers | names | See the enums. |
| Space Mode, Loop Mode, Loop Start/End Stage | integers | the integer | No formatter: hosts show 0..3, 0..2, 0..5. The editor shows names. |
Every constructor clamps its value into range, so a hand-edited preset can't create an out-of-range parameter.
No parameter uses NIH-plug's smoothers: .value() is the raw value, read at block start. Smoothing lives in the DSP, where the stage knows what it needs:
| What | Where | Time constant |
|---|---|---|
| Drive (with the Violence bias) |
drive_smoother, src/lib.rs
|
20 ms |
| Output | output_gain_smoother |
20 ms |
| Pressure | per voice, PRESSURE_SMOOTHING_S
|
10 ms |
| Body mix | PostProcessingChain |
20 ms |
| Filter cutoff and resonance | WdfLadderFilter |
about 20 ms, first value snaps |
| Drive Amount | LorenzDrive |
about 20 ms, first value snaps |
| Machinery Movement | FactoryEcho |
20 ms |
| Diode Softness and Asymmetry | OversampledClipper |
20 ms, snap on the first sample and on reset |
Everything else steps at block boundaries. The first-value snaps mean a preset loaded before playback doesn't glide in.
A voice copies most parameters into a VoiceControls snapshot at note-on, so a knob move doesn't reach notes already sounding. A few are re-sent every block. The rule by group:
| Acts | Parameters |
|---|---|
| Every block, on all sound | Drive, Output, Width (voice pan spread, passed every sample to every sounding voice, tails included), Body, Limiter Mode, Analog Ceiling, all post-chain parameters (filter, Lorenz drive, chassis, spread, Space and its sub-parameters, Sync Rate, Delay Time, diode), the macros' Violence and Brightness biases on the post chain |
| Every block, on held voices only | Resonator Damping, Resonator Brightness (both with the Corrosion and Brightness macro biases), Strike Position, Coupling Stiffness, Position Wander, Wander Rate, Position Envelope, Fundamental Anchor, Pressure. Sent by VoiceManager::update_live_controls to voices that are is_active() and not kit pads. Released tails keep their note-on values, so they decay with the timbre they had. |
| At note-on | Exciter, Object, Note Mode, Size, Rust, Damage, Thickness, Heat, Sludge, the 14 object character parameters, every exciter model control, Speed, Roughness, all envelope parameters and the Gesture Modifiers, the Mass and Corrosion macros' voice-side biases |
| Both | Quality Mode: the clipper's oversampling changes at once; the mode count (Eco 0.5×, Normal 1×, High 1.5×, Render 2×) is taken at note-on into VoiceControls::mode_count_scale
|
| Editor only | UI Scale |
The Gesture Modifiers (Env Amount, Velocity To Peak, Global Time Scale, Velocity To Level, Velocity To Time, Curve Tension) and the MSEG parameters only configure the friction MSEG; Hit exciters use Attack and Release, Specialty exciters Attack, Decay, Sustain and Release (Envelopes and Modulation). The macro routing is tabled on Signal Chain.
| Field | Attribute | Type | What |
|---|---|---|---|
editor_state |
#[persist = "editor-state"], gui feature only |
Arc<EguiState> |
The window size, default 810×630 (75 % of the 1080×840 base). |
kit |
#[persist = "kit"] |
Arc<RwLock<KitState>> |
Kit mode's pads, saved with the project; touched only off the audio thread. |
kit_table |
none (not saved) | Arc<KitTable> |
The audio thread's lock-free copy of the pads, rebuilt from kit in initialize. See Kit Mode. |
Integer parameters map to enums with from_int / to_int. Out-of-range integers (a hand-edited preset) fall back to a default rather than failing the load.
| Parameter (ID) | Range | Mapping | Fallback |
|---|---|---|---|
Exciter (exciter) |
1..16 | 1 Bow, 2 Hand Strike, 3 Felt Mallet, 4 Hard Mallet, 5 Drumstick, 6 Wire Brush, 7 Metal Pipe, 8 Metal Chain, 9 Stiff Point Scrape, 10 Heavy Grinding, 11 Corrugated Drag, 12 Tension Rise, 13 Pneumatic Jet, 14 Electromagnetic Hum, 15 Tension Snap, 16 Particle Rain | Hand Strike (also the default) |
Object (object) |
0..8 | 0 Pipe, 1 Plate, 2 Tank, 3 Chain, 4 I-Beam, 5 Taut Cable, 6 Coil Spring, 7 Sheet Metal, 8 Industrial Cog | Pipe |
Note Mode (play_mode, enum PlayMode) |
0..2 | 0 Tonal, 1 Kit, 2 Drone | Tonal |
Quality Mode (quality_mode) |
0..3 | 0 Eco, 1 Normal, 2 High, 3 Render | Normal |
Limiter Mode (limiter_mode) |
0..1 | 0 Hard, 1 Lookahead | Hard |
Space Mode (space_mode) |
0..3 | 0 Off, 1 Factory, 2 Spring, 3 Echo (mapped in apply_post_chain_params) |
Off |
Loop Mode (loop_mode) |
0..2 | 0 Off, 1 Forward, 2 PingPong | Off |
UI Scale (ui_scale) |
0..20 |
UI_SCALE_CHOICES: indices are stable, not in size order (0 = 50 %, 1 = 75 %, 2 = 100 %, 3 = 125 %, 4 = 150 %, 5–8 = 80–95 %, 9–20 the other 5 % steps) |
shown as 100 % |
-
ExciterType::family()groups the exciters: Hit (2–8), Friction (1, 9–12), Specialty (13–16). The family picks the force envelope. - The exciter IDs are not in the editor's order:
exciter_model_items()lists Hand Strike first and Bow after Metal Chain. IDs are what presets and projects store; never renumber them. - Drone mode forces the MSEG to loop stages 3 → 4 (Forward) at note-on, so friction exciters sustain; other families are unchanged.
Ranges and defaults as the code builds them (the user Wiki's web/guide/src/data/parameters.json, written by export_guide_data, holds the same data and is checked against the code). "When" uses the classes above: B = every block on all sound, H = held voices, N = note-on.
Master and modes
| ID | Name | Range | Default | When |
|---|---|---|---|---|
exciter |
Exciter | 1..16 | 2 (Hand Strike) | N |
object |
Object | 0..8 | 0 (Pipe) | N |
quality_mode |
Quality Mode | 0..3 | 1 (Normal) | B and N |
play_mode |
Note Mode | 0..2 | 0 (Tonal) | N |
limiter_mode |
Limiter Mode | 0..1 | 0 (Hard) | B |
size |
Size | 0.05..10 | 1 | N |
rust |
Rust | 0..5 | 0 | N |
damage |
Damage | 0..10 | 0 | N |
drive |
Drive | 0..5 | 0 | B |
output |
Output | 0..+40 dB | 0 dB | B |
width |
Width | −2..3 | 0.5 | B |
body |
Body | 0..5 | 2.62 | B |
ui_scale |
UI Scale | 0..20 | 1 (75 %) | editor |
macro_mass, macro_corrosion, macro_violence, macro_brightness
|
Mass, Corrosion, Violence, Macro Brightness | 0..1 | 0.5 | see the macro table |
Envelopes and gesture
| ID | Name | Range | Default |
|---|---|---|---|
env_attack |
Attack | 0.001..2 s | 0.05 |
env_decay |
Decay | 0.01..5 s | 0.3 |
env_sustain |
Sustain | 0..1 | 0.7 |
env_release |
Release | 0.01..5 s | 0.5 |
mseg_onset |
Onset Time | 0.001..1 s | 0.01 |
mseg_onset_level |
Onset Level | 0..1 | 0.01 |
mseg_attack |
MSEG Attack | 0.001..2 s | 0.05 |
mseg_hold |
Hold | 0..2 s | 0.02 |
mseg_decay |
MSEG Decay | 0.01..5 s | 0.3 |
mseg_sustain |
MSEG Sustain | 0..1 | 0.5 |
mseg_release |
MSEG Release | 0.01..5 s | 0.1 |
loop_mode, loop_start_stage, loop_end_stage
|
Loop Mode, Loop Start Stage, Loop End Stage | 0..2, 0..5, 0..5 | 0, 3, 4 |
env_amount |
Env Amount | 0..1 | 1 |
velocity_to_peak |
Velocity To Peak | 0..1 | 0.5 |
global_time_scale |
Global Time Scale | 0.1..10 | 1 |
velocity_to_level |
Velocity To Level | 0..1 | 1 |
velocity_to_time |
Velocity To Time | 0..1 | 0.15 |
curve_tension |
Curve Tension | −1..1 | 0 |
All are note-on.
Global exciter controls: exciter_pressure (0..1, default 0.5, H), exciter_speed (0..1, 0.5, N), exciter_roughness (0..1, 0.3, N). See Exciters.
Exciter model controls (all note-on; ranges in parameters.json):
| Exciter | Parameter IDs |
|---|---|
| Bow |
bow_pressure, bow_speed, rosin_grip, slip_curve
|
| Hand Strike |
hand_mass, flesh_stiffness, flesh_damping, mute_decay
|
| Felt Mallet |
mallet_mass, felt_softness, core_hardness, compression_curve
|
| Hard Mallet |
mallet_mass, material_stiffness, impact_damping
|
| Drumstick |
stick_mass, tip_stiffness, restitution_bounciness, micro_bounce_limit (rounded) |
| Wire Brush |
wire_density (rounded), spread_duration, brush_wire_stiffness, amplitude_randomization
|
| Metal Pipe |
pipe_mass, metal_stiffness, pipe_pitch, pipe_ring_decay
|
| Metal Chain |
link_count (rounded), chain_mass, drop_envelope_spread, internal_rattle, rattle_color
|
| Stiff Point Scrape |
scrape_speed, point_pressure, chatter_pitch, chatter_damping
|
| Heavy Grinding |
grind_speed, grind_pressure, surface_grit, grit_color
|
| Corrugated Drag |
drag_speed, ridge_spacing, ridge_depth, drag_exciter_mass
|
| Tension Rise |
pull_speed, break_threshold, slip_stochasticity, creak_sharpness
|
| Pneumatic Jet |
air_pressure, nozzle_width, turbulence_chaos
|
| Electromagnetic Hum |
mains_frequency, coil_proximity, voltage_sag
|
| Tension Snap |
pull_distance, hook_stiffness, snap_force
|
| Particle Rain |
flow_rate, particle_mass, mass_variance
|
mallet_mass is shared by both mallets. The rounded ones are float parameters turned into counts at note-on.
Resonator, materials and linkage
| ID | Range | Default | When |
|---|---|---|---|
res_damping (Damping) |
0..1 | 0.5 | H |
res_brightness (Resonator Brightness) |
0..1 | 0.5 | H |
thickness, heat, sludge
|
0..1 | 0.5, 0, 0 | N |
strike_position |
0..1 | 0.5 | H |
coupling_stiffness |
0..1 | 1 | H |
position_wander |
0..1 | 0 | H |
position_wander_rate |
0.1..5 Hz | 0.1 | H |
position_envelope |
0..1 | 0 | H |
fundamental_anchor |
0..1 | 0.3 | H |
pipe_diameter, tank_volume, chain_link_mass (0.1..1), beam_shear, spring_dispersion
|
0..1 | 0.5 | N |
plate_aspect (0.1..4), plate_stiffness (0.25..3) |
1, 1 | N | |
tank_cavity_mix, chain_instability, cable_braid, cable_tension_drop, spring_slosh, sheet_thinness, cog_dissonance
|
0..1 | 0.6, 0.3, 0.3, 0.4, 0.3, 0.4, 0.1 | N |
The character parameters reach the object's generator through CharacterParams (Objects).
Post chain (all B)
| ID | Range | Default |
|---|---|---|
filter_cutoff |
20..20 000 Hz | 20 000 |
filter_resonance, component_tolerance
|
0..1 | 0, 0 |
drive_amount |
0..5 | 0 |
bias_starvation, chaos_depth
|
0..1 | 0, 0 |
spread_width, listener_proximity
|
0..1 | 0.5, 0.5 |
chassis_material, chassis_volume
|
0..1 | 0.5, 0.5 |
space_mode |
0..3 | 0 |
space_amount |
0..1 | 0 |
factory_size, machinery_clutter, wall_impedance
|
0..1 | 0.5, 0.3, 0.5 |
spring_tension, wire_stiffness, spring_tank_size
|
0..1 | 0.5 each |
sync_rate |
0..1 | 0 (Off) |
delay_time, machinery_movement, high_frequency_damping
|
0..1 | 0.25, 0, 0.5 |
analog_ceiling |
0.5..1 | 0.9661 (≈ −0.3 dBFS) |
diode_softness, diode_asymmetry
|
0..1 | 0.5, 0.25 |
-
src/params.rs:CorrosionParams, the 149 constructors, the enums,SYNC_DIVISIONS,UI_SCALE_CHOICESand the display tests. -
src/lib.rs: where parameters are read (note_setup,begin_block,apply_post_chain_params) and the macro biases. -
src/presets/mod.rs:Preset::into_paramsandPresetParameters::apply_to, which build parameters with the same constructors. -
web/guide/src/data/parameters.json: the exported table of every parameter's range, default and help.
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