Repository navigation
Repository Layout
Corrosion is one Rust crate that builds a VST3 and CLAP plugin, five command-line tools, and (through a second Cargo workspace) a browser build. Around the crate sit the tests, benchmarks, scripts, the factory presets, the website and two sets of documents: the OpenSpec change records and this wiki. This page says where everything is and how the builds are wired, so the rest of the wiki can name files without explaining them.
flowchart LR
subgraph root["Root workspace: Cargo.toml"]
lib["corrosion crate<br/>src/lib.rs<br/>cdylib + rlib"]
bins["src/bin/*<br/>5 binaries"]
tests["tests/*.rs, benches/performance.rs"]
bins --> lib
tests --> lib
end
subgraph web["web/ workspace: web/Cargo.toml"]
engine["web/engine<br/>corrosion-web-engine<br/>feature web-host"]
editor["web/editor<br/>corrosion-web-editor<br/>feature web-gui"]
end
engine -->|"path = ../.."| lib
editor -->|"path = ../.."| lib
patch["web/vendor/nih-plug<br/>patched NIH-plug"] -.->|"[patch] only in web/"| engine
patch -.-> editor
The same structure as a list:
-
Root workspace (
Cargo.toml, lockfileCargo.lock). It has no[workspace]table, so it is a single-package workspace: thecorrosioncrate.- The library is built as
cdylib(the plugin binary a host loads) andrlib(what the binaries, integration tests, benchmarks and the web crates link against). - The five binaries in
src/bin/, the integration tests intests/and the Criterion benchmarkbenches/performance.rsall use therlib.
- The library is built as
-
Web workspace (
web/Cargo.toml, lockfileweb/Cargo.lock), membersengineandeditor.- Both members depend on the root crate by path (
corrosion = { path = "../.." }) withdefault-features = false. -
web/engineturns onweb-host;web/editorturns onweb-gui. - Its
[patch."https://github.com/robbert-vdh/nih-plug"]points NIH-plug atweb/vendor/nih-plug, a copy thatweb/scripts/fetch-nih-plug.shfetches at the revisionCargo.lockpins and patches withweb/nih-plug-public-setters.patch. That patch makes the parameter setters public, which the browser host needs. The plugin builds never see it, which is why the browser features only build insideweb/.
- Both members depend on the root crate by path (
Why two workspaces: a [patch] applies to a whole workspace. Keeping the patched NIH-plug in its own workspace means the shipped plugin is built against upstream NIH-plug, and the web build can still poke parameters directly. The Web App page covers the browser build itself.
Package. corrosion 0.2.0, edition 2021, GPL-3.0-or-later. The version is what the plugin reports to hosts (Plugin::VERSION is env!("CARGO_PKG_VERSION")).
Dependencies that matter for the build:
| Dependency | How it is used |
|---|---|
nih-plug (git, upstream) |
The plugin framework. Declared three times with target conditions: default features (VST3 wrapper) on every non-wasm target; default-features = false on wasm32 (no VST3, no host); and assert_process_allocs added on every target that is neither Windows nor wasm, which makes NIH-plug panic on an allocation inside process() in debug builds. |
nih_plug_egui (git, optional) |
The editor's window. default-features = false, features = ["opengl"], so egui's default fonts are not pulled in. |
egui =0.31.1 (optional) |
Plain egui for the browser editor, the version nih_plug_egui uses, without default fonts. |
rfd 0.18 (optional) |
Native file dialogs for preset Import and Export. xdg-portal on Linux, so the bundle links no GTK. |
clap 4 |
Argument parsing for the binaries in src/bin/. |
serde, serde_json
|
Presets, kits and the guide data. |
include_dir 0.7 |
Embeds presets/factory/ into the editor (src/gui/editor.rs). |
Features:
| Feature | Turns on | Meaning |
|---|---|---|
default |
gui |
A normal plugin build has an editor. |
gui |
nih_plug_egui, rfd
|
The egui editor in its own window, plus the file dialogs. CI's main test lane runs with --no-default-features, so it never compiles this. |
web-host |
nothing | The web module (src/web/): WebEngine, the command protocol. Builds only in web/. |
web-gui |
web-host, egui
|
src/gui/editor.rs compiled on plain egui, with no window of its own. Builds only in web/. |
Dev-dependencies: assert_no_alloc (git branch feature/nested-permit-forbid, the checking allocator behind tests/no_alloc.rs) and criterion 0.5 (the benchmark, declared with harness = false).
Profiles and patches:
-
[profile.test]setsopt-level = 1. Debug test runs render many seconds of audio; level 1 keeps debug assertions and overflow checks while cutting run time several-fold. -
[patch.crates-io]replacesnih_logwithvendor/nih_log, which drops the unmaintainedattycrate. -
[patch."https://github.com/BillyDM/egui-baseview.git"]replacesegui-baseviewwithvendor/egui-baseview, which removesdefault_fontsfrom its default features.nih_plug_eguiwould otherwise always turn that feature on, and a dependent crate can't turn off a transitive default feature.
There is no [profile.release] in the root manifest; release builds use Cargo's defaults. The web workspace sets its own (opt-level = 3, lto = true, codegen-units = 1, panic = "abort").
.cargo/config.toml is written for the maintainer's Windows machine:
[build]
target = "x86_64-pc-windows-gnu"
target-dir = "../corrosion-target"-
Default target. A bare
cargo buildorcargo teston Linux cross-compiles for Windows GNU and fails to link (or tries to run a.exe). On Linux, always set a host target:export CARGO_BUILD_TARGET=x86_64-unknown-linux-gnu. -
Output directory. Build output goes to
../corrosion-target, a sibling of the checkout, nottarget/. Paths in Cargo config are relative to the directory that holds.cargo/, so this is the same place whatever directory you run Cargo from.scripts/bundle.shlooks for the library there unlessCARGO_TARGET_DIRis set. -
Linkers.
x86_64-unknown-linux-musllinks withrust-lldand-C link-self-contained=yes(CI's test target);x86_64-unknown-linux-gnuwithgcc;x86_64-pc-windows-gnuwithx86_64-w64-mingw32-gcc. -
The web workspace inherits this file (Cargo reads config from parent directories) but overrides the output directory in
web/.cargo/config.toml(target-dir = "target", soweb/target/).web/scripts/build.shalways passes--target wasm32-unknown-unknown, so the Windows default never applies there.
The toolchain must be Rust 1.99 or newer: src/lib.rs allows the semicolon_in_expressions_from_non_local_macros lint on the module that expands NIH-plug's VST3 export, and older compilers reject that lint name under -D warnings. Building and Bundling has the full build recipe.
All five are thin command-line wrappers around library code, so tests can call the same code.
| Binary | Run as | What it does |
|---|---|---|
render |
cargo run --bin render -- --suite family|rust|damage|all|aliasing |
Deterministic offline comparison renders (offline::OfflineRenderer) into output/offline by default; --suite aliasing measures alias-like residual energy in the post chain. |
render_presets |
cargo run --release --bin render_presets |
Renders presets to stereo WAVs plus a manifest, through offline::render_preset, the plugin's own output path. |
seed_presets |
cargo run --release --bin seed_presets |
Levels the factory bank built in src/presets/factory/, writes presets/factory/ and src/presets/factory/levels.rs. See Factory Bank. |
export_guide_data |
cargo run --bin export_guide_data |
Writes the user Wiki's parameters.json and models.json from the parameters, control tables and models. |
render_guide_clips |
run by scripts/build-guide-clips.sh
|
Renders the user Wiki's audio clips and clips.json. See Site and User Wiki Tooling. |
src/lib.rs is the crate root: it declares the modules, holds the Corrosion plugin struct and its Plugin, ClapPlugin and Vst3Plugin impls, MIDI routing, the master drive and the output limiter. The modules:
| Path | Contents | Wiki page |
|---|---|---|
src/lib.rs |
Plugin struct, process_block, MIDI and CC routing, macros, master drive, host-state migrations, exports |
Plugin Lifecycle, Signal Chain |
src/params.rs |
CorrosionParams (149 parameters), one constructor per parameter, ExciterType, Object, PlayMode, QualityMode
|
Parameters |
src/voice/ |
Voice (one note) and VoiceManager (16-voice pool) |
Voices and Polyphony, Note Expression |
src/kit/ |
Kit mode's pads and the lock-free KitTable
|
Kit Mode |
src/gui_notes.rs |
Editor keyboard to audio thread: a lock-free note ring | Plugin Lifecycle |
src/dsp/ |
Everything that makes sound: exciters, resonators, profiles, envelopes, the interaction bus, transforms, the post chain, utilities | Modal Resonator, Exciters, Post Chain and the other Engine and Post chain pages |
src/gui/ |
The egui editor, control tables, palette, fonts, file dialogs | Editor |
src/presets/ |
Preset files, migrations, user presets, the factory bank in code | Presets and Migrations, Factory Bank |
src/offline/ |
Offline renderers that drive the real plugin | Testing |
src/guide/ |
The user Wiki's data exporter, clip plan, control-response measurement | Site and User Wiki Tooling |
src/randomizer/ |
Patch randomizer | Randomizer |
src/web/ |
Browser host (web-host / web-gui only) |
Web App |
src/bin/ |
The five binaries above | this page |
| Directory | What it holds |
|---|---|
src/ |
The crate (table above). |
tests/ |
Integration tests (no_alloc.rs, preset_roundtrip.rs, internals_wiki.rs, …), fixtures in tests/fixtures/ (the golden mode-bank hashes, the legacy preset corpus), and REAPER smoke scripts in tests/daw/. See Testing. |
benches/ |
performance.rs, the Criterion harness. See Benchmarks and Performance. |
scripts/ |
Bundling (bundle.sh, check_bundle.sh), validation (validate-plugins.sh), the local CI mirror (verify-local.sh), WAV checks, benchmark ratios, the third-party notices generator, the guide clip build and the wiki publisher. Old scripts live in scripts/archive/. |
web/ |
The web workspace (engine/, editor/), the page that hosts them (www/), the site's home and 404 (site/), shared design tokens (theme/), the user Wiki (guide/, an Astro Starlight project), build and test scripts (scripts/), the Cloudflare config (wrangler.toml) and the NIH-plug patch. dist/, target/ and vendor/ are build products, not in git. |
presets/ |
The factory bank on disk, presets/factory/<folder>/…, written by seed_presets and embedded into the editor. |
docs/ |
ARCHITECTURE.md (the as-built record), BACKLOG.md, PRD.md, REAPER_TESTING.md, the aspirational DSP notes in original-specs/, old reviews in archive/, and this wiki in internals/. |
openspec/ |
OpenSpec: specs/ holds the requirements of every archived change, changes/ the open changes and changes/archive/ the closed ones, each with its proposal, design (with measurements) and tasks. |
vendor/ |
Patched third-party crates used by both workspaces: nih_log and egui-baseview, each with a PATCHED.md. |
assets/ |
The editor's fonts (assets/fonts/: Inter, IBM Plex Sans, their licenses and a README). |
output/ |
Audition WAVs written by the renderers. Some are committed. |
.github/workflows/ |
ci.yml (checks, bundles, nightly, web, guide) and wiki.yml (publishes this wiki). See CI and Releases. |
.claude/, .opencode/
|
The OpenSpec skills and commands for coding assistants. |
Files at the root: README.md (the sound surface for users), CLAUDE.md (working rules for coding assistants and contributors), CONTRIBUTING.md, CODE_OF_CONDUCT.md, LICENSE (GPLv3), THIRD-PARTY-NOTICES.md (partly generated by scripts/third_party_notices.py) and the current code review.
-
Cargo.toml: the root package, its dependencies, features, test profile and patches. -
.cargo/config.toml: the Windows-GNU default target, the../corrosion-targetoutput directory and the per-target linkers. -
web/Cargo.toml: the web workspace and its NIH-plug patch (the Web App page covers it in full). -
src/lib.rs: the crate root and its module declarations. -
src: the crate's source. -
src/bin: the five binaries. -
tests: integration tests and fixtures. -
benches: the Criterion benchmark. -
scripts: build, check and publishing scripts. -
web: the browser build, the site and the user Wiki. -
presets: the factory bank on disk. -
docs: architecture record, backlog, specs and this wiki. -
openspec: change records and requirements. -
vendor: the patchednih_logandegui-baseview. -
assets: the editor's fonts. -
web/.cargo/config.toml: the web workspace's own output directory.
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