chore: release Quench 0.1.0 and Ballast 0.1.0

- Quench 0.1.0: first release.
- Ballast 0.1.0: first release.
- Mark both released in docs/ideas.md and add them to the release table.

.gitea/workflows/check.yml

@@ -22,7 +22,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        plugin: [rivet, patina, anvil, crucible, lathe, temper, weld, knurl, planish, braze]
+        plugin: [rivet, patina, anvil, crucible, lathe, temper, weld, knurl, planish, braze, quench, ballast]
     steps:
       - uses: https://github.com/actions/checkout@v4
         with:
@@ -64,6 +64,8 @@ jobs:
           cargo run --manifest-path tools/editor-check/Cargo.toml --locked -- target/editor/knurl.png --plugin knurl
           cargo run --manifest-path tools/editor-check/Cargo.toml --locked -- target/editor/planish.png --plugin planish
           cargo run --manifest-path tools/editor-check/Cargo.toml --locked -- target/editor/braze.png --plugin braze
+          cargo run --manifest-path tools/editor-check/Cargo.toml --locked -- target/editor/quench.png --plugin quench
+          cargo run --manifest-path tools/editor-check/Cargo.toml --locked -- target/editor/ballast.png --plugin ballast
       - uses: https://github.com/actions/upload-artifact@v3-node20
         with:
           name: editor-previews
@@ -97,6 +99,8 @@ jobs:
           python3 scripts/build-plugin.py --plugin knurl --target x86_64-pc-windows-gnu
           python3 scripts/build-plugin.py --plugin planish --target x86_64-pc-windows-gnu
           python3 scripts/build-plugin.py --plugin braze --target x86_64-pc-windows-gnu
+          python3 scripts/build-plugin.py --plugin quench --target x86_64-pc-windows-gnu
+          python3 scripts/build-plugin.py --plugin ballast --target x86_64-pc-windows-gnu
           python3 scripts/package-windows.py
       - uses: https://github.com/actions/upload-artifact@v3-node20
         with:

.gitea/workflows/release.yml

@@ -1,7 +1,7 @@
 name: Independent plugin release
 on:
   push:
-    tags: ["rivet-v*", "patina-v*", "anvil-v*", "crucible-v*", "lathe-v*", "temper-v*", "weld-v*", "knurl-v*", "planish-v*", "braze-v*"]
+    tags: ["rivet-v*", "patina-v*", "anvil-v*", "crucible-v*", "lathe-v*", "temper-v*", "weld-v*", "knurl-v*", "planish-v*", "braze-v*", "quench-v*", "ballast-v*"]
 
 permissions:
   contents: read

Cargo.lock

@@ -55,6 +55,25 @@ version = "1.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
 
+[[package]]
+name = "ballast-core"
+version = "0.1.0"
+dependencies = [
+ "common-dsp",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "ballast-ui"
+version = "0.1.0"
+dependencies = [
+ "ballast-core",
+ "common-dsp",
+ "common-ui",
+ "egui",
+]
+
 [[package]]
 name = "bitflags"
 version = "2.13.2"
@@ -389,6 +408,25 @@ version = "1.0.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3d595e54a326bc53c1c197b32d295e14b169e3cfeaa8dc82b529f947fba6bcf5"
 
+[[package]]
+name = "quench-core"
+version = "0.1.0"
+dependencies = [
+ "common-dsp",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "quench-ui"
+version = "0.1.0"
+dependencies = [
+ "common-dsp",
+ "common-ui",
+ "egui",
+ "quench-core",
+]
+
 [[package]]
 name = "quote"
 version = "1.0.47"

Cargo.toml

@@ -1,6 +1,6 @@
 [workspace]
 resolver = "2"
-members = ["plugins/common/ui", "plugins/common/dsp", "plugins/anvil/core", "plugins/anvil/ui", "plugins/lathe/core", "plugins/lathe/ui", "plugins/temper/core", "plugins/temper/ui", "plugins/weld/core", "plugins/weld/ui", "plugins/knurl/core", "plugins/knurl/ui", "plugins/planish/core", "plugins/planish/ui", "plugins/braze/core", "plugins/braze/ui", "plugins/crucible/core", "plugins/crucible/ui", "plugins/rivet/core", "plugins/rivet/midi", "plugins/rivet/preview", "plugins/rivet/app", "plugins/patina/core", "plugins/patina/render", "plugins/patina/ui"]
+members = ["plugins/common/ui", "plugins/common/dsp", "plugins/anvil/core", "plugins/anvil/ui", "plugins/lathe/core", "plugins/lathe/ui", "plugins/temper/core", "plugins/temper/ui", "plugins/weld/core", "plugins/weld/ui", "plugins/knurl/core", "plugins/knurl/ui", "plugins/planish/core", "plugins/planish/ui", "plugins/braze/core", "plugins/braze/ui", "plugins/quench/core", "plugins/quench/ui", "plugins/ballast/core", "plugins/ballast/ui", "plugins/crucible/core", "plugins/crucible/ui", "plugins/rivet/core", "plugins/rivet/midi", "plugins/rivet/preview", "plugins/rivet/app", "plugins/patina/core", "plugins/patina/render", "plugins/patina/ui"]
 exclude = ["plugins/rivet/plugin", "tools/editor-check", "plugins/patina/plugin", "plugins/anvil/plugin", "plugins/crucible/plugin", "plugins/lathe/plugin", "plugins/temper/plugin", "plugins/weld/plugin", "plugins/knurl/plugin", "plugins/planish/plugin"]
 
 [workspace.package]
@@ -31,3 +31,7 @@ opt-level = 2
 
 [profile.dev.package.weld-core]
 opt-level = 2
+[profile.dev.package.quench-core]
+opt-level = 2
+[profile.dev.package.ballast-core]
+opt-level = 2

README.md

@@ -30,9 +30,11 @@ note. Each plugin is a separate product with its own version, guide and release.
 | **[Knurl](docs/knurl/README.md)** | Gives every cycle of the note its own level, timing and grit: in-tune subharmonic growl, rattle and fry on every note | Bass | ≈ 71 ms | [Guide](docs/knurl/README.md) · [Changes](docs/knurl/CHANGELOG.md) |
 | **[Planish](docs/planish/README.md)** | Upward and downward compression (OTT) in bands set by harmonic number: band 2 holds harmonics 2–4 on every note | Bass | ≈ 67 ms | [Guide](docs/planish/README.md) · [Changes](docs/planish/CHANGELOG.md) |
 | **[Braze](docs/braze/README.md)** | Adds a detuned copy whose beating stays on the tempo grid on every note: reese movement in time | Bass | ≈ 67 ms | [Guide](docs/braze/README.md) · [Changes](docs/braze/CHANGELOG.md) |
+| **[Quench](docs/quench/README.md)** | Clips the top as hard as you like while the sub passes clean: the low end keeps its level under a loud master | Master or bass bus, last | < 1 ms (oversampling) | [Guide](docs/quench/README.md) · [Changes](docs/quench/CHANGELOG.md) |
+| **[Ballast](docs/ballast/README.md)** | Levels every note or switch-up to one loudness with a single gain each: no compression inside a part | Bass, after the sound design | ≈ 172 ms | [Guide](docs/ballast/README.md) · [Changes](docs/ballast/CHANGELOG.md) |
 
 Plugins with latency report it to the host, so FL Studio compensates the delay.
-Anvil, Lathe, Temper, Knurl, Planish and Braze detect pitch from the audio. They can also take the
+Anvil, Lathe, Temper, Knurl, Planish, Braze and Ballast detect notes from the audio. They can also take the
 pitch from MIDI. The order of the plugins matters: see [Signal chain](docs/chain.md).
 
 The names come from metalwork: a **rivet** joins pieces; **patina** changes a
@@ -41,7 +43,8 @@ is struck on; a **crucible** melts material down to be cast again; a **lathe**
 turns a piece so each cut lands the same all the way round; **tempering** sets
 how hard and how tough a metal ends up; a **weld** fuses two pieces into one;
 **knurling** presses a ridged grip pattern into a surface; **planishing**
-hammers a surface smooth and even; **brazing** joins two metals with a filler.
+hammers a surface smooth and even; **brazing** joins two metals with a filler; **quenching** hardens hot metal in one
+fast step; **ballast** is the weight that keeps a ship level.
 The suite is the **foundry**: the workshop where the bass gets cast, shaped and
 finished. Hosts list the plugins under the vendor name *Bass Foundry*.
 
@@ -68,6 +71,10 @@ finished. Hosts list the plugins under the vendor name *Bass Foundry*.
     <td><a href="docs/planish/README.md"><img src="docs/planish/assets/editor.png" alt="Planish editor"></a><br><b>Planish</b>: harmonic OTT</td>
     <td><a href="docs/braze/README.md"><img src="docs/braze/assets/editor.png" alt="Braze editor"></a><br><b>Braze</b>: tempo-locked beating</td>
   </tr>
+  <tr>
+    <td><a href="docs/quench/README.md"><img src="docs/quench/assets/editor.png" alt="Quench editor"></a><br><b>Quench</b>: sub-safe clipper</td>
+    <td><a href="docs/ballast/README.md"><img src="docs/ballast/assets/editor.png" alt="Ballast editor"></a><br><b>Ballast</b>: switch-up leveller</td>
+  </tr>
 </table>
 
 The previews are rendered headless from the real editor code by
@@ -126,7 +133,7 @@ cargo run --manifest-path tools/editor-check/Cargo.toml -- target/editor/lathe.p
 ```
 
 Plugin names for the scripts are `rivet`, `patina`, `anvil`, `crucible`,
-`lathe`, `temper`, `weld`, `knurl`, `planish` and `braze`. Builds go to `dist/<target>/<Name>.clap`. No
+`lathe`, `temper`, `weld`, `knurl`, `planish`, `braze`, `quench` and `ballast`. Builds go to `dist/<target>/<Name>.clap`. No
 script installs anything into a DAW. [Development and testing](docs/development.md)
 has the full command list.
 
@@ -166,6 +173,8 @@ plugins/
   knurl/               core · ui · plugin
   planish/             core · ui · plugin
   braze/               core · ui · plugin
+  quench/              core · ui · plugin
+  ballast/             core · ui · plugin
   common/
     ui/                Shared look: palette, embedded fonts, knobs, panels, meters
     dsp/               Shared filters, pitch tracking, oversampling, meters, WAV files

docs/ballast/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Ballast changelog
+
+## 0.1.0
+
+- Introduce Ballast, a switch-up leveller: every part of a bassline gets one
+  gain that brings it to the Target loudness. No compression inside a part.
+- Parts start at note starts (detected from the audio, or from MIDI) or on the
+  host's beat grid, from 1 bar to 1/16.
+- Loudness is K-weighted (ITU-R BS.1770) over each part's first 100 ms, in
+  10 ms blocks with a relative gate, and each part is weighted from rest.
+- The gain glides over 5 ms and is in place on the part's first sample.
+- **Learn** takes the next part's loudness as the target. **Amount**,
+  **Range**, **Measure from** (leave the sub out of the measurement), **Gate**,
+  **Output**, **Bypass**.
+- Editor: the last 32 parts, their loudness in and out, the target, and the
+  spread of the last 16 parts.
+- About 172 ms of latency: the tracker's lookahead, the window and the glide.

docs/ballast/README.md

@@ -0,0 +1,80 @@
+# Ballast
+
+Ballast levels every note or switch-up of a bassline to one loudness, with a
+single gain for each. Current version **0.1.0**.
+
+Riddim and dubstep basslines change patch every few beats. Patches at the same
+peak level still differ in how loud they sound, so each switch-up lands at a
+different loudness and gets hand-set gain or clipping. A compressor would even
+them out but also change their envelope and punch. Ballast measures each part's
+loudness and gives the whole part one gain: inside a part nothing moves.
+
+![Ballast](assets/editor.png)
+
+## Install on Windows
+
+Copy `Ballast.clap` into `C:\Program Files\Common Files\CLAP\`. In FL Studio
+2024.1 or newer, open Options → Manage plugins, enable Verify plugins, and Find
+installed plugins. Load Ballast in the mixer slot of the bass, after its sound
+design. Keep the font license with redistributed packages.
+
+## Work with it
+
+1. Choose where a part starts with **Parts from**:
+   - **Notes**: every note start, detected from the audio, or from MIDI notes
+     sent to the effect (**Notes from**: AUDIO or MIDI).
+   - **Grid**: every line of the host's beat grid, from 1 bar to 1/16. Use it
+     when a switch-up changes the patch on the same note: the note tracker does
+     not see a new note there.
+2. Play the bassline and press **LEARN** just before the switch-up that sits
+   right in the mix. Its loudness becomes the **Target**. You can also set
+   Target by hand.
+3. Watch the display: one bar per part with its loudness as it came in, and a
+   mark where Ballast puts it. The marks line up on the target line.
+4. Lower **Amount** to keep some of the differences: 50 % halves them.
+
+The panel shows the spread of the last 16 parts, in and out: the standard
+deviation of their loudness in dB. In the editor preview four patches spread
+by 7 dB come out within 0.4 dB; the rest is what Range left.
+
+Other controls:
+
+- **Range** is the most boost or cut a part gets.
+- **Measure from**: the measurement hears only what is above this frequency;
+  the gain still applies to the whole signal. When Anvil makes the sub on the
+  bus, set it to Anvil's Split: Anvil replaces the sub anyway, so only the part
+  above it should decide the gain.
+- **Gate** is the note-start threshold (Audio). A part quieter than the gate
+  keeps the last part's gain instead of being lifted, so rests and tails are
+  not pulled up.
+- **Output** trims the level; **Bypass** crossfades to the delayed input.
+
+### How it measures
+
+A part's loudness is its K-weighted level (ITU-R BS.1770, the weighting behind
+LUFS) over its first 100 ms, or over all of it when it is shorter. The level is
+counted in 10 ms blocks, and blocks 20 dB under the part's loudest block are
+left out. Each part is weighted from rest, as if it played alone, so the last
+part's level does not ring into it.
+
+The gain glides to the new value over 5 ms and is in place on the part's first
+sample, so the attack already has the new level. Later parts of a long note keep
+that gain: Ballast does not follow the note's envelope.
+
+## Timing and limits
+
+Latency is the note tracker's lookahead (about 67 ms), the 100 ms measuring
+window and the 5 ms glide, about 172 ms in all, reported to the host for delay
+compensation. That is too much for playing live through Ballast: add it for the
+mix.
+
+In Grid mode the grid follows the host's beat position while it plays and runs
+on at the last tempo when it stops. A note start found by a change of pitch can
+come about 20 ms early, inside the gap before the note;
+the block gate keeps that gap out of the measurement. Two parts closer than
+10 ms are merged.
+
+Ballast decides from the first 100 ms of a part. A patch that swells after
+that, or a note whose loudness depends on what plays with it, is levelled by
+its start only. It levels loudness, not brightness: two patches at the same
+loudness can still differ in tone.

docs/chain.md

@@ -1,14 +1,15 @@
 # Signal chain
 
 The order of the Bass Foundry plugins in a chain matters. Anvil, Lathe, Temper,
-Knurl, Planish and Braze each detect the pitch from the audio they receive. If a plugin earlier
+Knurl, Planish, Braze and Ballast each detect the pitch from the audio they receive. If a plugin earlier
 in the chain changes the audio, the pitch detection after it can go wrong.
 
 ## Recommended order
 
 ```text
-bass track:   synth → Lathe → Temper → Planish → Braze → Knurl → Patina → Weld
-bass bus:     Anvil → (bus compression, clipping) → Crucible
+bass track:   synth → Lathe → Temper → Planish → Braze → Knurl → Patina → Ballast → Weld
+bass bus:     Anvil → (bus compression) → Quench → Crucible
+master:       … → Quench (last, or before a true-peak limiter)
 ```
 
 - **Lathe and Temper before Knurl.** They hear the plain synth, where the pitch
@@ -22,7 +23,12 @@ bass bus:     Anvil → (bus compression, clipping) → Crucible
   it reads Loose, move Braze to the bus after Anvil, with Low cut at or above
   Anvil's Split. There it reads the pitch from Anvil's clean sub, and the sub
   stays out of the beating.
-- **Knurl last among the tracked plugins.** See below.
+- **Ballast after the sound design.** It levels what the patch finally sounds
+  like, so it comes after the distortion, OTT and Patina. It finds note starts
+  like the other tracked plugins: after Knurl, use MIDI or Grid. Weld and Anvil
+  come after it. On the bus with Anvil, set Measure from to Anvil's Split.
+- **Knurl last among the pitch-tracked plugins.** See below. Ballast only
+  needs note starts; after Knurl, run it from MIDI or the grid.
 - **Patina after the tracked plugins.** It does not detect pitch, so the order
   does not change its result.
 - **Weld after every plugin with latency on its track.** Weld can delay its own
@@ -31,6 +37,10 @@ bass bus:     Anvil → (bus compression, clipping) → Crucible
   that layer late.
 - **Anvil on the bus, in MIDI mode when Knurl is in the chain.** For Kick
   lock, send the kick's track to Anvil as a sidechain.
+- **Quench last on the bus or the master.** It clips the top and leaves the sub
+  alone, so put it where you would put a clipper. On the bass bus after Anvil,
+  set its Split at or a little above Anvil's Split: Anvil's sub then passes
+  Quench untouched. Quench does not detect pitch, so it can sit after Knurl.
 - **Crucible at the end of the chain you want to resample.**
 
 ## Knurl and pitch detection
@@ -53,7 +63,8 @@ and route the bass's MIDI notes to it.
 ## Latency
 
 Each tracked plugin adds its own lookahead: Anvil 80 ms, Lathe, Temper,
-Planish and Braze about 67 ms, Knurl about 71 ms, Patina about 45 ms. A full chain is
+Planish and Braze about 67 ms, Knurl about 71 ms, Patina about 45 ms, Ballast
+about 172 ms, Quench under 1 ms. A full chain is
 about 400 ms. FL
 Studio compensates this for playback and rendering, but playing a MIDI keyboard
 through the full chain is not practical. Write with a shorter chain and add the

docs/development.md

@@ -25,7 +25,8 @@ Patina has `render` for offline WAV evaluation. The shared crates are:
 
 - `common-ui`: palette, embedded fonts, header, panels, knobs, meters.
 - `common-dsp`: filters, YIN pitch tracking, the note tracker used by Anvil,
-  Lathe, Temper, Knurl, Planish and Braze, 4× oversampling, meters and WAV files.
+  Lathe, Temper, Knurl, Planish, Braze and Ballast, 4× oversampling (also Quench's),
+  BS.1770 K-weighting (Ballast), meters and WAV files.
 
 The wrappers stay separate workspaces, each with its own lockfile, so the
 NIH-plug Git dependency stays out of the root workspace. Host identities and
@@ -45,7 +46,7 @@ python3 -m unittest discover -s scripts/tests -v
 ```
 
 Products: `rivet`, `patina`, `anvil`, `crucible`, `lathe`, `temper`, `weld`,
-`knurl`, `planish`, `braze`.
+`knurl`, `planish`, `braze`, `quench`, `ballast`.
 
 `check-plugin.py` runs formatting, tests and clippy for one product's packages
 and its wrapper, without compiling the other products. Run it for every product
@@ -146,6 +147,8 @@ identify plugins by CLAP ID, so the vendor name does not affect saved projects.
 | Knurl | (new) | `io.narl.bass-foundry.knurl` |
 | Planish | (new) | `io.narl.bass-foundry.planish` |
 | Braze | (new) | `io.narl.bass-foundry.braze` |
+| Quench | (new) | `io.narl.bass-foundry.quench` |
+| Ballast | (new) | `io.narl.bass-foundry.ballast` |
 
 CLAP IDs use the form `io.narl.bass-foundry.<product>`. Builds tagged before
 this scheme used `io.storyboard.*` IDs; hosts treat the new IDs as different

docs/ideas.md

@@ -263,8 +263,8 @@ one period of the note, so heavy settings do not ripple at f0. See [Planish](pla
    Patina already cut fixed formants on every note, but it also cut a boosted
    harmonic as hard (5.7 dB), at a position that moved with the note.
    Open: MIDI as the pitch source.
-3. Planish (done, released 0.1.0), then Quench and Ballast: they fill the mix
-   and master gap.
+3. Planish (done, released 0.1.0), then Quench and Ballast (both done,
+   released 0.1.0): they fill the mix and master gap.
    - In parallel, from the research findings, in this order: Weld delay
      spread (done, Weld 0.3.0); the fatness lane, as the first Assay piece
      (prototype `scripts/fatness.py`); Anvil Ghost harmonics and Phone listen
@@ -328,6 +328,29 @@ Quenching hardens hot metal in one fast step. Quench clips only above a split
 frequency and adds the clean sub back with its own headroom, so the master can
 be clipped hard without distorting the low end. Pairs with Anvil's split.
 
+Built (released 0.1.0, see [Quench](quench/README.md)). Design checks, made
+in a prototype before the plugin:
+
+- Splitting and giving the top the instantaneous room, clamp(top, −C − sub,
+  C − sub), is exactly a plain clip of the sum: the error is the same signal.
+  The sub-safe part has to come from somewhere else.
+- Feeding the clip error back through 1 − lowpass diverges: the complement of
+  an LR4 lowpass peaks at 1.5× near the split.
+- What works: clip the top symmetrically at the ceiling minus the sub's held
+  peak (no pumping at the sub's rate, the sum stays under the ceiling), then
+  high-pass the clip error at the split so its products below the split go.
+  Two clip-and-high-pass passes and an oversampled hard clip hold the ceiling.
+  Measured: sub level +0.04 dB against −2.2 dB for a plain clip; low-band
+  products −35 dB against −16 dB. Cost: 0.5–1.2 dB less RMS at the same
+  ceiling.
+- Where it does not help: a top whose fundamental lies within an octave of the
+  split is partly in the sub band (saw at 98 Hz over a 49 Hz sub: about the same
+  as a plain clip).
+- Next ideas: link the channels' sub peak and offer mono below the split
+  (with Gauge); give the top the room on the sub's far side too (asymmetric)
+  with the error still high-passed, and measure whether that wins back the
+  loudness without pumping; a true-peak ceiling.
+
 ### Scribe — audio to MIDI (problem 18)
 
 A scribe marks lines on metal. Scribe runs the note tracker on a bass and
@@ -353,6 +376,21 @@ the same loudness without compression changing its character. Earlier working
 name: Hit Leveler. Pairs with Anvil: Anvil levels the sub, Ballast the whole
 patch.
 
+Built (released 0.1.0, see [Ballast](ballast/README.md)): one gain per part,
+parts from note starts or the host grid (a patch change on the same note is not
+a new note to the tracker), K-weighted loudness of the first 100 ms, Learn for
+the reference. Found while building it:
+
+- A note start from a pitch change comes about 20 ms early, in the gap before
+  the note; a plain mean over the window then reads the part ~0.9 dB quiet.
+  Fixed with 10 ms blocks and a relative gate (−20 dB under the loudest block).
+- The K-weighting filters ring the last part into the next one: a near-silent
+  part after a loud one read −18 LUFS instead of under −60. Fixed by weighting
+  every part from rest.
+- Next ideas: a brightness match next to loudness (problem 2 names both; with
+  Lathe or Patina doing the EQ), a "follow" option for long notes that swell,
+  and switch-up detection from timbre change instead of the grid.
+
 ### Bellows — pitch-tracked resonator
 
 A comb or Karplus-style resonator tuned to the detected note. It turns noise,

docs/quench/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Quench changelog
+
+## 0.1.0
+
+- Introduce Quench, a clipper that clips the top and lets the sub pass clean.
+- A Linkwitz–Riley split at **Split** (40–300 Hz). The top is clipped at the
+  ceiling minus the sub's held peak; **Hold** sets how long that peak holds.
+- What the clip removes is high-passed at Split, so its products stay out of
+  the low band. Two correction passes and an oversampled hard clip hold the
+  ceiling; a safety clip catches the downsampler's ringing.
+- **Drive**, **Ceiling**, **Soft** (knee of the top's clip), **Bypass**.
+- Listen to **Quench**, a **Plain** clipper at the same settings, or the
+  **Delta** that Quench takes away. Not saved.
+- Editor: how much the low band changed for Quench and for a plain clip, how
+  far the top is clipped, the sub's peak and the room it leaves, and a scope.
+- 4× oversampling; 37 samples of latency.

docs/quench/README.md

@@ -0,0 +1,104 @@
+# Quench
+
+Quench clips the top of the mix as hard as you like and lets the sub pass clean.
+Current version **0.1.0**.
+
+Riddim and dubstep masters are clipped hard. A plain clipper clips the sum of
+the sub and everything above it. Near the sub's peaks only one side of the top
+gets clipped, so the clipping takes energy out at the sub's rate: the sub loses
+level, and the low end fills with products that were not in the mix. Quench
+splits the signal at a frequency you set, never clips the sub, and clips only
+the top, in the room the sub leaves under the ceiling.
+
+![Quench](assets/editor.png)
+
+## Install on Windows
+
+Copy `Quench.clap` into `C:\Program Files\Common Files\CLAP\`. In FL Studio
+2024.1 or newer, open Options → Manage plugins, enable Verify plugins, and Find
+installed plugins. Load Quench last on the master or on the bass bus. Keep the
+font license with redistributed packages.
+
+## Work with it
+
+1. Put Quench where you would put a clipper: last on the master, or last on
+   the bass bus. Before a true-peak limiter is fine.
+2. Set **Ceiling**, the highest output peak.
+3. Set **Split** above the highest sub note, or at Anvil's Split when Anvil
+   makes the sub. Everything below Split passes without clipping.
+4. Raise **Drive** until the top clips as hard as you want. The panel shows
+   how far the top is clipped.
+5. Press **PLAIN** to hear a plain clipper at the same settings, then
+   **QUENCH** again. **DELTA** plays only what Quench takes away. The listen
+   choice is not saved and goes back to QUENCH when the editor closes.
+
+The panel shows:
+
+- **Low end changed by**: how much the band below Split differs from the
+  input, against the sub's level, for Quench and for a plain clip of the same
+  signal. Lower is cleaner. It reads "—" when no sub plays.
+- **Top clipped by**: how far the top's loudest peak went past its room.
+- **Sub peak · room left**: the sub's peak after Drive and the room it leaves
+  the top under the ceiling.
+- The scope: the output (grey), the sub band (blue), and the sub plus or minus
+  the top's room (thin lines). The output stays between the thin lines.
+
+Other controls:
+
+- **Hold** keeps the room the sub's peak needs for this long. With a hold
+  longer than half a period of the lowest note (17 ms at 30 Hz), the top's
+  clip level stays steady through the sub's cycle and the top does not pump
+  with the sub. Shorter holds give the top a little more room between sub
+  peaks, and that room then changes at the sub's rate.
+- **Soft** bends the top's clip: 0 % is a hard clip, 100 % a soft curve from
+  the start. The ceiling stays a hard limit.
+- **Bypass** crossfades to the input, delayed by the latency.
+
+When the sub alone reaches the ceiling, the top has no room left. The panel
+then warns: lower Drive or the sub. A safety clip still holds the ceiling, and
+that clip does cut the sub.
+
+### How it works
+
+A Linkwitz–Riley crossover splits the signal at Split. The sub passes. The top
+is clipped symmetrically at the ceiling minus the sub's held peak, so the sum
+of sub and top never goes over the ceiling.
+
+Clipping the top also makes products below Split, for example difference
+tones between its partials. Quench high-passes what the clip removed at Split,
+so those products do not reach the low band. High-passing lets a few peaks
+overshoot. Two correction passes clip those again and high-pass the correction,
+and a final hard clip at the ceiling takes the small rest. All of this runs at
+4× oversampling. A safety clip after the downsampler catches the filters'
+ringing; it reads "idle" or a few hundredths of a dB.
+
+Measured on a 50 Hz sub at −10.5 dBFS under a top of five unrelated partials
+peaking about 6 dB over the ceiling:
+
+| | Sub level | Low-band products |
+| --- | --- | --- |
+| Plain clip | −2.2 dB | −16 dB |
+| Quench | +0.04 dB | −35 dB |
+
+Low-band products are everything below 110 Hz except the sub, against the
+sub's level.
+
+Quench pays for this in loudness. The top gets the room on the sub's quieter
+side only, so at the same ceiling Quench measured 0.5–1.2 dB lower in RMS
+than a plain clip. Add Drive to make up for it.
+
+## Timing and limits
+
+Latency is the oversampling filters: 37 samples (0.8 ms at 48 kHz), reported
+to the host for delay compensation.
+
+The split is a slope, not a wall. A top whose own fundamental lies near
+Split, for example a distorted patch an octave above a 49 Hz sub, is partly in
+the sub band. That part passes unclipped and takes up room, and Quench helps
+less there: on a saw top at 98 Hz it changed the low end about as much as a
+plain clip. Keep the top's lowest partial at least an octave above Split.
+
+Quench keeps the ceiling on sample peaks. True peaks between samples can
+still go a little over it: put a true-peak limiter after Quench if the master
+needs one. Each channel is clipped on its own; Quench does not link the
+channels or turn the sub to mono.

docs/releases.md

@@ -17,6 +17,8 @@ workflows are in `.gitea/workflows/`. A plugin's version is the `version` in
 | Knurl | `knurl-v0.2.0` | `knurl-windows-x86_64-0.2.0.zip` |
 | Planish | `planish-v0.1.0` | `planish-windows-x86_64-0.1.0.zip` |
 | Braze | `braze-v0.1.0` | `braze-windows-x86_64-0.1.0.zip` |
+| Quench | `quench-v0.1.0` | `quench-windows-x86_64-0.1.0.zip` |
+| Ballast | `ballast-v0.1.0` | `ballast-windows-x86_64-0.1.0.zip` |
 
 ## Make a release
 

plugins/ballast/core/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "ballast-core"
+version = "0.1.0"
+edition.workspace = true
+license.workspace = true
+
+[dependencies]
+common-dsp = { path = "../../common/dsp" }
+serde = { workspace = true }
+
+[dev-dependencies]
+serde_json = { workspace = true }

plugins/ballast/core/src/lib.rs

@@ -0,0 +1,474 @@
+//! Levels each part of a bassline, a note or a step of the beat grid, to one loudness with a
+//! single gain per part. No compression: the gain does not move inside a part, so a patch
+//! keeps its own envelope and punch.
+//!
+//! A part's loudness is the K-weighted (ITU-R BS.1770) mean square of its first 100 ms, or
+//! of all of it when it is shorter, counted in 10 ms blocks; blocks 20 dB under the loudest
+//! one are left out, so a gap at the start does not pull the reading down. Each part is
+//! weighted from rest, as if it played alone. The audio path is delayed by the note tracker's lookahead
+//! plus that window plus a 5 ms ramp, so every part's gain is known before its attack leaves
+//! the plugin, and the ramp to it ends exactly on the attack.
+mod settings;
+use common_dsp::loudness::{lufs, KWeighting};
+use common_dsp::svf::{Svf, SvfCoef};
+use common_dsp::tracker::{NoteEvent, Tracker, TrackerConfig};
+use common_dsp::{coefficient, db_to_gain, gain_to_db};
+pub use settings::{
+    Grid, Segment, Settings, Source, FROM_MAX, FROM_MIN, RANGE_MAX, TARGET_MAX, TARGET_MIN,
+};
+
+/// Each part is measured over this much of its start.
+pub const WINDOW_MS: f32 = 100.;
+/// The gain glides to a new part's value over this long, ending on its first sample.
+pub const RAMP_MS: f32 = 5.;
+/// A boundary closer than this to the last one is ignored: the parts are merged.
+const MIN_PART_MS: f32 = 10.;
+/// The window is measured in blocks of this length.
+const BLOCK_MS: f32 = 10.;
+const BLOCKS: usize = (WINDOW_MS / BLOCK_MS) as usize;
+/// Blocks this far under the part's loudest block do not count: a note start found by a
+/// pitch change can come early, inside the gap before the note.
+const RELATIVE_GATE_DB: f64 = 20.;
+/// Parts shown in the editor.
+pub const HISTORY: usize = 32;
+/// Parts used for the spread readout.
+const SPREAD: usize = 16;
+const PENDING: usize = 32;
+const Q: f32 = std::f32::consts::FRAC_1_SQRT_2;
+/// Tempo the grid runs at before the host reports one.
+const FALLBACK_BPM: f64 = 120.;
+
+#[derive(Clone, Copy, Debug, Default, PartialEq)]
+pub struct Part {
+    /// Loudness of the part's measured start, in LUFS.
+    pub loudness: f32,
+    /// Gain given to the part, in dB.
+    pub gain: f32,
+    /// Under the gate: the part kept the previous gain.
+    pub gated: bool,
+}
+
+#[derive(Clone, Copy, Debug)]
+pub struct AnalyzerFrame {
+    /// Latest parts, oldest first; the first `count` entries are valid.
+    pub history: [Part; HISTORY],
+    pub count: usize,
+    /// Gain applied at the output right now, in dB.
+    pub gain: f32,
+    /// Standard deviation of the loudness of the last 16 parts over the gate, before and after
+    /// Ballast. NaN with fewer than two.
+    pub spread_in: f32,
+    pub spread_out: f32,
+    /// Waiting for the next part to take as the target.
+    pub learning: bool,
+    /// The loudness last taken by Learn, and a number that changes each time one is taken.
+    pub learned: f32,
+    pub learn_id: u32,
+    pub tempo: f64,
+    pub synced: bool,
+    pub latency: u32,
+    pub sample_rate: f32,
+}
+impl Default for AnalyzerFrame {
+    fn default() -> Self {
+        Self {
+            history: [Part::default(); HISTORY],
+            count: 0,
+            gain: 0.,
+            spread_in: f32::NAN,
+            spread_out: f32::NAN,
+            learning: false,
+            learned: f32::NAN,
+            learn_id: 0,
+            tempo: FALLBACK_BPM,
+            synced: false,
+            latency: 0,
+            sample_rate: 48000.,
+        }
+    }
+}
+
+/// Gain in dB that brings `loudness` to the target, at `amount` (0–1), within ±`range`.
+pub fn part_gain(loudness: f32, target: f32, amount: f32, range: f32) -> f32 {
+    ((target - loudness) * amount).clamp(-range, range)
+}
+
+#[derive(Clone, Copy, Default)]
+struct Pending {
+    start: u64,
+    gain: f32,
+}
+
+pub struct Engine {
+    rate: f32,
+    channels: usize,
+    settings: Settings,
+    tracker: Tracker,
+    lookahead: usize,
+    window: usize,
+    ramp: usize,
+    min_part: usize,
+    delay: Vec<[f32; 2]>,
+    delay_at: usize,
+    weighting: [KWeighting; 2],
+    from: [[Svf; 2]; 2],
+    from_coef: SvfCoef,
+    /// Samples of the aligned stream: the input delayed by the tracker's lookahead.
+    clock: u64,
+    open: bool,
+    part_start: u64,
+    block: usize,
+    blocks: [(f64, usize); BLOCKS],
+    measured: usize,
+    last_gain: f32,
+    queue: [Pending; PENDING],
+    queue_head: usize,
+    queue_len: usize,
+    gain: f32,
+    ramp_from: f32,
+    ramp_to: f32,
+    ramp_left: usize,
+    history: [Part; HISTORY],
+    history_at: usize,
+    history_len: usize,
+    learn: bool,
+    learned: f32,
+    learn_id: u32,
+    tempo: f64,
+    /// Beat position of the aligned stream.
+    beats: f64,
+    synced: bool,
+    cell: i64,
+    output: f32,
+    bypass: f32,
+    smooth: f32,
+    fresh: bool,
+}
+
+impl Engine {
+    pub fn new(rate: f32, channels: usize) -> Result<Self, &'static str> {
+        if !(8000.0..=384000.).contains(&rate) {
+            return Err("unsupported sample rate");
+        }
+        if !(1..=2).contains(&channels) {
+            return Err("unsupported channel count");
+        }
+        let tracker = Tracker::new(rate, TrackerConfig::BASS);
+        let lookahead = tracker.latency();
+        let samples = |ms: f32| ((rate * ms * 0.001).round() as usize).max(1);
+        let (window, ramp) = (samples(WINDOW_MS), samples(RAMP_MS));
+        let mut e = Self {
+            rate,
+            channels,
+            settings: Settings::default(),
+            tracker,
+            lookahead,
+            window,
+            ramp,
+            min_part: samples(MIN_PART_MS),
+            delay: vec![[0.; 2]; lookahead + window + ramp + 1],
+            delay_at: 0,
+            weighting: [KWeighting::new(rate); 2],
+            from: [[Svf::default(); 2]; 2],
+            from_coef: SvfCoef::IDENTITY,
+            clock: 0,
+            open: false,
+            part_start: 0,
+            block: samples(BLOCK_MS),
+            blocks: [(0., 0); BLOCKS],
+            measured: 0,
+            last_gain: 0.,
+            queue: [Pending::default(); PENDING],
+            queue_head: 0,
+            queue_len: 0,
+            gain: 1.,
+            ramp_from: 1.,
+            ramp_to: 1.,
+            ramp_left: 0,
+            history: [Part::default(); HISTORY],
+            history_at: 0,
+            history_len: 0,
+            learn: false,
+            learned: f32::NAN,
+            learn_id: 0,
+            tempo: FALLBACK_BPM,
+            beats: 0.,
+            synced: false,
+            cell: 0,
+            output: 1.,
+            bypass: 0.,
+            smooth: coefficient(rate, 10.),
+            fresh: true,
+        };
+        e.set_settings(Settings::default())?;
+        e.fresh = true;
+        Ok(e)
+    }
+    /// Lookahead of the tracker, the measuring window and the ramp.
+    pub fn latency_samples(&self) -> u32 {
+        (self.lookahead + self.window + self.ramp) as u32
+    }
+    pub fn channels(&self) -> usize {
+        self.channels
+    }
+    pub fn settings(&self) -> Settings {
+        self.settings
+    }
+    pub fn set_settings(&mut self, s: Settings) -> Result<(), &'static str> {
+        s.validate()?;
+        self.tracker.set(s.source == Source::Midi, s.gate, false);
+        if s.from != self.settings.from || self.fresh {
+            self.from_coef = if s.from > FROM_MIN {
+                SvfCoef::highpass(self.rate, s.from, Q)
+            } else {
+                SvfCoef::IDENTITY
+            };
+        }
+        self.settings = s;
+        if std::mem::take(&mut self.fresh) {
+            self.output = db_to_gain(s.output);
+            self.bypass = f32::from(s.bypass);
+        }
+        Ok(())
+    }
+    /// Host tempo in BPM and, while playing, the beat position at the block's first sample.
+    pub fn set_transport(&mut self, tempo: Option<f64>, position: Option<f64>) {
+        if let Some(t) = tempo.filter(|t| t.is_finite() && *t > 0.) {
+            self.tempo = t;
+        }
+        match position.filter(|p| p.is_finite()) {
+            Some(p) => {
+                // The parts are cut on the aligned stream, `lookahead` samples behind the input.
+                self.beats = p - self.lookahead as f64 / self.rate as f64 * self.tempo / 60.;
+                self.synced = true;
+            }
+            None => self.synced = false,
+        }
+    }
+    pub fn note_on(&mut self, note: u8) {
+        self.tracker.note_on(note);
+    }
+    pub fn note_off(&mut self, note: u8) {
+        self.tracker.note_off(note);
+    }
+    /// Takes the loudness of the next part over the gate as the new target.
+    pub fn learn(&mut self) {
+        self.learn = true;
+    }
+    pub fn reset(&mut self) {
+        self.tracker.reset();
+        self.delay.fill([0.; 2]);
+        self.delay_at = 0;
+        for k in &mut self.weighting {
+            k.reset();
+        }
+        self.from = [[Svf::default(); 2]; 2];
+        self.clock = 0;
+        self.open = false;
+        self.blocks = [(0., 0); BLOCKS];
+        self.measured = 0;
+        self.last_gain = 0.;
+        self.queue_len = 0;
+        self.gain = 1.;
+        self.ramp_left = 0;
+        self.history_len = 0;
+        self.learn = false;
+        self.fresh = true;
+        let s = self.settings;
+        let _ = self.set_settings(s);
+    }
+
+    /// Mean square of the measured blocks, without those far under the loudest.
+    fn gated_mean(&self) -> f64 {
+        let used = self.measured.div_ceil(self.block).min(BLOCKS);
+        let blocks = &self.blocks[..used];
+        let loudest = blocks
+            .iter()
+            .map(|(s, n)| s / (*n).max(1) as f64)
+            .fold(0., f64::max);
+        let floor = loudest * 10f64.powf(-RELATIVE_GATE_DB / 10.);
+        let (sum, n) = blocks
+            .iter()
+            .filter(|(s, n)| s / (*n).max(1) as f64 >= floor)
+            .fold((0., 0), |(a, b), (s, n)| (a + s, b + n));
+        sum / n.max(1) as f64
+    }
+    fn close(&mut self) {
+        self.open = false;
+        let s = self.settings;
+        let loudness = lufs(self.gated_mean());
+        let gated = loudness < s.gate;
+        let gain = if gated {
+            self.last_gain
+        } else {
+            part_gain(loudness, s.target, s.amount * 0.01, s.range)
+        };
+        if !gated {
+            self.last_gain = gain;
+            if std::mem::take(&mut self.learn) {
+                self.learned = loudness;
+                self.learn_id = self.learn_id.wrapping_add(1);
+            }
+        }
+        if self.queue_len < PENDING {
+            let at = (self.queue_head + self.queue_len) % PENDING;
+            self.queue[at] = Pending {
+                start: self.part_start,
+                gain,
+            };
+            self.queue_len += 1;
+        }
+        self.history[self.history_at] = Part {
+            loudness,
+            gain,
+            gated,
+        };
+        self.history_at = (self.history_at + 1) % HISTORY;
+        self.history_len = (self.history_len + 1).min(HISTORY);
+    }
+
+    // Channels index the delayed frame, the filters and the output at once.
+    #[allow(clippy::needless_range_loop)]
+    pub fn process_sample(&mut self, x: [f32; 2]) -> [f32; 2] {
+        let mono = if self.channels == 2 {
+            0.5 * (x[0] + x[1])
+        } else {
+            x[0]
+        };
+        let mut started = false;
+        self.tracker.process(mono, |e| {
+            if matches!(e, NoteEvent::Start { .. }) {
+                started = true;
+            }
+        });
+        let len = self.delay.len();
+        self.delay[self.delay_at] = x;
+        let aligned = self.delay[(self.delay_at + len - self.lookahead) % len];
+        self.delay_at = (self.delay_at + 1) % len;
+        let delayed = self.delay[self.delay_at];
+
+        // Grid lines are counted on the aligned stream even in Notes mode, so switching modes
+        // does not cut a part.
+        let cell = (self.beats / self.settings.grid.quarters()).floor() as i64;
+        self.beats += self.tempo / 60. / self.rate as f64;
+        let crossed = cell != self.cell;
+        self.cell = cell;
+        let boundary = match self.settings.segment {
+            Segment::Notes => started,
+            Segment::Grid => crossed,
+        };
+
+        if boundary && !(self.open && self.measured < self.min_part) {
+            if self.open {
+                self.close();
+            }
+            self.open = true;
+            self.part_start = self.clock;
+            self.blocks = [(0., 0); BLOCKS];
+            self.measured = 0;
+            // Each part is weighted from rest, as if it played alone: the filters' memory of
+            // the last part would otherwise ring into this one.
+            for k in &mut self.weighting {
+                k.reset();
+            }
+            self.from = [[Svf::default(); 2]; 2];
+        }
+        let mut power = 0f64;
+        for c in 0..self.channels {
+            let f = &mut self.from[c];
+            let v = f[0].process(&self.from_coef, aligned[c]);
+            let v = f[1].process(&self.from_coef, v);
+            let w = self.weighting[c].process(v) as f64;
+            power += w * w;
+        }
+        if self.open {
+            let b = &mut self.blocks[(self.measured / self.block).min(BLOCKS - 1)];
+            b.0 += power;
+            b.1 += 1;
+            self.measured += 1;
+            if self.measured >= self.window {
+                self.close();
+            }
+        }
+        // A part's ramp starts `ramp` samples before its first sample reaches the output.
+        if self.queue_len > 0 {
+            let next = self.queue[self.queue_head];
+            if self.clock >= next.start + self.window as u64 {
+                self.queue_head = (self.queue_head + 1) % PENDING;
+                self.queue_len -= 1;
+                self.ramp_from = self.gain;
+                self.ramp_to = db_to_gain(next.gain);
+                self.ramp_left = self.ramp;
+            }
+        }
+        if self.ramp_left > 0 {
+            self.ramp_left -= 1;
+            let t = 1. - self.ramp_left as f32 / self.ramp as f32;
+            let t = t * t * (3. - 2. * t);
+            self.gain = self.ramp_from + (self.ramp_to - self.ramp_from) * t;
+        }
+        self.clock += 1;
+
+        let s = self.settings;
+        self.output += (db_to_gain(s.output) - self.output) * self.smooth;
+        self.bypass += (f32::from(s.bypass) - self.bypass) * self.smooth;
+        if (f32::from(s.bypass) - self.bypass).abs() < 1e-6 {
+            self.bypass = f32::from(s.bypass);
+        }
+        let mut out = [0.; 2];
+        for c in 0..self.channels {
+            let wet = delayed[c] * self.gain * self.output;
+            out[c] = if self.bypass >= 1. {
+                delayed[c]
+            } else {
+                wet + (delayed[c] - wet) * self.bypass
+            };
+        }
+        out
+    }
+
+    fn spread(&self, after: bool) -> f32 {
+        let (mut n, mut sum, mut sq) = (0usize, 0f64, 0f64);
+        for i in 0..self.history_len {
+            if n == SPREAD {
+                break;
+            }
+            let p = self.history[(self.history_at + HISTORY - 1 - i) % HISTORY];
+            if p.gated {
+                continue;
+            }
+            let v = (p.loudness + if after { p.gain } else { 0. }) as f64;
+            n += 1;
+            sum += v;
+            sq += v * v;
+        }
+        if n < 2 {
+            return f32::NAN;
+        }
+        let mean = sum / n as f64;
+        ((sq / n as f64 - mean * mean).max(0.)).sqrt() as f32
+    }
+
+    /// Readings for the editor. Never allocates.
+    pub fn take_analyzer(&self) -> AnalyzerFrame {
+        let mut f = AnalyzerFrame {
+            count: self.history_len,
+            gain: gain_to_db(self.gain),
+            spread_in: self.spread(false),
+            spread_out: self.spread(true),
+            learning: self.learn,
+            learned: self.learned,
+            learn_id: self.learn_id,
+            tempo: self.tempo,
+            synced: self.synced,
+            latency: self.latency_samples(),
+            sample_rate: self.rate,
+            ..AnalyzerFrame::default()
+        };
+        let first = (self.history_at + HISTORY - self.history_len) % HISTORY;
+        for i in 0..self.history_len {
+            f.history[i] = self.history[(first + i) % HISTORY];
+        }
+        f
+    }
+}

plugins/ballast/core/src/settings.rs

@@ -0,0 +1,133 @@
+//! Host-independent controls. Loudness in LUFS, gains in dB, amounts in percent.
+use serde::{Deserialize, Serialize};
+
+pub const TARGET_MIN: f32 = -40.;
+pub const TARGET_MAX: f32 = 0.;
+pub const RANGE_MAX: f32 = 24.;
+/// Lowest frequency the measurement can start from. At or under this the measurement hears
+/// the full band.
+pub const FROM_MIN: f32 = 20.;
+pub const FROM_MAX: f32 = 300.;
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
+pub enum Source {
+    /// Note starts are detected from the incoming bass.
+    #[default]
+    Audio,
+    /// Note starts come from MIDI note input.
+    Midi,
+}
+
+/// Where one leveled part ends and the next begins.
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
+pub enum Segment {
+    /// Every note start.
+    #[default]
+    Notes,
+    /// Every line of the host's beat grid, so a patch change on the same note counts too.
+    Grid,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
+pub enum Grid {
+    Bar,
+    Half,
+    #[default]
+    Quarter,
+    Eighth,
+    Sixteenth,
+}
+impl Grid {
+    pub const ALL: [Grid; 5] = [
+        Grid::Bar,
+        Grid::Half,
+        Grid::Quarter,
+        Grid::Eighth,
+        Grid::Sixteenth,
+    ];
+    /// Length in quarter notes.
+    pub fn quarters(self) -> f64 {
+        match self {
+            Grid::Bar => 4.,
+            Grid::Half => 2.,
+            Grid::Quarter => 1.,
+            Grid::Eighth => 0.5,
+            Grid::Sixteenth => 0.25,
+        }
+    }
+    pub fn label(self) -> &'static str {
+        match self {
+            Grid::Bar => "1 BAR",
+            Grid::Half => "1/2",
+            Grid::Quarter => "1/4",
+            Grid::Eighth => "1/8",
+            Grid::Sixteenth => "1/16",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq)]
+#[serde(deny_unknown_fields)]
+pub struct Settings {
+    pub source: Source,
+    pub segment: Segment,
+    pub grid: Grid,
+    /// Loudness every part should land at, measured over its first 100 ms.
+    pub target: f32,
+    /// Share of the correction that is applied.
+    pub amount: f32,
+    /// Most boost or cut, in dB.
+    pub range: f32,
+    /// The measurement hears only what is above this frequency; the gain still applies to
+    /// the full band. Set it to Anvil's Split when Anvil makes the sub.
+    pub from: f32,
+    /// Note-start threshold (Audio source), and the loudness under which a part keeps the
+    /// last gain instead of being lifted.
+    pub gate: f32,
+    pub output: f32,
+    pub bypass: bool,
+}
+impl Default for Settings {
+    fn default() -> Self {
+        Self {
+            source: Source::Audio,
+            segment: Segment::Notes,
+            grid: Grid::Quarter,
+            target: -14.,
+            amount: 100.,
+            range: 12.,
+            from: FROM_MIN,
+            gate: -48.,
+            output: 0.,
+            bypass: false,
+        }
+    }
+}
+impl Settings {
+    pub fn validate(&self) -> Result<(), &'static str> {
+        let finite = [
+            self.target,
+            self.amount,
+            self.range,
+            self.from,
+            self.gate,
+            self.output,
+        ]
+        .iter()
+        .all(|v| v.is_finite());
+        if !finite {
+            return Err("non-finite setting");
+        }
+        let ok = (TARGET_MIN..=TARGET_MAX).contains(&self.target)
+            && (0.0..=100.).contains(&self.amount)
+            && (0.0..=RANGE_MAX).contains(&self.range)
+            && (FROM_MIN..=FROM_MAX).contains(&self.from)
+            && (-60.0..=-20.).contains(&self.gate)
+            && (-12.0..=12.).contains(&self.output);
+        if ok {
+            Ok(())
+        } else {
+            Err("setting out of range")
+        }
+    }
+}

plugins/ballast/core/tests/dsp.rs

@@ -0,0 +1,332 @@
+use ballast_core::{part_gain, Engine, Grid, Segment, Settings, Source, RAMP_MS, WINDOW_MS};
+use common_dsp::loudness::{lufs, KWeighting};
+use std::f64::consts::TAU;
+
+const RATE: f32 = 48000.;
+const BPM: f64 = 120.;
+/// One quarter at 120 BPM.
+const QUARTER: usize = 24000;
+
+/// Two patches a switch-up might alternate: a loud saw and a quiet sine, an octave apart.
+fn patch(i: usize, which: usize) -> f32 {
+    let t = i as f64 / RATE as f64;
+    if which.is_multiple_of(2) {
+        let phase = (55. * t).fract();
+        (0.5 * (2. * phase - 1.)) as f32
+    } else {
+        (0.1 * (TAU * 110. * t).sin()) as f32
+    }
+}
+fn grid_engine(s: Settings) -> Engine {
+    let mut e = Engine::new(RATE, 2).unwrap();
+    e.set_settings(Settings {
+        segment: Segment::Grid,
+        grid: Grid::Quarter,
+        ..s
+    })
+    .unwrap();
+    e
+}
+/// Runs `input` through the engine in 512-sample blocks with the transport playing from 0.
+fn run(e: &mut Engine, input: &[f32]) -> Vec<f32> {
+    let mut out = Vec::with_capacity(input.len());
+    for (i, &v) in input.iter().enumerate() {
+        if i % 512 == 0 {
+            e.set_transport(Some(BPM), Some(i as f64 / RATE as f64 * BPM / 60.));
+        }
+        out.push(e.process_sample([v, v])[0]);
+    }
+    out
+}
+/// K-weighted loudness of both channels (the same signal) over `window` samples from `start`.
+fn loudness(x: &[f32], start: usize, window: usize) -> f32 {
+    let mut k = KWeighting::new(RATE);
+    // Settle the filter on what came before, as the engine's own measurement does.
+    for &v in &x[start.saturating_sub(4800)..start] {
+        k.process(v);
+    }
+    let sum: f64 = x[start..start + window]
+        .iter()
+        .map(|&v| (k.process(v) as f64).powi(2))
+        .sum();
+    lufs(2. * sum / window as f64)
+}
+fn window() -> usize {
+    (RATE * WINDOW_MS * 0.001) as usize
+}
+
+#[test]
+fn every_part_lands_at_the_target() {
+    let target = -18.;
+    let mut e = grid_engine(Settings {
+        target,
+        ..Settings::default()
+    });
+    let latency = e.latency_samples() as usize;
+    let parts = 10;
+    let input: Vec<f32> = (0..parts * QUARTER + latency)
+        .map(|i| patch(i, i / QUARTER))
+        .collect();
+    let out = run(&mut e, &input);
+    for p in 2..parts {
+        let start = p * QUARTER;
+        let before = loudness(&input, start, window());
+        let after = loudness(&out, start + latency, window());
+        assert!(
+            (after - target).abs() < 0.3,
+            "part {p}: {before:.1} → {after:.1}"
+        );
+    }
+    let f = e.take_analyzer();
+    assert!(f.spread_in > 5., "{}", f.spread_in);
+    assert!(f.spread_out < 0.1, "{}", f.spread_out);
+}
+
+#[test]
+fn the_gain_holds_still_inside_a_part_and_is_in_place_on_its_attack() {
+    let mut e = grid_engine(Settings {
+        target: -18.,
+        ..Settings::default()
+    });
+    let latency = e.latency_samples() as usize;
+    let ramp = (RATE * RAMP_MS * 0.001) as usize;
+    let input: Vec<f32> = (0..6 * QUARTER + latency)
+        .map(|i| patch(i, i / QUARTER) + 0.2)
+        .collect();
+    let out = run(&mut e, &input);
+    for p in 2..5 {
+        let start = p * QUARTER;
+        assert!(input[start].abs() > 0.05);
+        let gain = out[start + latency] / input[start];
+        for n in start..start + QUARTER - ramp {
+            if input[n].abs() < 0.05 {
+                continue;
+            }
+            let g = out[n + latency] / input[n];
+            assert!(
+                (g / gain - 1.).abs() < 1e-4,
+                "part {p}, sample {n}: {g} vs {gain}"
+            );
+        }
+    }
+}
+
+#[test]
+fn note_starts_from_the_audio_cut_the_parts() {
+    let target = -18.;
+    let mut e = Engine::new(RATE, 2).unwrap();
+    e.set_settings(Settings {
+        target,
+        ..Settings::default()
+    })
+    .unwrap();
+    let latency = e.latency_samples() as usize;
+    // 300 ms notes with 100 ms gaps, alternating the two patches.
+    let note = 19200;
+    let input: Vec<f32> = (0..8 * note + latency)
+        .map(|i| {
+            if i % note < 14400 && i < 8 * note {
+                patch(i, i / note)
+            } else {
+                0.
+            }
+        })
+        .collect();
+    let out = run(&mut e, &input);
+    let f = e.take_analyzer();
+    let parts = f.history[..f.count].iter().filter(|p| !p.gated).count();
+    assert_eq!(parts, 8, "{:?}", &f.history[..f.count]);
+    for n in 2..8 {
+        // The tracker finds the start a few milliseconds in; measure past that.
+        let start = n * note + 960;
+        let after = loudness(&out, start + latency, window());
+        assert!((after - target).abs() < 0.5, "note {n}: {after:.1}");
+    }
+}
+
+#[test]
+fn midi_note_starts_cut_legato_parts() {
+    let target = -18.;
+    let mut e = Engine::new(RATE, 2).unwrap();
+    e.set_settings(Settings {
+        target,
+        source: Source::Midi,
+        ..Settings::default()
+    })
+    .unwrap();
+    let latency = e.latency_samples() as usize;
+    let note = QUARTER;
+    let mut out = Vec::new();
+    let input: Vec<f32> = (0..6 * note + latency)
+        .map(|i| patch(i, i / note))
+        .collect();
+    for (i, &v) in input.iter().enumerate() {
+        if i % note == 0 {
+            // Legato: the new note starts before the old one ends, on the same pitch.
+            e.note_on(33);
+            if i > 0 {
+                e.note_off(33);
+                e.note_on(33);
+            }
+        }
+        out.push(e.process_sample([v, v])[0]);
+    }
+    for n in 2..6 {
+        let after = loudness(&out, n * note + latency, window());
+        assert!((after - target).abs() < 0.3, "note {n}: {after:.1}");
+    }
+}
+
+#[test]
+fn quiet_parts_keep_the_last_gain() {
+    let mut e = grid_engine(Settings {
+        target: -18.,
+        gate: -40.,
+        ..Settings::default()
+    });
+    // A loud part, then a part far under the gate, then the loud patch again. The parts change
+    // on zero crossings of a 110 Hz sine, so no step rings into the quiet part.
+    let input: Vec<f32> = (0..4 * QUARTER)
+        .map(|i| {
+            let v = 0.5 * (TAU * 110. * i as f64 / RATE as f64).sin() as f32;
+            if i / QUARTER == 2 {
+                v * 0.001
+            } else {
+                v
+            }
+        })
+        .collect();
+    run(&mut e, &input);
+    let f = e.take_analyzer();
+    let parts = &f.history[..f.count];
+    // The first part is the silence before the input reaches the measurement.
+    let quiet = 1 + parts[1..]
+        .iter()
+        .position(|p| p.gated)
+        .expect("a gated part");
+    assert_eq!(parts[quiet].gain, parts[quiet - 1].gain);
+}
+
+#[test]
+fn amount_and_range_scale_the_correction() {
+    assert_eq!(part_gain(-10., -14., 1., 12.), -4.);
+    assert_eq!(part_gain(-10., -14., 0.5, 12.), -2.);
+    assert_eq!(part_gain(-40., -14., 1., 12.), 12.);
+    assert_eq!(part_gain(0., -14., 1., 6.), -6.);
+    let mut e = grid_engine(Settings {
+        target: -18.,
+        amount: 50.,
+        ..Settings::default()
+    });
+    let input: Vec<f32> = (0..4 * QUARTER).map(|i| patch(i, i / QUARTER)).collect();
+    run(&mut e, &input);
+    let f = e.take_analyzer();
+    for p in &f.history[1..f.count] {
+        let full = -18. - p.loudness;
+        assert!((p.gain - 0.5 * full).abs() < 1e-3, "{p:?}");
+    }
+}
+
+#[test]
+fn learn_takes_the_next_part_as_the_target() {
+    let mut e = grid_engine(Settings::default());
+    let input: Vec<f32> = (0..3 * QUARTER).map(|i| patch(i, i / QUARTER)).collect();
+    run(&mut e, &input[..QUARTER + 100]);
+    e.learn();
+    assert!(e.take_analyzer().learning);
+    let before = e.take_analyzer().learn_id;
+    run(&mut e, &input[QUARTER + 100..]);
+    let f = e.take_analyzer();
+    assert!(!f.learning);
+    assert_ne!(f.learn_id, before);
+    let taken = f.history[..f.count]
+        .iter()
+        .find(|p| p.loudness == f.learned)
+        .expect("learned a part's loudness");
+    assert!(!taken.gated);
+}
+
+#[test]
+fn the_measurement_can_leave_out_the_sub() {
+    // The same top, once with a loud sub under it.
+    let top = |i: usize| (0.05 * (TAU * 1000. * i as f64 / RATE as f64).sin()) as f32;
+    let sub = |i: usize| (0.5 * (TAU * 50. * i as f64 / RATE as f64).sin()) as f32;
+    let gains = |from: f32| {
+        let mut e = grid_engine(Settings {
+            target: -24.,
+            range: 24.,
+            from,
+            ..Settings::default()
+        });
+        let input: Vec<f32> = (0..4 * QUARTER)
+            .map(|i| {
+                top(i)
+                    + if (i / QUARTER).is_multiple_of(2) {
+                        sub(i)
+                    } else {
+                        0.
+                    }
+            })
+            .collect();
+        run(&mut e, &input);
+        let f = e.take_analyzer();
+        let p = &f.history[..f.count];
+        (p[p.len() - 2].gain - p[p.len() - 1].gain).abs()
+    };
+    assert!(gains(20.) > 10.);
+    assert!(gains(200.) < 1., "{}", gains(200.));
+}
+
+#[test]
+fn bypass_is_the_input_delayed_by_the_latency() {
+    let mut e = grid_engine(Settings {
+        bypass: true,
+        target: -30.,
+        ..Settings::default()
+    });
+    let latency = e.latency_samples() as usize;
+    let lookahead = latency - window() - (RATE * RAMP_MS * 0.001) as usize;
+    // The tracker's lookahead: two periods of 30 Hz and a margin, about 67 ms.
+    assert!((lookahead as f32 / RATE - 0.067).abs() < 0.005);
+    let input: Vec<f32> = (0..2 * QUARTER).map(|i| patch(i, i / QUARTER)).collect();
+    let out = run(&mut e, &input);
+    for i in latency..input.len() {
+        assert_eq!(out[i], input[i - latency]);
+    }
+}
+
+#[test]
+fn settings_are_validated_and_serialise() {
+    assert!(Settings::default().validate().is_ok());
+    for bad in [
+        Settings {
+            target: 3.,
+            ..Settings::default()
+        },
+        Settings {
+            range: 30.,
+            ..Settings::default()
+        },
+        Settings {
+            from: 10.,
+            ..Settings::default()
+        },
+        Settings {
+            amount: f32::NAN,
+            ..Settings::default()
+        },
+    ] {
+        assert!(bad.validate().is_err());
+        assert!(Engine::new(RATE, 2).unwrap().set_settings(bad).is_err());
+    }
+    let s = Settings {
+        segment: Segment::Grid,
+        grid: Grid::Eighth,
+        source: Source::Midi,
+        target: -9.,
+        ..Settings::default()
+    };
+    let json = serde_json::to_string(&s).unwrap();
+    assert_eq!(serde_json::from_str::<Settings>(&json).unwrap(), s);
+    assert!(serde_json::from_str::<Settings>(r#"{"target":0,"oops":1}"#).is_err());
+}

plugins/ballast/core/tests/realtime.rs

@@ -0,0 +1,86 @@
+use ballast_core::{Engine, Grid, Segment, Settings, Source};
+use std::{
+    alloc::{GlobalAlloc, Layout, System},
+    cell::Cell,
+};
+
+struct CheckedAllocator;
+thread_local! {
+    static CHECK:Cell<bool>=const {Cell::new(false)};
+    static OPERATIONS:Cell<usize>=const {Cell::new(0)};
+}
+fn record() {
+    if CHECK.try_with(Cell::get).unwrap_or(false) {
+        let _ = OPERATIONS.try_with(|n| n.set(n.get() + 1));
+    }
+}
+unsafe impl GlobalAlloc for CheckedAllocator {
+    unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
+        record();
+        unsafe { System.alloc(layout) }
+    }
+    unsafe fn dealloc(&self, pointer: *mut u8, layout: Layout) {
+        record();
+        unsafe { System.dealloc(pointer, layout) }
+    }
+    unsafe fn realloc(&self, pointer: *mut u8, layout: Layout, size: usize) -> *mut u8 {
+        record();
+        unsafe { System.realloc(pointer, layout, size) }
+    }
+}
+#[global_allocator]
+static ALLOCATOR: CheckedAllocator = CheckedAllocator;
+
+#[test]
+fn processing_notes_settings_transport_and_analysis_do_not_allocate_or_free() {
+    let mut engine = Engine::new(48000., 2).unwrap();
+    let mut settings = Settings::default();
+    engine.set_settings(settings).unwrap();
+    CHECK.with(|v| v.set(true));
+    for i in 0..96000 {
+        if i % 512 == 0 {
+            let playing = (i / 24000) % 2 == 0;
+            engine.set_transport(
+                Some(140.),
+                playing.then_some(i as f64 / 48000. * 140. / 60.),
+            );
+        }
+        if i % 4800 == 0 {
+            let step = i / 4800;
+            settings.segment = if step % 2 == 0 {
+                Segment::Grid
+            } else {
+                Segment::Notes
+            };
+            settings.grid = Grid::ALL[step % Grid::ALL.len()];
+            settings.source = if step % 4 < 2 {
+                Source::Audio
+            } else {
+                Source::Midi
+            };
+            settings.from = 20. + 30. * (step % 5) as f32;
+            settings.bypass = step % 7 == 6;
+            engine.set_settings(settings).unwrap();
+            engine.note_on(33 + (step % 12) as u8);
+            if step % 3 == 0 {
+                engine.learn();
+            }
+        }
+        if i % 4800 == 2400 {
+            engine.note_off(33 + (i / 4800 % 12) as u8);
+        }
+        let t = i as f32 / 48000.;
+        let x = if (i / 2400) % 2 == 0 {
+            (std::f32::consts::TAU * 55. * t).sin() * 0.5
+        } else {
+            0.
+        };
+        std::hint::black_box(engine.process_sample([x, -x]));
+        if i % 1600 == 0 {
+            std::hint::black_box(engine.take_analyzer());
+        }
+    }
+    engine.reset();
+    CHECK.with(|v| v.set(false));
+    assert_eq!(OPERATIONS.with(Cell::get), 0);
+}

plugins/ballast/plugin/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "ballast"
+version = "0.1.0"
+edition = "2021"
+license = "ISC"
+
+[workspace]
+
+[lib]
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+nih_plug = { git = "https://github.com/robbert-vdh/nih-plug.git", rev = "de421011f41a6d10fc8c7a6084e4f4dee0143683", default-features = false }
+nih_plug_egui = { git = "https://github.com/robbert-vdh/nih-plug.git", rev = "de421011f41a6d10fc8c7a6084e4f4dee0143683" }
+ballast-core = { path = "../core" }
+ballast-ui = { path = "../ui" }
+crossbeam-queue = "0.3"
+
+[dev-dependencies]
+clap-sys = { git = "https://github.com/micahrj/clap-sys.git", rev = "25d7f53fdb6363ad63fbd80049cb7a42a97ac156" }
+serde_json = "1"
+
+[profile.release]
+lto = "thin"
+strip = "symbols"

plugins/ballast/plugin/src/lib.rs

@@ -0,0 +1,210 @@
+//! CLAP audio effect. All DSP state is owned by the processing thread.
+mod params;
+use ballast_core::{AnalyzerFrame, Engine};
+use crossbeam_queue::ArrayQueue;
+use nih_plug::prelude::*;
+use nih_plug_egui::{create_egui_editor, egui};
+use params::{BallastParams, FLOATS};
+use std::sync::{
+    atomic::{AtomicBool, Ordering},
+    Arc,
+};
+
+struct Shared {
+    analyzer: ArrayQueue<AnalyzerFrame>,
+    /// Set by the editor's Learn button, taken by the audio thread.
+    learn: AtomicBool,
+}
+
+struct EditorData {
+    ui: ballast_ui::State,
+    gestures: [bool; FLOATS],
+}
+pub struct Ballast {
+    params: Arc<BallastParams>,
+    shared: Arc<Shared>,
+    engine: Option<Engine>,
+    publish_count: usize,
+    publish_interval: usize,
+}
+impl Default for Ballast {
+    fn default() -> Self {
+        Self {
+            params: Arc::new(BallastParams::default()),
+            shared: Arc::new(Shared {
+                analyzer: ArrayQueue::new(2),
+                learn: AtomicBool::new(false),
+            }),
+            engine: None,
+            publish_count: 0,
+            publish_interval: 1600,
+        }
+    }
+}
+impl Plugin for Ballast {
+    const NAME: &'static str = "Ballast";
+    const VENDOR: &'static str = "Bass Foundry";
+    const URL: &'static str = "";
+    const EMAIL: &'static str = "";
+    const VERSION: &'static str = env!("CARGO_PKG_VERSION");
+    const AUDIO_IO_LAYOUTS: &'static [AudioIOLayout] = &[
+        AudioIOLayout {
+            main_input_channels: NonZeroU32::new(2),
+            main_output_channels: NonZeroU32::new(2),
+            ..AudioIOLayout::const_default()
+        },
+        AudioIOLayout {
+            main_input_channels: NonZeroU32::new(1),
+            main_output_channels: NonZeroU32::new(1),
+            ..AudioIOLayout::const_default()
+        },
+    ];
+    const MIDI_INPUT: MidiConfig = MidiConfig::Basic;
+    const SAMPLE_ACCURATE_AUTOMATION: bool = false;
+    type SysExMessage = ();
+    type BackgroundTask = ();
+    fn params(&self) -> Arc<dyn Params> {
+        self.params.clone()
+    }
+    fn editor(&mut self, _: AsyncExecutor<Self>) -> Option<Box<dyn Editor>> {
+        let params = self.params.clone();
+        let shared = self.shared.clone();
+        create_egui_editor(
+            params.editor.clone(),
+            EditorData {
+                ui: ballast_ui::State::default(),
+                gestures: [false; FLOATS],
+            },
+            |ctx, _| ballast_ui::style(ctx),
+            move |ctx, setter, data| {
+                while let Some(frame) = shared.analyzer.pop() {
+                    data.ui.accept_frame(frame);
+                }
+                let before = params.settings();
+                let mut edited = before;
+                nih_plug_egui::resizable_window::ResizableWindow::new("ballast-editor")
+                    .min_size(egui::vec2(
+                        ballast_ui::WIDTH as f32 - 80.,
+                        ballast_ui::HEIGHT as f32 - 40.,
+                    ))
+                    .show(ctx, &params.editor, |ui| {
+                        ballast_ui::show(ui, &mut edited, &mut data.ui)
+                    });
+                params.apply(
+                    setter,
+                    &before,
+                    &edited,
+                    data.ui.gesture_active,
+                    &mut data.gestures,
+                );
+                if std::mem::take(&mut data.ui.learn_request) {
+                    shared.learn.store(true, Ordering::Release);
+                }
+                ctx.request_repaint_after(std::time::Duration::from_millis(40));
+            },
+        )
+    }
+    fn initialize(
+        &mut self,
+        layout: &AudioIOLayout,
+        config: &BufferConfig,
+        context: &mut impl InitContext<Self>,
+    ) -> bool {
+        let Ok(mut engine) = Engine::new(
+            config.sample_rate,
+            layout.main_input_channels.map_or(0, |v| v.get() as usize),
+        ) else {
+            return false;
+        };
+        let settings = self.params.settings();
+        if engine.set_settings(settings).is_err() {
+            return false;
+        }
+        context.set_latency_samples(engine.latency_samples());
+        self.publish_interval = (config.sample_rate / 30.) as usize;
+        self.engine = Some(engine);
+        true
+    }
+    fn reset(&mut self) {
+        if let Some(e) = self.engine.as_mut() {
+            e.reset();
+        }
+        self.publish_count = 0;
+    }
+    fn process(
+        &mut self,
+        buffer: &mut Buffer,
+        _: &mut AuxiliaryBuffers,
+        context: &mut impl ProcessContext<Self>,
+    ) -> ProcessStatus {
+        let Some(engine) = self.engine.as_mut() else {
+            return ProcessStatus::Normal;
+        };
+        let settings = self.params.settings();
+        let _ = engine.set_settings(settings);
+        if self.shared.learn.swap(false, Ordering::AcqRel) {
+            engine.learn();
+        }
+        let transport = context.transport();
+        engine.set_transport(
+            transport.tempo,
+            if transport.playing {
+                transport.pos_beats()
+            } else {
+                None
+            },
+        );
+        let mut next = context.next_event();
+        for (index, mut sample) in buffer.iter_samples().enumerate() {
+            while let Some(event) = next {
+                if event.timing() as usize > index {
+                    break;
+                }
+                match event {
+                    NoteEvent::NoteOn { note, velocity, .. } if velocity > 0. => {
+                        engine.note_on(note)
+                    }
+                    NoteEvent::NoteOn { note, .. } | NoteEvent::NoteOff { note, .. } => {
+                        engine.note_off(note)
+                    }
+                    NoteEvent::Choke { note, .. } => engine.note_off(note),
+                    _ => {}
+                }
+                next = context.next_event();
+            }
+            let x = [
+                *sample.get_mut(0).unwrap(),
+                if engine.channels() == 2 {
+                    *sample.get_mut(1).unwrap()
+                } else {
+                    0.
+                },
+            ];
+            let out = engine.process_sample(x);
+            for (c, value) in sample.into_iter().enumerate() {
+                *value = out[c];
+            }
+            self.publish_count += 1;
+            if self.publish_count >= self.publish_interval {
+                let _ = self.shared.analyzer.force_push(engine.take_analyzer());
+                self.publish_count = 0;
+            }
+        }
+        // The lookahead delay must drain after input stops.
+        ProcessStatus::KeepAlive
+    }
+}
+impl ClapPlugin for Ballast {
+    const CLAP_ID: &'static str = "io.narl.bass-foundry.ballast";
+    const CLAP_DESCRIPTION: Option<&'static str> =
+        Some("Levels every note or switch-up to one loudness with a single gain each");
+    const CLAP_MANUAL_URL: Option<&'static str> = None;
+    const CLAP_SUPPORT_URL: Option<&'static str> = None;
+    const CLAP_FEATURES: &'static [ClapFeature] = &[
+        ClapFeature::AudioEffect,
+        ClapFeature::Utility,
+        ClapFeature::Stereo,
+        ClapFeature::Mono,
+    ];
+}
+nih_export_clap!(Ballast);

plugins/ballast/plugin/src/params.rs

@@ -0,0 +1,203 @@
+use ballast_core::{
+    Grid, Segment, Settings, Source, FROM_MAX, FROM_MIN, RANGE_MAX, TARGET_MAX, TARGET_MIN,
+};
+use nih_plug::prelude::*;
+use nih_plug_egui::EguiState;
+use std::sync::Arc;
+
+#[derive(Enum, Debug, PartialEq, Eq, Clone, Copy)]
+pub enum SourceParam {
+    #[id = "audio"]
+    Audio,
+    #[id = "midi"]
+    #[name = "MIDI"]
+    Midi,
+}
+#[derive(Enum, Debug, PartialEq, Eq, Clone, Copy)]
+pub enum SegmentParam {
+    #[id = "notes"]
+    Notes,
+    #[id = "grid"]
+    Grid,
+}
+#[derive(Enum, Debug, PartialEq, Eq, Clone, Copy)]
+pub enum GridParam {
+    #[id = "bar"]
+    #[name = "1 bar"]
+    Bar,
+    #[id = "1-2"]
+    #[name = "1/2"]
+    Half,
+    #[id = "1-4"]
+    #[name = "1/4"]
+    Quarter,
+    #[id = "1-8"]
+    #[name = "1/8"]
+    Eighth,
+    #[id = "1-16"]
+    #[name = "1/16"]
+    Sixteenth,
+}
+const GRIDS: [(GridParam, Grid); 5] = [
+    (GridParam::Bar, Grid::Bar),
+    (GridParam::Half, Grid::Half),
+    (GridParam::Quarter, Grid::Quarter),
+    (GridParam::Eighth, Grid::Eighth),
+    (GridParam::Sixteenth, Grid::Sixteenth),
+];
+fn grid_param(g: Grid) -> GridParam {
+    GRIDS
+        .iter()
+        .find(|(_, v)| *v == g)
+        .map_or(GridParam::Quarter, |(p, _)| *p)
+}
+fn linear(name: &str, v: f32, min: f32, max: f32, unit: &'static str) -> FloatParam {
+    FloatParam::new(name, v, FloatRange::Linear { min, max }).with_unit(unit)
+}
+/// Continuous controls, in the order of the gesture slots.
+pub const FLOATS: usize = 6;
+
+#[derive(Params)]
+pub struct BallastParams {
+    #[persist = "editor"]
+    pub editor: Arc<EguiState>,
+    #[id = "source"]
+    pub source: EnumParam<SourceParam>,
+    #[id = "segment"]
+    pub segment: EnumParam<SegmentParam>,
+    #[id = "grid"]
+    pub grid: EnumParam<GridParam>,
+    #[id = "target"]
+    pub target: FloatParam,
+    #[id = "amount"]
+    pub amount: FloatParam,
+    #[id = "range"]
+    pub range: FloatParam,
+    #[id = "from"]
+    pub from: FloatParam,
+    #[id = "gate"]
+    pub gate: FloatParam,
+    #[id = "output"]
+    pub output: FloatParam,
+    #[id = "bypass"]
+    pub bypass: BoolParam,
+}
+impl Default for BallastParams {
+    fn default() -> Self {
+        let d = Settings::default();
+        Self {
+            editor: EguiState::from_size(ballast_ui::WIDTH, ballast_ui::HEIGHT),
+            source: EnumParam::new("Note source", SourceParam::Audio),
+            segment: EnumParam::new("Parts from", SegmentParam::Notes),
+            grid: EnumParam::new("Grid", grid_param(d.grid)),
+            target: linear("Target", d.target, TARGET_MIN, TARGET_MAX, " LUFS"),
+            amount: linear("Amount", d.amount, 0., 100., " %"),
+            range: linear("Range", d.range, 0., RANGE_MAX, " dB"),
+            from: FloatParam::new(
+                "Measure from",
+                d.from,
+                FloatRange::Skewed {
+                    min: FROM_MIN,
+                    max: FROM_MAX,
+                    factor: FloatRange::skew_factor(-1.),
+                },
+            )
+            .with_unit(" Hz"),
+            gate: linear("Gate", d.gate, -60., -20., " dB"),
+            output: linear("Output", d.output, -12., 12., " dB"),
+            bypass: BoolParam::new("Bypass", false).make_bypass(),
+        }
+    }
+}
+impl BallastParams {
+    pub fn settings(&self) -> Settings {
+        let grid = self.grid.value();
+        Settings {
+            source: match self.source.value() {
+                SourceParam::Audio => Source::Audio,
+                SourceParam::Midi => Source::Midi,
+            },
+            segment: match self.segment.value() {
+                SegmentParam::Notes => Segment::Notes,
+                SegmentParam::Grid => Segment::Grid,
+            },
+            grid: GRIDS
+                .iter()
+                .find(|(p, _)| *p == grid)
+                .map_or(Grid::Quarter, |(_, g)| *g),
+            target: self.target.value(),
+            amount: self.amount.value(),
+            range: self.range.value(),
+            from: self.from.value(),
+            gate: self.gate.value(),
+            output: self.output.value(),
+            bypass: self.bypass.value(),
+        }
+    }
+    fn floats(&self) -> [&FloatParam; FLOATS] {
+        [
+            &self.target,
+            &self.amount,
+            &self.range,
+            &self.from,
+            &self.gate,
+            &self.output,
+        ]
+    }
+    fn values(s: &Settings) -> [f32; FLOATS] {
+        [s.target, s.amount, s.range, s.from, s.gate, s.output]
+    }
+    /// Pushes every changed editor value to the host. Continuous controls hold one gesture
+    /// while the pointer is down; switches are set in a single gesture.
+    pub fn apply(
+        &self,
+        setter: &ParamSetter,
+        old: &Settings,
+        new: &Settings,
+        dragging: bool,
+        open: &mut [bool; FLOATS],
+    ) {
+        let pairs = Self::values(old).into_iter().zip(Self::values(new));
+        for (i, (p, (a, b))) in self.floats().into_iter().zip(pairs).enumerate() {
+            if a != b {
+                if !open[i] {
+                    open[i] = true;
+                    setter.begin_set_parameter(p);
+                }
+                setter.set_parameter(p, b);
+            }
+            if !dragging && open[i] {
+                setter.end_set_parameter(p);
+                open[i] = false;
+            }
+        }
+        if new.bypass != old.bypass {
+            setter.begin_set_parameter(&self.bypass);
+            setter.set_parameter(&self.bypass, new.bypass);
+            setter.end_set_parameter(&self.bypass);
+        }
+        if new.source != old.source {
+            let v = match new.source {
+                Source::Audio => SourceParam::Audio,
+                Source::Midi => SourceParam::Midi,
+            };
+            setter.begin_set_parameter(&self.source);
+            setter.set_parameter(&self.source, v);
+            setter.end_set_parameter(&self.source);
+        }
+        if new.segment != old.segment {
+            let v = match new.segment {
+                Segment::Notes => SegmentParam::Notes,
+                Segment::Grid => SegmentParam::Grid,
+            };
+            setter.begin_set_parameter(&self.segment);
+            setter.set_parameter(&self.segment, v);
+            setter.end_set_parameter(&self.segment);
+        }
+        if new.grid != old.grid {
+            setter.begin_set_parameter(&self.grid);
+            setter.set_parameter(&self.grid, grid_param(new.grid));
+            setter.end_set_parameter(&self.grid);
+        }
+    }
+}

plugins/ballast/plugin/tests/host.rs

@@ -0,0 +1,216 @@
+//! Exercise the actual exported CLAP ABI without requiring a GUI or installed DAW.
+use clap_sys::{
+    audio_buffer::*,
+    events::*,
+    ext::{audio_ports::*, latency::*, state::*},
+    factory::plugin_factory::*,
+    host::*,
+    process::*,
+    stream::*,
+    version::*,
+};
+use std::{
+    ffi::{c_char, c_void, CStr},
+    io::{Cursor, Read},
+    ptr,
+};
+
+unsafe extern "C" fn extension(_: *const clap_host, _: *const c_char) -> *const c_void {
+    ptr::null()
+}
+unsafe extern "C" fn request(_: *const clap_host) {}
+unsafe extern "C" fn count(_: *const clap_input_events) -> u32 {
+    0
+}
+unsafe extern "C" fn event(_: *const clap_input_events, _: u32) -> *const clap_event_header {
+    ptr::null()
+}
+unsafe extern "C" fn push(_: *const clap_output_events, _: *const clap_event_header) -> bool {
+    true
+}
+unsafe extern "C" fn write(stream: *const clap_ostream, buffer: *const c_void, size: u64) -> i64 {
+    // SAFETY: The test owns the Vec for the entire synchronous save call.
+    let bytes = unsafe { &mut *((*stream).ctx as *mut Vec<u8>) };
+    bytes.extend_from_slice(unsafe {
+        std::slice::from_raw_parts(buffer as *const u8, size as usize)
+    });
+    size as i64
+}
+unsafe extern "C" fn read(stream: *const clap_istream, buffer: *mut c_void, size: u64) -> i64 {
+    // SAFETY: The test owns the Cursor; the wrapper supplies writable stream storage.
+    let cursor = unsafe { &mut *((*stream).ctx as *mut Cursor<Vec<u8>>) };
+    cursor
+        .read(unsafe { std::slice::from_raw_parts_mut(buffer as *mut u8, size as usize) })
+        .unwrap() as i64
+}
+
+#[test]
+fn effect_ports_state_latency_and_audio_lifecycle() {
+    // SAFETY: All callbacks, strings, streams, buffers, and the host outlive their
+    // synchronous ABI calls. Activation/processing/destruction follow CLAP order.
+    unsafe {
+        let entry = &ballast::clap_entry;
+        assert!(entry.init.unwrap()(c"ballast.clap".as_ptr()));
+        let factory = entry.get_factory.unwrap()(CLAP_PLUGIN_FACTORY_ID.as_ptr())
+            as *const clap_plugin_factory;
+        assert!(!factory.is_null());
+        let factory = &*factory;
+        assert_eq!(factory.get_plugin_count.unwrap()(factory), 1);
+        let descriptor = factory.get_plugin_descriptor.unwrap()(factory, 0);
+        assert!(!descriptor.is_null());
+        assert_eq!(CStr::from_ptr((*descriptor).name), c"Ballast");
+        assert_eq!(
+            CStr::from_ptr((*descriptor).id),
+            c"io.narl.bass-foundry.ballast"
+        );
+        assert!(factory.get_plugin_descriptor.unwrap()(factory, 1).is_null());
+        let host = clap_host {
+            clap_version: CLAP_VERSION,
+            host_data: ptr::null_mut(),
+            name: c"Storyboard test host".as_ptr(),
+            vendor: c"Tests".as_ptr(),
+            url: c"".as_ptr(),
+            version: c"1.0".as_ptr(),
+            get_extension: Some(extension),
+            request_restart: Some(request),
+            request_process: Some(request),
+            request_callback: Some(request),
+        };
+        let plugin = factory.create_plugin.unwrap()(factory, &host, (*descriptor).id);
+        assert!(!plugin.is_null());
+        let p = &*plugin;
+        assert!(p.init.unwrap()(plugin));
+        let ports = p.get_extension.unwrap()(plugin, CLAP_EXT_AUDIO_PORTS.as_ptr())
+            as *const clap_plugin_audio_ports;
+        assert!(!ports.is_null());
+        assert_eq!((*ports).count.unwrap()(plugin, false), 1);
+        assert_eq!((*ports).count.unwrap()(plugin, true), 1);
+        let latency = p.get_extension.unwrap()(plugin, CLAP_EXT_LATENCY.as_ptr())
+            as *const clap_plugin_latency;
+        assert!(!latency.is_null());
+        let state =
+            p.get_extension.unwrap()(plugin, CLAP_EXT_STATE.as_ptr()) as *const clap_plugin_state;
+        assert!(!state.is_null());
+        let state = &*state;
+        let save = || {
+            let mut bytes = Vec::new();
+            let stream = clap_ostream {
+                ctx: &mut bytes as *mut Vec<u8> as *mut c_void,
+                write: Some(write),
+            };
+            assert!(state.save.unwrap()(plugin, &stream));
+            bytes
+        };
+        let mut envelope: nih_plug::prelude::PluginState =
+            serde_json::from_slice(&save()[8..]).unwrap();
+        use nih_plug::wrapper::state::ParamValue;
+        // Amount 0 passes the input through the lookahead delay unchanged.
+        envelope.params.insert("amount".into(), ParamValue::F32(0.));
+        envelope
+            .params
+            .insert("target".into(), ParamValue::F32(-20.));
+        envelope.params.insert("from".into(), ParamValue::F32(100.));
+        envelope
+            .params
+            .insert("segment".into(), ParamValue::String("grid".into()));
+        envelope
+            .params
+            .insert("grid".into(), ParamValue::String("1-8".into()));
+        envelope
+            .params
+            .insert("source".into(), ParamValue::String("midi".into()));
+        let encoded = serde_json::to_vec(&envelope).unwrap();
+        let mut framed = (encoded.len() as u64).to_le_bytes().to_vec();
+        framed.extend_from_slice(&encoded);
+        let mut bytes = Cursor::new(framed);
+        let stream = clap_istream {
+            ctx: &mut bytes as *mut Cursor<Vec<u8>> as *mut c_void,
+            read: Some(read),
+        };
+        assert!(state.load.unwrap()(plugin, &stream));
+        let restored: nih_plug::prelude::PluginState =
+            serde_json::from_slice(&save()[8..]).unwrap();
+        assert_eq!(
+            serde_json::to_value(&restored.params).unwrap(),
+            serde_json::to_value(&envelope.params).unwrap()
+        );
+        for rate in [44100., 48000., 96000.] {
+            assert!(p.activate.unwrap()(plugin, rate, 1, 512));
+            let delay = (*latency).get.unwrap()(plugin) as usize;
+            // The tracker's 67 ms, the 100 ms measuring window and the 5 ms ramp.
+            assert!((delay as f64 / rate - 0.172).abs() < 0.005, "{delay}");
+            assert!(p.start_processing.unwrap()(plugin));
+            let total = delay + 9600;
+            let mut position = 0;
+            let (mut energy_in, mut energy_out) = (0f64, 0f64);
+            while position < total {
+                let frames = [1, 127, 512, 31][position % 4].min(total - position);
+                // A 1 kHz tone at amount 0.
+                let tone = |n: usize| {
+                    0.25 * (std::f64::consts::TAU * 1000. * n as f64 / rate).sin() as f32
+                };
+                let mut input_left = [0f32; 512];
+                let mut input_right = [0f32; 512];
+                for i in 0..frames {
+                    input_left[i] = tone(position + i);
+                    input_right[i] = -tone(position + i);
+                }
+                let mut left = [0f32; 512];
+                let mut right = [0f32; 512];
+                let mut in_channels = [input_left.as_mut_ptr(), input_right.as_mut_ptr()];
+                let mut out_channels = [left.as_mut_ptr(), right.as_mut_ptr()];
+                let incoming = clap_audio_buffer {
+                    data32: in_channels.as_mut_ptr(),
+                    data64: ptr::null_mut(),
+                    channel_count: 2,
+                    latency: 0,
+                    constant_mask: 0,
+                };
+                let mut outgoing_audio = clap_audio_buffer {
+                    data32: out_channels.as_mut_ptr(),
+                    data64: ptr::null_mut(),
+                    channel_count: 2,
+                    latency: 0,
+                    constant_mask: 0,
+                };
+                let input = clap_input_events {
+                    ctx: ptr::null_mut(),
+                    size: Some(count),
+                    get: Some(event),
+                };
+                let outgoing = clap_output_events {
+                    ctx: ptr::null_mut(),
+                    try_push: Some(push),
+                };
+                let process = clap_process {
+                    steady_time: position as i64,
+                    frames_count: frames as u32,
+                    transport: ptr::null(),
+                    audio_inputs: &incoming,
+                    audio_outputs: &mut outgoing_audio,
+                    audio_inputs_count: 1,
+                    audio_outputs_count: 1,
+                    in_events: &input,
+                    out_events: &outgoing,
+                };
+                assert_ne!(p.process.unwrap()(plugin, &process), CLAP_PROCESS_ERROR);
+                for i in 0..frames {
+                    let n = position + i;
+                    if n < delay {
+                        assert!(left[i].abs() < 1e-6, "output before the lookahead");
+                    } else if n > delay + 4800 {
+                        energy_in += (tone(n - delay) as f64).powi(2);
+                        energy_out += (left[i] as f64).powi(2) + (right[i] as f64).powi(2);
+                    }
+                }
+                position += frames;
+            }
+            let ratio_db = 10. * (energy_out / (2. * energy_in)).log10();
+            assert!(ratio_db.abs() < 0.2, "{ratio_db}");
+            p.stop_processing.unwrap()(plugin);
+            p.deactivate.unwrap()(plugin);
+        }
+        p.destroy.unwrap()(plugin);
+        entry.deinit.unwrap()();
+    }
+}

plugins/ballast/ui/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "ballast-ui"
+version = "0.1.0"
+edition.workspace = true
+license.workspace = true
+
+[dependencies]
+egui = "0.31.1"
+ballast-core = { path = "../core" }
+common-ui = { path = "../../common/ui" }
+common-dsp = { path = "../../common/dsp" }

plugins/ballast/ui/src/lib.rs

@@ -0,0 +1,376 @@
+//! Ballast editor, shared by the CLAP wrapper and the headless renderer.
+use ballast_core::{
+    AnalyzerFrame, Grid, Segment, Settings, Source, FROM_MAX, FROM_MIN, HISTORY, RANGE_MAX,
+    TARGET_MAX, TARGET_MIN,
+};
+use common_ui::*;
+use egui::{self, Color32, FontId, Pos2, Rect, RichText, Sense, Stroke, Vec2};
+
+pub use common_ui::style;
+pub const WIDTH: u32 = 980;
+pub const HEIGHT: u32 = 660;
+
+pub struct State {
+    pub analyzer: AnalyzerFrame,
+    /// Set by the Learn button; the wrapper passes it to the engine and clears it.
+    pub learn_request: bool,
+    /// The last Learn result already applied. None until the first frame arrives, so an old
+    /// result is not applied again when the editor opens.
+    learn_seen: Option<u32>,
+    learned: Option<f32>,
+    /// True while a pointer button is held, so knob drags become one host gesture.
+    pub gesture_active: bool,
+    pub help: String,
+}
+impl Default for State {
+    fn default() -> Self {
+        Self {
+            analyzer: AnalyzerFrame::default(),
+            learn_request: false,
+            learn_seen: None,
+            learned: None,
+            gesture_active: false,
+            help: DEFAULT_HELP.into(),
+        }
+    }
+}
+const DEFAULT_HELP: &str = "Put Ballast on the bass after its sound design. Press LEARN on the \
+                            switch-up that sits right, or set Target.";
+impl State {
+    pub fn accept_frame(&mut self, frame: AnalyzerFrame) {
+        match self.learn_seen {
+            Some(id) if id != frame.learn_id && frame.learned.is_finite() => {
+                self.learned = Some(frame.learned);
+            }
+            _ => {}
+        }
+        self.learn_seen = Some(frame.learn_id);
+        self.analyzer = frame;
+    }
+}
+fn hint(r: &egui::Response, state: &mut State, text: &str) {
+    if r.hovered() || r.has_focus() {
+        state.help = text.into();
+    }
+}
+#[allow(clippy::too_many_arguments)]
+fn knob(
+    ui: &mut egui::Ui,
+    state: &mut State,
+    name: &str,
+    value: &mut f32,
+    range: std::ops::RangeInclusive<f32>,
+    default: f32,
+    unit: &str,
+    help: &str,
+) {
+    ui.vertical_centered(|ui| {
+        let r = rotary(ui, name, value, range, default, unit, 72., ACCENT);
+        hint(&r, state, help);
+    });
+}
+
+const LOW: f32 = -42.;
+const HIGH: f32 = 0.;
+
+/// The last parts: their loudness in (bars), after Ballast (marks) and the target.
+fn parts(ui: &mut egui::Ui, settings: &Settings, frame: &AnalyzerFrame, height: f32) {
+    let (rect, _) = ui.allocate_exact_size(Vec2::new(ui.available_width(), height), Sense::hover());
+    let p = ui.painter_at(rect);
+    p.rect_filled(rect, 2., SCREEN);
+    p.text(
+        rect.left_top() + Vec2::new(10., 8.),
+        egui::Align2::LEFT_TOP,
+        format!("LAST {HISTORY} PARTS · LOUDNESS OF THE FIRST 100 MS"),
+        FontId::proportional(11.),
+        MUTED,
+    );
+    p.text(
+        rect.right_top() + Vec2::new(-12., 8.),
+        egui::Align2::RIGHT_TOP,
+        "bar: in · mark: out",
+        FontId::proportional(11.),
+        MUTED,
+    );
+    let area = Rect::from_min_max(
+        rect.left_top() + Vec2::new(44., 30.),
+        rect.right_bottom() - Vec2::new(12., 12.),
+    );
+    let y = |lufs: f32| {
+        let t = ((lufs - LOW) / (HIGH - LOW)).clamp(0., 1.);
+        area.bottom() - t * area.height()
+    };
+    for db in [-36., -24., -12., 0.] {
+        p.line_segment(
+            [
+                Pos2::new(area.left(), y(db)),
+                Pos2::new(area.right(), y(db)),
+            ],
+            Stroke::new(1.0_f32, Color32::from_rgb(32, 35, 40)),
+        );
+        p.text(
+            Pos2::new(area.left() - 6., y(db)),
+            egui::Align2::RIGHT_CENTER,
+            format!("{db:.0}"),
+            FontId::monospace(10.),
+            DIM,
+        );
+    }
+    let column = area.width() / HISTORY as f32;
+    // Newest part on the right.
+    let offset = HISTORY - frame.count;
+    for i in 0..frame.count {
+        let part = frame.history[i];
+        let x = area.left() + column * (offset + i) as f32;
+        let bar = Rect::from_min_max(
+            Pos2::new(x + column * 0.2, y(part.loudness)),
+            Pos2::new(x + column * 0.8, area.bottom()),
+        );
+        let color = if part.gated {
+            DIM.gamma_multiply(0.6)
+        } else {
+            STEEL.gamma_multiply(0.45)
+        };
+        p.rect_filled(bar, 1., color);
+        if !part.gated {
+            let out = y(part.loudness + part.gain);
+            p.line_segment(
+                [
+                    Pos2::new(x + column * 0.1, out),
+                    Pos2::new(x + column * 0.9, out),
+                ],
+                Stroke::new(3.0_f32, ACCENT),
+            );
+        }
+    }
+    let t = y(settings.target);
+    p.line_segment(
+        [Pos2::new(area.left(), t), Pos2::new(area.right(), t)],
+        Stroke::new(1.0_f32, ACCENT.gamma_multiply(0.5)),
+    );
+    p.text(
+        Pos2::new(area.left() + 4., t - 3.),
+        egui::Align2::LEFT_BOTTOM,
+        format!("TARGET {:.1} LUFS", settings.target),
+        FontId::proportional(10.),
+        ACCENT,
+    );
+    p.rect_stroke(
+        rect,
+        2.,
+        Stroke::new(1.0_f32, EDGE),
+        egui::StrokeKind::Inside,
+    );
+}
+
+pub fn show(ui: &mut egui::Ui, settings: &mut Settings, state: &mut State) {
+    backdrop(ui);
+    state.help = DEFAULT_HELP.into();
+    state.gesture_active = ui.input(|i| i.pointer.any_down());
+    if let Some(l) = state.learned.take() {
+        settings.target = l.clamp(TARGET_MIN, TARGET_MAX);
+    }
+    ui.add_space(2.);
+    header(ui, "BALLAST", "SWITCH-UP LEVELLER", |ui| {
+        let r = ui
+            .selectable_label(settings.bypass, RichText::new("BYPASS").size(13.))
+            .on_hover_text("Crossfade to the delayed dry signal.");
+        if r.clicked() {
+            settings.bypass = !settings.bypass;
+        }
+        ui.separator();
+        if settings.segment == Segment::Notes {
+            for (source, label) in [(Source::Midi, "MIDI"), (Source::Audio, "AUDIO")] {
+                let r =
+                    ui.selectable_label(settings.source == source, RichText::new(label).size(13.));
+                if r.clicked() {
+                    settings.source = source;
+                }
+            }
+            caption(ui, "NOTES FROM");
+            ui.separator();
+        }
+        for (segment, label) in [(Segment::Grid, "GRID"), (Segment::Notes, "NOTES")] {
+            let r =
+                ui.selectable_label(settings.segment == segment, RichText::new(label).size(13.));
+            if r.clicked() {
+                settings.segment = segment;
+            }
+        }
+        caption(ui, "PARTS FROM");
+    });
+    ui.add_space(6.);
+    let frame = state.analyzer;
+    ui.horizontal_top(|ui| {
+        panel(ui, |ui| {
+            ui.set_width(250.);
+            ui.set_min_height(TOP);
+            ui.vertical(|ui| readings(ui, settings, state, &frame));
+        });
+        ui.add_space(4.);
+        panel(ui, |ui| {
+            ui.set_width(ui.available_width());
+            parts(ui, settings, &frame, TOP);
+        });
+    });
+    ui.add_space(6.);
+    panel(ui, |ui| {
+        ui.set_width(ui.available_width());
+        ui.vertical(|ui| controls(ui, settings, state));
+    });
+    ui.separator();
+    ui.label(RichText::new(&state.help).color(MUTED));
+}
+const TOP: f32 = 300.;
+
+fn readings(ui: &mut egui::Ui, settings: &Settings, state: &mut State, frame: &AnalyzerFrame) {
+    caption(ui, "SPREAD OF THE LAST PARTS");
+    let known = frame.spread_in.is_finite();
+    ui.label(
+        RichText::new(if known {
+            format!("{:.1} · {:.1} dB", frame.spread_in, frame.spread_out)
+        } else {
+            "—".into()
+        })
+        .font(FontId::new(34., egui::FontFamily::Name("medium".into())))
+        .color(if known { TEXT } else { DIM }),
+    );
+    ui.label(
+        RichText::new("in · out, standard deviation")
+            .size(12.)
+            .color(MUTED),
+    );
+    ui.add_space(12.);
+    readout(ui, "GAIN NOW", format!("{:+.1} dB", frame.gain), ACCENT);
+    readout(ui, "TARGET", format!("{:.1} LUFS", settings.target), TEXT);
+    let label = if frame.learning || state.learn_request {
+        "LISTENING"
+    } else {
+        "LEARN"
+    };
+    let r = ui.selectable_label(
+        frame.learning || state.learn_request,
+        RichText::new(label).size(13.),
+    );
+    if r.clicked() {
+        state.learn_request = true;
+    }
+    hint(
+        &r,
+        state,
+        "Takes the loudness of the next part over the gate as the target. Press it just \
+         before the switch-up that sits right in the mix.",
+    );
+    ui.add_space(10.);
+    ui.label(
+        RichText::new(format!(
+            "{:.0} ms lookahead · {}",
+            frame.latency as f32 / frame.sample_rate.max(1.) * 1000.,
+            match settings.segment {
+                Segment::Notes => match settings.source {
+                    Source::Audio => "parts at detected notes".to_string(),
+                    Source::Midi => "parts at MIDI notes".to_string(),
+                },
+                Segment::Grid => format!(
+                    "grid at {:.1} BPM, {}",
+                    frame.tempo,
+                    if frame.synced {
+                        "host transport"
+                    } else {
+                        "free running"
+                    }
+                ),
+            }
+        ))
+        .size(12.)
+        .color(MUTED),
+    );
+}
+
+fn controls(ui: &mut egui::Ui, settings: &mut Settings, state: &mut State) {
+    let d = Settings::default();
+    if settings.segment == Segment::Grid {
+        ui.horizontal(|ui| {
+            caption(ui, "ONE PART EVERY");
+            ui.add_space(6.);
+            for grid in Grid::ALL {
+                let r = ui
+                    .selectable_label(settings.grid == grid, RichText::new(grid.label()).size(13.));
+                if r.clicked() {
+                    settings.grid = grid;
+                }
+                hint(
+                    &r,
+                    state,
+                    "A new part starts on every line of this grid, also when the note does not \
+                     change.",
+                );
+            }
+        });
+        ui.add_space(8.);
+        ui.separator();
+    }
+    ui.columns(6, |c| {
+        knob(
+            &mut c[0],
+            state,
+            "Target",
+            &mut settings.target,
+            TARGET_MIN..=TARGET_MAX,
+            d.target,
+            " LUFS",
+            "Loudness every part lands at, over its first 100 ms.",
+        );
+        knob(
+            &mut c[1],
+            state,
+            "Amount",
+            &mut settings.amount,
+            0. ..=100.,
+            d.amount,
+            " %",
+            "Share of the correction. 50 % halves the differences between parts.",
+        );
+        knob(
+            &mut c[2],
+            state,
+            "Range",
+            &mut settings.range,
+            0. ..=RANGE_MAX,
+            d.range,
+            " dB",
+            "Most boost or cut a part gets.",
+        );
+        knob(
+            &mut c[3],
+            state,
+            "Measure from",
+            &mut settings.from,
+            FROM_MIN..=FROM_MAX,
+            d.from,
+            " Hz",
+            "The measurement hears only what is above this. Set it to Anvil's Split when \
+             Anvil makes the sub; the gain still applies to the whole signal.",
+        );
+        knob(
+            &mut c[4],
+            state,
+            "Gate",
+            &mut settings.gate,
+            -60. ..=-20.,
+            d.gate,
+            " dB",
+            "Note-start threshold, and the loudness under which a part keeps the last gain.",
+        );
+        knob(
+            &mut c[5],
+            state,
+            "Output",
+            &mut settings.output,
+            -12. ..=12.,
+            d.output,
+            " dB",
+            "Output trim.",
+        );
+    });
+}

plugins/catalog.json

@@ -165,5 +165,39 @@
       "braze-core",
       "braze-ui"
     ]
+  },
+  "quench": {
+    "name": "Quench",
+    "description": "Clips the top as hard as you like while the sub passes clean",
+    "manifest": "plugins/quench/plugin/Cargo.toml",
+    "library": "quench",
+    "documentation": "docs/quench",
+    "clap_id": "io.narl.bass-foundry.quench",
+    "licenses": {
+      "plugins/common/ui/assets/OFL.txt": "licenses/Roboto-OFL.txt"
+    },
+    "packages": [
+      "common-ui",
+      "common-dsp",
+      "quench-core",
+      "quench-ui"
+    ]
+  },
+  "ballast": {
+    "name": "Ballast",
+    "description": "Levels every note or switch-up to one loudness with a single gain each",
+    "manifest": "plugins/ballast/plugin/Cargo.toml",
+    "library": "ballast",
+    "documentation": "docs/ballast",
+    "clap_id": "io.narl.bass-foundry.ballast",
+    "licenses": {
+      "plugins/common/ui/assets/OFL.txt": "licenses/Roboto-OFL.txt"
+    },
+    "packages": [
+      "common-ui",
+      "common-dsp",
+      "ballast-core",
+      "ballast-ui"
+    ]
   }
 }

plugins/common/dsp/src/lib.rs

@@ -1,4 +1,5 @@
 //! Shared allocation-free DSP building blocks: filters, pitch detection, notes, WAV files.
+pub mod loudness;
 pub mod meter;
 pub mod oversample;
 pub mod svf;

plugins/common/dsp/src/loudness.rs

@@ -0,0 +1,71 @@
+//! ITU-R BS.1770 K-weighting: the pre-filter (a high shelf for the head) and the RLB high-pass.
+//! Mean square of the weighted signal, summed over channels, gives the loudness in LUFS as
+//! −0.691 + 10·log10(sum). Coefficients come from the standard's analog prototypes, so any
+//! sample rate is exact, not only 48 kHz.
+
+/// Biquad in transposed direct form II, in f64: the RLB pole sits close to 1 at high rates.
+#[derive(Clone, Copy, Debug, Default)]
+struct Stage {
+    b: [f64; 3],
+    a: [f64; 2],
+    z: [f64; 2],
+}
+impl Stage {
+    #[inline]
+    fn process(&mut self, x: f64) -> f64 {
+        let y = self.b[0] * x + self.z[0];
+        self.z[0] = self.b[1] * x - self.a[0] * y + self.z[1];
+        self.z[1] = self.b[2] * x - self.a[1] * y;
+        y
+    }
+}
+
+/// One channel of K-weighting. Allocation-free.
+#[derive(Clone, Copy, Debug)]
+pub struct KWeighting {
+    shelf: Stage,
+    high: Stage,
+}
+impl KWeighting {
+    pub fn new(rate: f32) -> Self {
+        let rate = rate as f64;
+        // Pre-filter: high shelf of about +4 dB above 1.7 kHz.
+        let (f0, g, q) = (1681.974450955533, 3.999843853973347, 0.7071752369554196);
+        let k = (std::f64::consts::PI * f0 / rate).tan();
+        let vh = 10f64.powf(g / 20.);
+        let vb = vh.powf(0.4996667741545416);
+        let a0 = 1. + k / q + k * k;
+        let shelf = Stage {
+            b: [
+                (vh + vb * k / q + k * k) / a0,
+                2. * (k * k - vh) / a0,
+                (vh - vb * k / q + k * k) / a0,
+            ],
+            a: [2. * (k * k - 1.) / a0, (1. - k / q + k * k) / a0],
+            z: [0.; 2],
+        };
+        // RLB: second-order high-pass at 38 Hz.
+        let (f0, q) = (38.13547087602444, 0.5003270373238773);
+        let k = (std::f64::consts::PI * f0 / rate).tan();
+        let a0 = 1. + k / q + k * k;
+        let high = Stage {
+            b: [1., -2., 1.],
+            a: [2. * (k * k - 1.) / a0, (1. - k / q + k * k) / a0],
+            z: [0.; 2],
+        };
+        Self { shelf, high }
+    }
+    #[inline]
+    pub fn process(&mut self, x: f32) -> f32 {
+        self.high.process(self.shelf.process(x as f64)) as f32
+    }
+    pub fn reset(&mut self) {
+        self.shelf.z = [0.; 2];
+        self.high.z = [0.; 2];
+    }
+}
+
+/// Loudness in LUFS of a mean square summed over channels.
+pub fn lufs(mean_square: f64) -> f32 {
+    (-0.691 + 10. * mean_square.max(1e-20).log10()) as f32
+}

plugins/common/dsp/tests/dsp.rs

@@ -80,3 +80,29 @@ fn wave_round_trip_keeps_root_and_wavetable_chunks() {
     assert_eq!(wav::decode(&bytes).unwrap(), w);
     assert!(wav::decode(&bytes[..40]).is_err());
 }
+
+#[test]
+fn k_weighting_reads_a_full_scale_997_hz_sine_at_minus_3_lufs() {
+    use common_dsp::loudness::{lufs, KWeighting};
+    let level = |rate: f32, hz: f64| {
+        let mut k = KWeighting::new(rate);
+        let n = rate as usize;
+        let mut sum = 0f64;
+        for i in 0..2 * n {
+            let x = (std::f64::consts::TAU * hz * i as f64 / rate as f64).sin() as f32;
+            let y = k.process(x) as f64;
+            if i >= n {
+                sum += y * y;
+            }
+        }
+        lufs(sum / n as f64)
+    };
+    // BS.1770-4: a 0 dBFS 997 Hz sine in one channel reads −3.01 LKFS, at every rate.
+    for rate in [44100., 48000., 96000., 192000.] {
+        let got = level(rate, 997.);
+        // BS.1770 allows meters 0.1 LU; the prototypes land within 0.03 up to 192 kHz.
+        assert!((got + 3.01).abs() < 0.05, "{rate}: {got}");
+    }
+    // The RLB high-pass counts a 30 Hz sub much less than the mids.
+    assert!(level(48000., 30.) < level(48000., 997.) - 5.);
+}

plugins/quench/core/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "quench-core"
+version = "0.1.0"
+edition.workspace = true
+license.workspace = true
+
+[dependencies]
+common-dsp = { path = "../../common/dsp" }
+serde = { workspace = true }
+
+[dev-dependencies]
+serde_json = { workspace = true }

plugins/quench/core/src/lib.rs

@@ -0,0 +1,422 @@
+//! A clipper that leaves the sub alone.
+//!
+//! A plain clipper clips the sum of sub and top. Near the sub's peaks only one side of the top
+//! gets clipped, so the clipping takes energy out at the sub's rate: the sub loses level and
+//! the low band fills with products that were not in the mix.
+//!
+//! Quench splits the signal with a Linkwitz–Riley crossover. The sub passes untouched. The
+//! top is clipped symmetrically at the room the sub leaves under the ceiling: the ceiling
+//! minus the sub's held peak. Holding the peak through the sub's cycle keeps the top's clip
+//! level steady, so the top is not pumped at the sub's rate. What the clip removes is then
+//! high-passed at the split, so its products below the split do not reach the low band.
+//! High-passing lets a few peaks overshoot; two correction passes clip those and high-pass the
+//! correction again. A hard clip at the ceiling, still oversampled, takes the small rest, and a
+//! safety clip after the downsampler catches its ringing.
+//!
+//! Everything runs at 4× oversampling. Plain clipping of the same signal runs alongside, for
+//! the Plain monitor and for the meter that compares how much each changes the low band.
+mod settings;
+use common_dsp::oversample::Oversampler;
+use common_dsp::svf::{Svf, SvfCoef};
+use common_dsp::{coefficient, db_to_gain, gain_to_db};
+pub use settings::{Settings, CEILING_MIN, DRIVE_MAX, HOLD_MAX, HOLD_MIN, SPLIT_MAX, SPLIT_MIN};
+
+const Q: f32 = std::f32::consts::FRAC_1_SQRT_2;
+const FACTOR: usize = Oversampler::FACTOR;
+/// Correction passes after the top's clip.
+pub const PASSES: usize = 2;
+/// Points in the scope, each the extremes of `SCOPE_STEP` samples.
+pub const SCOPE: usize = 256;
+const SCOPE_STEP: usize = 8;
+const SCOPE_LEN: usize = SCOPE * SCOPE_STEP;
+/// Averaging time of the low-band meter.
+const METER_MS: f32 = 300.;
+const SMOOTH_MS: f32 = 20.;
+const BYPASS_MS: f32 = 10.;
+pub const SILENT: f32 = -120.;
+/// Below this sub energy (−50 dB RMS) the low-band meter has nothing to compare against.
+const SUB_FLOOR: f32 = 1e-5;
+
+/// What the output plays. Monitors are not saved.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum Monitor {
+    #[default]
+    Quench,
+    /// A plain clipper at the same Drive, Ceiling and Soft, for comparison.
+    Plain,
+    /// What Quench takes away: its output minus the unclipped input.
+    Delta,
+}
+
+#[derive(Clone, Copy, Debug)]
+pub struct AnalyzerFrame {
+    /// Peak after Drive, in dBFS, since the last frame.
+    pub input_peak: f32,
+    pub output_peak: f32,
+    /// Peak of the sub band after Drive.
+    pub sub_peak: f32,
+    /// How far the top's loudest peak went past its clip level, in dB. 0 when nothing clipped.
+    pub top_clip: f32,
+    /// How far the final safety clip reached, in dB. 0 when it did nothing.
+    pub safety: f32,
+    /// Change of the low band below the split, against the sub, in dB: Quench and a plain clip
+    /// of the same signal. NaN without a sub.
+    pub low_quench: f32,
+    pub low_plain: f32,
+    pub ceiling: f32,
+    pub latency: u32,
+    pub sample_rate: f32,
+    /// Latest output of the selected monitor (oldest first), as extremes per point.
+    pub scope_min: [f32; SCOPE],
+    pub scope_max: [f32; SCOPE],
+    /// The sub band and the room it leaves the top, at the same points.
+    pub scope_sub: [f32; SCOPE],
+    pub scope_room: [f32; SCOPE],
+}
+impl Default for AnalyzerFrame {
+    fn default() -> Self {
+        Self {
+            input_peak: SILENT,
+            output_peak: SILENT,
+            sub_peak: SILENT,
+            top_clip: 0.,
+            safety: 0.,
+            low_quench: f32::NAN,
+            low_plain: f32::NAN,
+            ceiling: Settings::default().ceiling,
+            latency: Oversampler::latency() as u32,
+            sample_rate: 48000.,
+            scope_min: [0.; SCOPE],
+            scope_max: [0.; SCOPE],
+            scope_sub: [0.; SCOPE],
+            scope_room: [0.; SCOPE],
+        }
+    }
+}
+
+/// Clips `h` to ±`limit`. `knee` (0–1) is the share of the range below `limit` that bends:
+/// 0 is a hard clip. Never exceeds `limit`.
+#[inline]
+pub fn shape(h: f32, limit: f32, knee: f32) -> f32 {
+    let a = limit * (1. - knee);
+    let m = h.abs();
+    if m <= a {
+        return h;
+    }
+    let w = limit - a;
+    let y = if w <= 1e-9 {
+        limit
+    } else {
+        a + w * ((m - a) / w).tanh()
+    };
+    y.min(limit).copysign(h)
+}
+
+/// One band of a Linkwitz–Riley crossover: two Butterworth stages.
+#[inline]
+fn lr4(f: &mut [Svf; 2], c: &SvfCoef, v: f32) -> f32 {
+    let v = f[0].process(c, v);
+    f[1].process(c, v)
+}
+
+#[derive(Clone, Copy)]
+struct Coefs {
+    low: SvfCoef,
+    high: SvfCoef,
+    /// Held-peak length in oversampled samples, and its release per sample after that.
+    hold: usize,
+    release: f32,
+    knee: f32,
+}
+impl Coefs {
+    fn new(rate: f32, s: &Settings) -> Self {
+        let fast = rate * FACTOR as f32;
+        Self {
+            low: SvfCoef::lowpass(fast, s.split, Q),
+            high: SvfCoef::highpass(fast, s.split, Q),
+            hold: (s.hold * 0.001 * fast) as usize,
+            release: 1. - coefficient(fast, s.hold),
+            knee: s.soft * 0.01,
+        }
+    }
+}
+
+struct Channel {
+    os: Oversampler,
+    low: [Svf; 2],
+    high: [Svf; 2],
+    /// High-passes what the top's clip removed.
+    error: Svf,
+    passes: [Svf; PASSES],
+    env: f32,
+    hold_left: usize,
+    meter_quench: [Svf; 2],
+    meter_plain: [Svf; 2],
+    /// The input delayed by the latency, for bypass.
+    dry: Vec<f32>,
+}
+impl Channel {
+    fn new(latency: usize) -> Self {
+        Self {
+            os: Oversampler::new(),
+            low: [Svf::default(); 2],
+            high: [Svf::default(); 2],
+            error: Svf::default(),
+            passes: [Svf::default(); PASSES],
+            env: 0.,
+            hold_left: 0,
+            meter_quench: [Svf::default(); 2],
+            meter_plain: [Svf::default(); 2],
+            dry: vec![0.; latency + 1],
+        }
+    }
+    fn reset(&mut self) {
+        self.os.reset();
+        for f in self
+            .low
+            .iter_mut()
+            .chain(self.high.iter_mut())
+            .chain(self.passes.iter_mut())
+            .chain(self.meter_quench.iter_mut())
+            .chain(self.meter_plain.iter_mut())
+        {
+            f.reset();
+        }
+        self.error.reset();
+        self.env = 0.;
+        self.hold_left = 0;
+        self.dry.fill(0.);
+    }
+}
+
+/// Peaks and energies gathered between two analyzer frames.
+#[derive(Clone, Copy, Default)]
+struct Gather {
+    input: f32,
+    output: f32,
+    sub: f32,
+    /// Largest ratio of the top to its room.
+    top: f32,
+    safety: f32,
+}
+
+pub struct Engine {
+    rate: f32,
+    channels: usize,
+    settings: Settings,
+    coefs: Coefs,
+    channel: [Channel; 2],
+    drive: f32,
+    ceiling: f32,
+    bypass: f32,
+    primed: bool,
+    smooth: f32,
+    fade: f32,
+    meter: f32,
+    dry_at: usize,
+    energy_quench: f32,
+    energy_plain: f32,
+    energy_sub: f32,
+    gather: Gather,
+    scope: [[f32; 4]; SCOPE_LEN],
+    scope_at: usize,
+}
+impl Engine {
+    pub fn new(rate: f32, channels: usize) -> Result<Self, &'static str> {
+        if !(8000.0..=384000.).contains(&rate) {
+            return Err("unsupported sample rate");
+        }
+        if !(1..=2).contains(&channels) {
+            return Err("unsupported channel count");
+        }
+        let settings = Settings::default();
+        let latency = Oversampler::latency();
+        Ok(Self {
+            rate,
+            channels,
+            settings,
+            coefs: Coefs::new(rate, &settings),
+            channel: [Channel::new(latency), Channel::new(latency)],
+            drive: 1.,
+            ceiling: db_to_gain(settings.ceiling),
+            bypass: 0.,
+            primed: false,
+            smooth: coefficient(rate, SMOOTH_MS),
+            fade: coefficient(rate, BYPASS_MS),
+            meter: coefficient(rate * FACTOR as f32, METER_MS),
+            dry_at: 0,
+            energy_quench: 0.,
+            energy_plain: 0.,
+            energy_sub: 0.,
+            gather: Gather::default(),
+            scope: [[0.; 4]; SCOPE_LEN],
+            scope_at: 0,
+        })
+    }
+    pub fn channels(&self) -> usize {
+        self.channels
+    }
+    pub fn latency_samples(&self) -> u32 {
+        Oversampler::latency() as u32
+    }
+    pub fn settings(&self) -> Settings {
+        self.settings
+    }
+    pub fn set_settings(&mut self, s: Settings) -> Result<(), &'static str> {
+        s.validate()?;
+        if s != self.settings || !self.primed {
+            self.coefs = Coefs::new(self.rate, &s);
+        }
+        self.settings = s;
+        if !self.primed {
+            // The first settings after a start take effect at once instead of ramping.
+            self.drive = db_to_gain(s.drive);
+            self.ceiling = db_to_gain(s.ceiling);
+            self.bypass = if s.bypass { 1. } else { 0. };
+            self.primed = true;
+        }
+        Ok(())
+    }
+    pub fn reset(&mut self) {
+        for c in &mut self.channel {
+            c.reset();
+        }
+        self.dry_at = 0;
+        self.energy_quench = 0.;
+        self.energy_plain = 0.;
+        self.energy_sub = 0.;
+        self.gather = Gather::default();
+        self.scope = [[0.; 4]; SCOPE_LEN];
+        self.scope_at = 0;
+        self.primed = false;
+        let s = self.settings;
+        let _ = self.set_settings(s);
+    }
+
+    pub fn process_sample(&mut self, x: [f32; 2], monitor: Monitor) -> [f32; 2] {
+        let s = self.settings;
+        self.drive += self.smooth * (db_to_gain(s.drive) - self.drive);
+        self.ceiling += self.smooth * (db_to_gain(s.ceiling) - self.ceiling);
+        self.bypass += self.fade * (if s.bypass { 1. } else { 0. } - self.bypass);
+        let (c, k, drive) = (self.ceiling, self.coefs, self.drive);
+        let mut out = [0.; 2];
+        let mut point = [f32::MAX, f32::MIN, 0., 0.];
+        let n = self.channel[0].dry.len();
+        for (ch, &input) in x.iter().enumerate().take(self.channels) {
+            let chan = &mut self.channel[ch];
+            let driven = input * drive;
+            self.gather.input = self.gather.input.max(driven.abs());
+            let up = chan.os.up(driven);
+            let mut picked = [0.; FACTOR];
+            for (j, &v) in up.iter().enumerate() {
+                let low = lr4(&mut chan.low, &k.low, v);
+                let high = lr4(&mut chan.high, &k.high, v);
+                // The sub's held peak decides the top's room.
+                let a = low.abs();
+                if a >= chan.env {
+                    chan.env = a;
+                    chan.hold_left = k.hold;
+                } else if chan.hold_left > 0 {
+                    chan.hold_left -= 1;
+                } else {
+                    chan.env = a.max(chan.env * k.release);
+                }
+                let room = (c - chan.env).max(0.);
+                let top = shape(high, room, k.knee);
+                let reference = low + high;
+                let mut y = reference + chan.error.process(&k.high, top - high);
+                for p in &mut chan.passes {
+                    y += p.process(&k.high, y.clamp(-c, c) - y);
+                }
+                // What the passes leave over the ceiling is small; clipping it here, still
+                // oversampled, leaves the safety clip after the downsampler almost idle.
+                let y = y.clamp(-c, c);
+                let plain = shape(reference, c, k.knee);
+                let lq = lr4(&mut chan.meter_quench, &k.low, y - reference);
+                let lp = lr4(&mut chan.meter_plain, &k.low, plain - reference);
+                self.energy_quench += self.meter * (lq * lq - self.energy_quench);
+                self.energy_plain += self.meter * (lp * lp - self.energy_plain);
+                self.energy_sub += self.meter * (low * low - self.energy_sub);
+                self.gather.sub = self.gather.sub.max(a);
+                if high.abs() > room {
+                    let ratio = high.abs() / room.max(c * 1e-3);
+                    self.gather.top = self.gather.top.max(ratio);
+                }
+                picked[j] = match monitor {
+                    Monitor::Quench => y,
+                    Monitor::Plain => plain,
+                    Monitor::Delta => y - reference,
+                };
+                if ch == 0 {
+                    point[0] = point[0].min(picked[j]);
+                    point[1] = point[1].max(picked[j]);
+                    point[2] = low;
+                    point[3] = room;
+                }
+            }
+            let mut o = chan.os.down(picked);
+            if monitor != Monitor::Delta && o.abs() > c {
+                self.gather.safety = self.gather.safety.max(o.abs() / c);
+                o = o.clamp(-c, c);
+            }
+            let dry = chan.dry[(self.dry_at + 1) % n];
+            chan.dry[self.dry_at] = input;
+            o = if self.bypass >= 1. - 1e-6 {
+                dry
+            } else {
+                o + self.bypass * (dry - o)
+            };
+            self.gather.output = self.gather.output.max(o.abs());
+            out[ch] = o;
+        }
+        self.dry_at = (self.dry_at + 1) % n;
+        self.scope[self.scope_at] = point;
+        self.scope_at = (self.scope_at + 1) % SCOPE_LEN;
+        out
+    }
+
+    /// Readings since the last call. Never allocates.
+    pub fn take_analyzer(&mut self) -> AnalyzerFrame {
+        let g = std::mem::take(&mut self.gather);
+        let db = |v: f32| if v > 0. { gain_to_db(v) } else { SILENT };
+        let relative = |e: f32| {
+            if self.energy_sub > SUB_FLOOR {
+                10. * (e.max(1e-20) / self.energy_sub).log10()
+            } else {
+                f32::NAN
+            }
+        };
+        let mut f = AnalyzerFrame {
+            input_peak: db(g.input),
+            output_peak: db(g.output),
+            sub_peak: db(g.sub),
+            top_clip: if g.top > 1. { gain_to_db(g.top) } else { 0. },
+            safety: if g.safety > 1. {
+                gain_to_db(g.safety)
+            } else {
+                0.
+            },
+            low_quench: relative(self.energy_quench),
+            low_plain: relative(self.energy_plain),
+            ceiling: self.settings.ceiling,
+            latency: self.latency_samples(),
+            sample_rate: self.rate,
+            ..AnalyzerFrame::default()
+        };
+        for i in 0..SCOPE {
+            let (mut lo, mut hi) = (f32::MAX, f32::MIN);
+            let mut last = [0.; 4];
+            for j in 0..SCOPE_STEP {
+                let v = self.scope[(self.scope_at + i * SCOPE_STEP + j) % SCOPE_LEN];
+                lo = lo.min(v[0]);
+                hi = hi.max(v[1]);
+                last = v;
+            }
+            f.scope_min[i] = if lo <= hi { lo } else { 0. };
+            f.scope_max[i] = if lo <= hi { hi } else { 0. };
+            f.scope_sub[i] = last[2];
+            f.scope_room[i] = last[3];
+        }
+        f
+    }
+}

plugins/quench/core/src/settings.rs

@@ -0,0 +1,58 @@
+//! Host-independent controls. Levels in dB, times in milliseconds, amounts in percent.
+use serde::{Deserialize, Serialize};
+
+pub const DRIVE_MAX: f32 = 24.;
+pub const CEILING_MIN: f32 = -12.;
+pub const SPLIT_MIN: f32 = 40.;
+pub const SPLIT_MAX: f32 = 300.;
+pub const HOLD_MIN: f32 = 10.;
+pub const HOLD_MAX: f32 = 300.;
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq)]
+#[serde(deny_unknown_fields)]
+pub struct Settings {
+    /// Gain into the clipper.
+    pub drive: f32,
+    /// Highest output peak, in dBFS.
+    pub ceiling: f32,
+    /// Everything below this frequency is the sub: it passes without clipping.
+    pub split: f32,
+    /// How long the sub's peak keeps its headroom reserved. Longer than half a period of the
+    /// lowest note keeps the top's clip level steady through the sub's cycle.
+    pub hold: f32,
+    /// Knee of the top's clipper: 0 % is a hard clip, 100 % a soft curve from the start.
+    pub soft: f32,
+    pub bypass: bool,
+}
+impl Default for Settings {
+    fn default() -> Self {
+        Self {
+            drive: 0.,
+            ceiling: -0.3,
+            split: 120.,
+            hold: 60.,
+            soft: 0.,
+            bypass: false,
+        }
+    }
+}
+impl Settings {
+    pub fn validate(&self) -> Result<(), &'static str> {
+        let finite = [self.drive, self.ceiling, self.split, self.hold, self.soft]
+            .iter()
+            .all(|v| v.is_finite());
+        if !finite {
+            return Err("non-finite setting");
+        }
+        let ok = (0.0..=DRIVE_MAX).contains(&self.drive)
+            && (CEILING_MIN..=0.).contains(&self.ceiling)
+            && (SPLIT_MIN..=SPLIT_MAX).contains(&self.split)
+            && (HOLD_MIN..=HOLD_MAX).contains(&self.hold)
+            && (0.0..=100.).contains(&self.soft);
+        if ok {
+            Ok(())
+        } else {
+            Err("setting out of range")
+        }
+    }
+}

plugins/quench/core/tests/dsp.rs

@@ -0,0 +1,300 @@
+use quench_core::{shape, Engine, Monitor, Settings};
+use std::f64::consts::TAU;
+
+const RATE: f32 = 48000.;
+/// Partials of the top: not harmonics of the sub, so their clipping products can be told
+/// apart from the sub's own harmonics.
+const TOPS: [f64; 5] = [437., 611., 1013., 1597., 2399.];
+
+fn top(t: f64) -> f64 {
+    TOPS.iter()
+        .enumerate()
+        .map(|(i, f)| (TAU * f * t + i as f64).sin())
+        .sum::<f64>()
+        / 4.2
+}
+/// Mono render of `seconds` of `signal`, returned as the left channel.
+fn render(
+    engine: &mut Engine,
+    seconds: f32,
+    monitor: Monitor,
+    signal: impl Fn(f64) -> f64,
+) -> Vec<f32> {
+    let n = (seconds * RATE) as usize;
+    (0..n)
+        .map(|i| {
+            let v = signal(i as f64 / RATE as f64) as f32;
+            engine.process_sample([v, v], monitor)[0]
+        })
+        .collect()
+}
+fn engine(s: Settings) -> Engine {
+    let mut e = Engine::new(RATE, 2).unwrap();
+    e.set_settings(s).unwrap();
+    e
+}
+/// Amplitude of `hz` over a whole number of its periods at the end of `x`.
+fn amplitude(x: &[f32], hz: f64) -> f64 {
+    let n = (RATE as f64 / hz * (0.5 * hz).floor()) as usize;
+    let x = &x[x.len() - n..];
+    let (mut re, mut im) = (0., 0.);
+    for (i, &v) in x.iter().enumerate() {
+        let a = TAU * hz * i as f64 / RATE as f64;
+        re += v as f64 * a.cos();
+        im += v as f64 * a.sin();
+    }
+    2. * (re * re + im * im).sqrt() / n as f64
+}
+/// Hann-windowed spectrum magnitude of the last half second, 2 Hz bins up to `top_bin`.
+fn spectrum(x: &[f32], top_bin: usize) -> Vec<f64> {
+    let n = RATE as usize / 2;
+    let x = &x[x.len() - n..];
+    let w: Vec<f64> = (0..n)
+        .map(|i| 0.5 - 0.5 * (TAU * i as f64 / n as f64).cos())
+        .collect();
+    let norm: f64 = w.iter().sum();
+    (0..=top_bin)
+        .map(|b| {
+            let (mut re, mut im) = (0., 0.);
+            for i in 0..n {
+                let a = TAU * b as f64 * i as f64 / n as f64;
+                re += x[i] as f64 * w[i] * a.cos();
+                im += x[i] as f64 * w[i] * a.sin();
+            }
+            2. * (re * re + im * im).sqrt() / norm
+        })
+        .collect()
+}
+/// Everything below 110 Hz except the 50 Hz sub, against the sub, in dB.
+fn low_junk(x: &[f32]) -> f64 {
+    let s = spectrum(x, 55);
+    let junk: f64 = s
+        .iter()
+        .enumerate()
+        .filter(|(b, _)| !(22..=28).contains(b) && *b > 0)
+        .map(|(_, v)| v * v)
+        .sum();
+    let sub: f64 = s[22..=28].iter().map(|v| v * v).sum();
+    10. * (junk / sub).log10()
+}
+fn db(r: f64) -> f64 {
+    20. * r.log10()
+}
+
+#[test]
+fn below_the_ceiling_the_signal_passes_unchanged() {
+    let mut e = engine(Settings::default());
+    let signal = |t: f64| 0.3 * (TAU * 50. * t).sin() + 0.2 * (TAU * 1000. * t).sin();
+    let out = render(&mut e, 1., Monitor::Quench, signal);
+    for (hz, a) in [(50., 0.3), (1000., 0.2)] {
+        let got = db(amplitude(&out, hz) / a);
+        assert!(got.abs() < 0.02, "{hz} Hz: {got:.3} dB");
+    }
+    let f = e.take_analyzer();
+    assert_eq!(f.top_clip, 0.);
+    assert_eq!(f.safety, 0.);
+    let mut e = engine(Settings::default());
+    let delta = render(&mut e, 0.2, Monitor::Delta, signal);
+    assert!(delta.iter().all(|v| v.abs() < 1e-4));
+}
+
+#[test]
+fn the_output_never_passes_the_ceiling() {
+    let mut seed = 1u32;
+    let noise: Vec<f64> = (0..RATE as usize)
+        .map(|_| {
+            seed = seed.wrapping_mul(1664525).wrapping_add(1013904223);
+            (seed >> 8) as f64 / (1u32 << 24) as f64 * 2. - 1.
+        })
+        .collect();
+    for ceiling in [-6., -0.3, 0.] {
+        for soft in [0., 50., 100.] {
+            for monitor in [Monitor::Quench, Monitor::Plain] {
+                let mut e = engine(Settings {
+                    drive: 24.,
+                    ceiling,
+                    soft,
+                    ..Settings::default()
+                });
+                let out = render(&mut e, 1., monitor, |t| {
+                    let i = ((t * RATE as f64) as usize).min(noise.len() - 1);
+                    0.4 * (TAU * 41. * t).sin() + 0.3 * top(t) + 0.2 * noise[i]
+                });
+                let limit = 10f32.powf(ceiling / 20.) * (1. + 1e-6);
+                let peak = out.iter().fold(0f32, |m, v| m.max(v.abs()));
+                assert!(
+                    peak <= limit,
+                    "{ceiling} dB, soft {soft}, {monitor:?}: {peak}"
+                );
+            }
+        }
+    }
+}
+
+#[test]
+fn the_sub_keeps_its_level_and_the_low_band_stays_clean() {
+    // A quiet sub under a top that peaks far over the ceiling: the hard case for a clipper.
+    let signal = |t: f64| 0.3 * (TAU * 50. * t).sin() + 2. * top(t);
+    let mut results = Vec::new();
+    for monitor in [Monitor::Quench, Monitor::Plain] {
+        let mut e = engine(Settings::default());
+        let out = render(&mut e, 1.5, monitor, signal);
+        let sub = db(amplitude(&out, 50.) / 0.3);
+        results.push((sub, low_junk(&out)));
+    }
+    let [(q_sub, q_junk), (p_sub, p_junk)] = [results[0], results[1]];
+    assert!(q_sub.abs() < 0.2, "Quench changes the sub by {q_sub:.2} dB");
+    assert!(
+        p_sub < -0.8,
+        "a plain clip should squash the sub: {p_sub:.2} dB"
+    );
+    assert!(
+        q_junk < p_junk - 10.,
+        "low-band products: Quench {q_junk:.1} dB, plain {p_junk:.1} dB"
+    );
+}
+
+#[test]
+fn the_meter_shows_how_much_less_the_low_band_changes() {
+    let mut e = engine(Settings::default());
+    render(&mut e, 1.5, Monitor::Quench, |t| {
+        0.3 * (TAU * 50. * t).sin() + 2. * top(t)
+    });
+    let f = e.take_analyzer();
+    assert!(
+        f.low_quench < f.low_plain - 10.,
+        "Quench {:.1} dB, plain {:.1} dB",
+        f.low_quench,
+        f.low_plain
+    );
+    assert!(f.top_clip > 6.);
+    // The oversampled clip leaves the safety clip after the downsampler almost idle.
+    assert!(f.safety < 0.2, "{}", f.safety);
+    let mut e = engine(Settings::default());
+    render(&mut e, 0.5, Monitor::Quench, |t| {
+        0.5 * (TAU * 1000. * t).sin()
+    });
+    assert!(
+        e.take_analyzer().low_quench.is_nan(),
+        "no sub, nothing to compare"
+    );
+}
+
+#[test]
+fn a_sub_over_the_ceiling_leaves_no_room_and_is_still_limited() {
+    let mut e = engine(Settings {
+        ceiling: -6.,
+        ..Settings::default()
+    });
+    let out = render(&mut e, 1., Monitor::Quench, |t| {
+        0.8 * (TAU * 50. * t).sin() + 0.3 * top(t)
+    });
+    let f = e.take_analyzer();
+    assert!(f.sub_peak > -6., "{}", f.sub_peak);
+    assert!(f.safety > 0.);
+    let peak = out.iter().fold(0f32, |m, v| m.max(v.abs()));
+    assert!(peak <= 0.5012 * (1. + 1e-6));
+    let room = f.scope_room.iter().fold(0f32, |m, v| m.max(*v));
+    assert_eq!(room, 0., "the held sub peak is over the ceiling");
+}
+
+#[test]
+fn the_held_peak_keeps_the_tops_room_steady_through_the_cycle() {
+    let room_ripple = |hold: f32, hz: f64| {
+        let mut e = engine(Settings {
+            hold,
+            ..Settings::default()
+        });
+        render(&mut e, 1., Monitor::Quench, |t| {
+            0.5 * (TAU * hz * t).sin() + 0.3 * top(t)
+        });
+        let f = e.take_analyzer();
+        let (lo, hi) = f
+            .scope_room
+            .iter()
+            .fold((f32::MAX, f32::MIN), |(a, b), v| (a.min(*v), b.max(*v)));
+        (hi - lo) / hi
+    };
+    // 30 Hz: the sub peaks every 16.7 ms.
+    let held = room_ripple(60., 30.);
+    let short = room_ripple(10., 30.);
+    assert!(held < 0.01, "{held}");
+    assert!(short > 0.1, "{short}");
+}
+
+#[test]
+fn bypass_is_the_input_delayed_by_the_latency() {
+    let mut e = engine(Settings {
+        bypass: true,
+        drive: 12.,
+        ..Settings::default()
+    });
+    let latency = e.latency_samples() as usize;
+    let x: Vec<f32> = (0..4800)
+        .map(|i| (0.9 * (TAU * 50. * i as f64 / RATE as f64).sin()) as f32 + 0.5)
+        .collect();
+    let out: Vec<f32> = x
+        .iter()
+        .map(|&v| e.process_sample([v, v], Monitor::Quench)[0])
+        .collect();
+    for i in latency..x.len() {
+        assert_eq!(out[i], x[i - latency]);
+    }
+}
+
+#[test]
+fn mono_works_and_the_shape_never_passes_its_limit() {
+    let mut e = Engine::new(44100., 1).unwrap();
+    e.set_settings(Settings {
+        drive: 12.,
+        ..Settings::default()
+    })
+    .unwrap();
+    for i in 0..44100 {
+        let v = (TAU * 55. * i as f64 / 44100.).sin() as f32;
+        let o = e.process_sample([v, 0.], Monitor::Quench);
+        assert!(o[0].abs() <= 0.9661 && o[1] == 0.);
+    }
+    for knee in [0., 0.3, 1.] {
+        for h in [-5., -1., -0.2, 0., 0.5, 0.99, 3.] {
+            let y = shape(h, 0.8, knee);
+            assert!(y.abs() <= 0.8 && y * h >= 0.);
+        }
+    }
+    assert_eq!(shape(0.5, 0.8, 0.), 0.5);
+    assert_eq!(shape(0.5, 0., 0.), 0.);
+}
+
+#[test]
+fn settings_are_validated_and_serialise() {
+    assert!(Settings::default().validate().is_ok());
+    for bad in [
+        Settings {
+            drive: -1.,
+            ..Settings::default()
+        },
+        Settings {
+            ceiling: 0.5,
+            ..Settings::default()
+        },
+        Settings {
+            split: 20.,
+            ..Settings::default()
+        },
+        Settings {
+            hold: f32::NAN,
+            ..Settings::default()
+        },
+    ] {
+        assert!(bad.validate().is_err());
+        assert!(Engine::new(RATE, 2).unwrap().set_settings(bad).is_err());
+    }
+    let s = Settings {
+        drive: 9.,
+        soft: 40.,
+        ..Settings::default()
+    };
+    let json = serde_json::to_string(&s).unwrap();
+    assert_eq!(serde_json::from_str::<Settings>(&json).unwrap(), s);
+    assert!(serde_json::from_str::<Settings>(r#"{"drive":0,"oops":1}"#).is_err());
+}

plugins/quench/core/tests/realtime.rs

@@ -0,0 +1,65 @@
+use quench_core::{Engine, Monitor, Settings};
+use std::{
+    alloc::{GlobalAlloc, Layout, System},
+    cell::Cell,
+};
+
+struct CheckedAllocator;
+thread_local! {
+    static CHECK:Cell<bool>=const {Cell::new(false)};
+    static OPERATIONS:Cell<usize>=const {Cell::new(0)};
+}
+fn record() {
+    if CHECK.try_with(Cell::get).unwrap_or(false) {
+        let _ = OPERATIONS.try_with(|n| n.set(n.get() + 1));
+    }
+}
+unsafe impl GlobalAlloc for CheckedAllocator {
+    unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
+        record();
+        unsafe { System.alloc(layout) }
+    }
+    unsafe fn dealloc(&self, pointer: *mut u8, layout: Layout) {
+        record();
+        unsafe { System.dealloc(pointer, layout) }
+    }
+    unsafe fn realloc(&self, pointer: *mut u8, layout: Layout, size: usize) -> *mut u8 {
+        record();
+        unsafe { System.realloc(pointer, layout, size) }
+    }
+}
+#[global_allocator]
+static ALLOCATOR: CheckedAllocator = CheckedAllocator;
+
+#[test]
+fn processing_settings_monitors_and_analysis_do_not_allocate_or_free() {
+    let mut engine = Engine::new(48000., 2).unwrap();
+    let mut settings = Settings {
+        drive: 12.,
+        ..Settings::default()
+    };
+    engine.set_settings(settings).unwrap();
+    let monitors = [Monitor::Quench, Monitor::Plain, Monitor::Delta];
+    CHECK.with(|v| v.set(true));
+    for i in 0..96000 {
+        if i % 4800 == 0 {
+            let step = i / 4800;
+            settings.split = 60. + 20. * (step % 6) as f32;
+            settings.hold = 20. + 40. * (step % 3) as f32;
+            settings.soft = 25. * (step % 5) as f32;
+            settings.ceiling = -3. * (step % 3) as f32;
+            settings.bypass = step % 7 == 6;
+            engine.set_settings(settings).unwrap();
+        }
+        let t = i as f32 / 48000.;
+        let x = (std::f32::consts::TAU * 45. * t).sin() * 0.5
+            + (std::f32::consts::TAU * 733. * t).sin() * 0.5;
+        std::hint::black_box(engine.process_sample([x, -x], monitors[(i / 9600) % 3]));
+        if i % 1600 == 0 {
+            std::hint::black_box(engine.take_analyzer());
+        }
+    }
+    engine.reset();
+    CHECK.with(|v| v.set(false));
+    assert_eq!(OPERATIONS.with(Cell::get), 0);
+}

plugins/quench/plugin/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "quench"
+version = "0.1.0"
+edition = "2021"
+license = "ISC"
+
+[workspace]
+
+[lib]
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+nih_plug = { git = "https://github.com/robbert-vdh/nih-plug.git", rev = "de421011f41a6d10fc8c7a6084e4f4dee0143683", default-features = false }
+nih_plug_egui = { git = "https://github.com/robbert-vdh/nih-plug.git", rev = "de421011f41a6d10fc8c7a6084e4f4dee0143683" }
+quench-core = { path = "../core" }
+quench-ui = { path = "../ui" }
+crossbeam-queue = "0.3"
+
+[dev-dependencies]
+clap-sys = { git = "https://github.com/micahrj/clap-sys.git", rev = "25d7f53fdb6363ad63fbd80049cb7a42a97ac156" }
+serde_json = "1"
+
+[profile.release]
+lto = "thin"
+strip = "symbols"

plugins/quench/plugin/src/lib.rs

@@ -0,0 +1,204 @@
+//! CLAP audio effect. All DSP state is owned by the processing thread.
+mod params;
+use crossbeam_queue::ArrayQueue;
+use nih_plug::prelude::*;
+use nih_plug_egui::{create_egui_editor, egui};
+use params::{QuenchParams, FLOATS};
+use quench_core::{AnalyzerFrame, Engine, Monitor};
+use std::sync::{
+    atomic::{AtomicU8, Ordering},
+    Arc,
+};
+
+struct Shared {
+    analyzer: ArrayQueue<AnalyzerFrame>,
+    /// The editor's listen choice: 0 Quench, 1 Plain, 2 Delta.
+    monitor: AtomicU8,
+}
+fn encode(m: Monitor) -> u8 {
+    match m {
+        Monitor::Quench => 0,
+        Monitor::Plain => 1,
+        Monitor::Delta => 2,
+    }
+}
+fn decode(v: u8) -> Monitor {
+    match v {
+        1 => Monitor::Plain,
+        2 => Monitor::Delta,
+        _ => Monitor::Quench,
+    }
+}
+struct EditorData {
+    ui: quench_ui::State,
+    gestures: [bool; FLOATS],
+}
+pub struct Quench {
+    params: Arc<QuenchParams>,
+    shared: Arc<Shared>,
+    engine: Option<Engine>,
+    publish_count: usize,
+    publish_interval: usize,
+}
+impl Default for Quench {
+    fn default() -> Self {
+        Self {
+            params: Arc::new(QuenchParams::default()),
+            shared: Arc::new(Shared {
+                analyzer: ArrayQueue::new(2),
+                monitor: AtomicU8::new(0),
+            }),
+            engine: None,
+            publish_count: 0,
+            publish_interval: 1600,
+        }
+    }
+}
+impl Plugin for Quench {
+    const NAME: &'static str = "Quench";
+    const VENDOR: &'static str = "Bass Foundry";
+    const URL: &'static str = "";
+    const EMAIL: &'static str = "";
+    const VERSION: &'static str = env!("CARGO_PKG_VERSION");
+    const AUDIO_IO_LAYOUTS: &'static [AudioIOLayout] = &[
+        AudioIOLayout {
+            main_input_channels: NonZeroU32::new(2),
+            main_output_channels: NonZeroU32::new(2),
+            ..AudioIOLayout::const_default()
+        },
+        AudioIOLayout {
+            main_input_channels: NonZeroU32::new(1),
+            main_output_channels: NonZeroU32::new(1),
+            ..AudioIOLayout::const_default()
+        },
+    ];
+    const SAMPLE_ACCURATE_AUTOMATION: bool = false;
+    type SysExMessage = ();
+    type BackgroundTask = ();
+    fn params(&self) -> Arc<dyn Params> {
+        self.params.clone()
+    }
+    fn editor(&mut self, _: AsyncExecutor<Self>) -> Option<Box<dyn Editor>> {
+        let params = self.params.clone();
+        let shared = self.shared.clone();
+        create_egui_editor(
+            params.editor.clone(),
+            EditorData {
+                ui: quench_ui::State::default(),
+                gestures: [false; FLOATS],
+            },
+            |ctx, data| {
+                data.ui.monitor = Monitor::Quench;
+                quench_ui::style(ctx);
+            },
+            move |ctx, setter, data| {
+                while let Some(frame) = shared.analyzer.pop() {
+                    data.ui.accept_frame(frame);
+                }
+                let before = params.settings();
+                let mut edited = before;
+                nih_plug_egui::resizable_window::ResizableWindow::new("quench-editor")
+                    .min_size(egui::vec2(
+                        quench_ui::WIDTH as f32 - 80.,
+                        quench_ui::HEIGHT as f32 - 40.,
+                    ))
+                    .show(ctx, &params.editor, |ui| {
+                        quench_ui::show(ui, &mut edited, &mut data.ui)
+                    });
+                params.apply(
+                    setter,
+                    &before,
+                    &edited,
+                    data.ui.gesture_active,
+                    &mut data.gestures,
+                );
+                // The monitor is a listen choice only: never saved and never left on after
+                // the editor closes.
+                shared
+                    .monitor
+                    .store(encode(data.ui.monitor), Ordering::Release);
+                ctx.request_repaint_after(std::time::Duration::from_millis(40));
+            },
+        )
+    }
+    fn initialize(
+        &mut self,
+        layout: &AudioIOLayout,
+        config: &BufferConfig,
+        context: &mut impl InitContext<Self>,
+    ) -> bool {
+        let Ok(mut engine) = Engine::new(
+            config.sample_rate,
+            layout.main_input_channels.map_or(0, |v| v.get() as usize),
+        ) else {
+            return false;
+        };
+        if engine.set_settings(self.params.settings()).is_err() {
+            return false;
+        }
+        context.set_latency_samples(engine.latency_samples());
+        self.shared.monitor.store(0, Ordering::Release);
+        self.publish_interval = (config.sample_rate / 30.) as usize;
+        self.engine = Some(engine);
+        true
+    }
+    fn reset(&mut self) {
+        if let Some(e) = self.engine.as_mut() {
+            e.reset();
+        }
+        self.publish_count = 0;
+    }
+    fn process(
+        &mut self,
+        buffer: &mut Buffer,
+        _: &mut AuxiliaryBuffers,
+        _: &mut impl ProcessContext<Self>,
+    ) -> ProcessStatus {
+        let Some(engine) = self.engine.as_mut() else {
+            return ProcessStatus::Normal;
+        };
+        let _ = engine.set_settings(self.params.settings());
+        let monitor = if self.params.editor.is_open() {
+            decode(self.shared.monitor.load(Ordering::Acquire))
+        } else {
+            Monitor::Quench
+        };
+        for mut sample in buffer.iter_samples() {
+            let x = [
+                *sample.get_mut(0).unwrap(),
+                if engine.channels() == 2 {
+                    *sample.get_mut(1).unwrap()
+                } else {
+                    0.
+                },
+            ];
+            let out = engine.process_sample(x, monitor);
+            for (c, value) in sample.into_iter().enumerate() {
+                *value = out[c];
+            }
+            self.publish_count += 1;
+            if self.publish_count >= self.publish_interval {
+                let _ = self.shared.analyzer.force_push(engine.take_analyzer());
+                self.publish_count = 0;
+            }
+        }
+        // The oversampling filters must drain after input stops.
+        ProcessStatus::KeepAlive
+    }
+}
+impl ClapPlugin for Quench {
+    const CLAP_ID: &'static str = "io.narl.bass-foundry.quench";
+    const CLAP_DESCRIPTION: Option<&'static str> =
+        Some("Clips the top as hard as you like while the sub passes clean");
+    const CLAP_MANUAL_URL: Option<&'static str> = None;
+    const CLAP_SUPPORT_URL: Option<&'static str> = None;
+    const CLAP_FEATURES: &'static [ClapFeature] = &[
+        ClapFeature::AudioEffect,
+        ClapFeature::Distortion,
+        ClapFeature::Limiter,
+        ClapFeature::Mastering,
+        ClapFeature::Stereo,
+        ClapFeature::Mono,
+    ];
+}
+nih_export_clap!(Quench);

plugins/quench/plugin/src/params.rs

@@ -0,0 +1,108 @@
+use nih_plug::prelude::*;
+use nih_plug_egui::EguiState;
+use quench_core::{Settings, CEILING_MIN, DRIVE_MAX, HOLD_MAX, HOLD_MIN, SPLIT_MAX, SPLIT_MIN};
+use std::sync::Arc;
+
+fn linear(name: &str, v: f32, min: f32, max: f32, unit: &'static str) -> FloatParam {
+    FloatParam::new(name, v, FloatRange::Linear { min, max }).with_unit(unit)
+}
+fn skewed(name: &str, v: f32, min: f32, max: f32, unit: &'static str) -> FloatParam {
+    FloatParam::new(
+        name,
+        v,
+        FloatRange::Skewed {
+            min,
+            max,
+            factor: FloatRange::skew_factor(-1.),
+        },
+    )
+    .with_unit(unit)
+}
+/// Continuous controls, in the order of the gesture slots.
+pub const FLOATS: usize = 5;
+
+#[derive(Params)]
+pub struct QuenchParams {
+    #[persist = "editor"]
+    pub editor: Arc<EguiState>,
+    #[id = "drive"]
+    pub drive: FloatParam,
+    #[id = "ceiling"]
+    pub ceiling: FloatParam,
+    #[id = "split"]
+    pub split: FloatParam,
+    #[id = "hold"]
+    pub hold: FloatParam,
+    #[id = "soft"]
+    pub soft: FloatParam,
+    #[id = "bypass"]
+    pub bypass: BoolParam,
+}
+impl Default for QuenchParams {
+    fn default() -> Self {
+        let d = Settings::default();
+        Self {
+            editor: EguiState::from_size(quench_ui::WIDTH, quench_ui::HEIGHT),
+            drive: linear("Drive", d.drive, 0., DRIVE_MAX, " dB"),
+            ceiling: linear("Ceiling", d.ceiling, CEILING_MIN, 0., " dB"),
+            split: skewed("Split", d.split, SPLIT_MIN, SPLIT_MAX, " Hz"),
+            hold: skewed("Hold", d.hold, HOLD_MIN, HOLD_MAX, " ms"),
+            soft: linear("Soft", d.soft, 0., 100., " %"),
+            bypass: BoolParam::new("Bypass", false).make_bypass(),
+        }
+    }
+}
+impl QuenchParams {
+    pub fn settings(&self) -> Settings {
+        Settings {
+            drive: self.drive.value(),
+            ceiling: self.ceiling.value(),
+            split: self.split.value(),
+            hold: self.hold.value(),
+            soft: self.soft.value(),
+            bypass: self.bypass.value(),
+        }
+    }
+    fn floats(&self) -> [&FloatParam; FLOATS] {
+        [
+            &self.drive,
+            &self.ceiling,
+            &self.split,
+            &self.hold,
+            &self.soft,
+        ]
+    }
+    fn values(s: &Settings) -> [f32; FLOATS] {
+        [s.drive, s.ceiling, s.split, s.hold, s.soft]
+    }
+    /// Pushes every changed editor value to the host. Continuous controls hold one gesture
+    /// while the pointer is down; switches are set in a single gesture.
+    pub fn apply(
+        &self,
+        setter: &ParamSetter,
+        old: &Settings,
+        new: &Settings,
+        dragging: bool,
+        open: &mut [bool; FLOATS],
+    ) {
+        let pairs = Self::values(old).into_iter().zip(Self::values(new));
+        for (i, (p, (a, b))) in self.floats().into_iter().zip(pairs).enumerate() {
+            if a != b {
+                if !open[i] {
+                    open[i] = true;
+                    setter.begin_set_parameter(p);
+                }
+                setter.set_parameter(p, b);
+            }
+            if !dragging && open[i] {
+                setter.end_set_parameter(p);
+                open[i] = false;
+            }
+        }
+        if new.bypass != old.bypass {
+            setter.begin_set_parameter(&self.bypass);
+            setter.set_parameter(&self.bypass, new.bypass);
+            setter.end_set_parameter(&self.bypass);
+        }
+    }
+}

plugins/quench/plugin/tests/host.rs

@@ -0,0 +1,205 @@
+//! Exercise the actual exported CLAP ABI without requiring a GUI or installed DAW.
+use clap_sys::{
+    audio_buffer::*,
+    events::*,
+    ext::{audio_ports::*, latency::*, state::*},
+    factory::plugin_factory::*,
+    host::*,
+    process::*,
+    stream::*,
+    version::*,
+};
+use std::{
+    ffi::{c_char, c_void, CStr},
+    io::{Cursor, Read},
+    ptr,
+};
+
+unsafe extern "C" fn extension(_: *const clap_host, _: *const c_char) -> *const c_void {
+    ptr::null()
+}
+unsafe extern "C" fn request(_: *const clap_host) {}
+unsafe extern "C" fn count(_: *const clap_input_events) -> u32 {
+    0
+}
+unsafe extern "C" fn event(_: *const clap_input_events, _: u32) -> *const clap_event_header {
+    ptr::null()
+}
+unsafe extern "C" fn push(_: *const clap_output_events, _: *const clap_event_header) -> bool {
+    true
+}
+unsafe extern "C" fn write(stream: *const clap_ostream, buffer: *const c_void, size: u64) -> i64 {
+    // SAFETY: The test owns the Vec for the entire synchronous save call.
+    let bytes = unsafe { &mut *((*stream).ctx as *mut Vec<u8>) };
+    bytes.extend_from_slice(unsafe {
+        std::slice::from_raw_parts(buffer as *const u8, size as usize)
+    });
+    size as i64
+}
+unsafe extern "C" fn read(stream: *const clap_istream, buffer: *mut c_void, size: u64) -> i64 {
+    // SAFETY: The test owns the Cursor; the wrapper supplies writable stream storage.
+    let cursor = unsafe { &mut *((*stream).ctx as *mut Cursor<Vec<u8>>) };
+    cursor
+        .read(unsafe { std::slice::from_raw_parts_mut(buffer as *mut u8, size as usize) })
+        .unwrap() as i64
+}
+
+#[test]
+fn effect_ports_state_latency_and_audio_lifecycle() {
+    // SAFETY: All callbacks, strings, streams, buffers, and the host outlive their
+    // synchronous ABI calls. Activation/processing/destruction follow CLAP order.
+    unsafe {
+        let entry = &quench::clap_entry;
+        assert!(entry.init.unwrap()(c"quench.clap".as_ptr()));
+        let factory = entry.get_factory.unwrap()(CLAP_PLUGIN_FACTORY_ID.as_ptr())
+            as *const clap_plugin_factory;
+        assert!(!factory.is_null());
+        let factory = &*factory;
+        assert_eq!(factory.get_plugin_count.unwrap()(factory), 1);
+        let descriptor = factory.get_plugin_descriptor.unwrap()(factory, 0);
+        assert!(!descriptor.is_null());
+        assert_eq!(CStr::from_ptr((*descriptor).name), c"Quench");
+        assert_eq!(
+            CStr::from_ptr((*descriptor).id),
+            c"io.narl.bass-foundry.quench"
+        );
+        assert!(factory.get_plugin_descriptor.unwrap()(factory, 1).is_null());
+        let host = clap_host {
+            clap_version: CLAP_VERSION,
+            host_data: ptr::null_mut(),
+            name: c"Storyboard test host".as_ptr(),
+            vendor: c"Tests".as_ptr(),
+            url: c"".as_ptr(),
+            version: c"1.0".as_ptr(),
+            get_extension: Some(extension),
+            request_restart: Some(request),
+            request_process: Some(request),
+            request_callback: Some(request),
+        };
+        let plugin = factory.create_plugin.unwrap()(factory, &host, (*descriptor).id);
+        assert!(!plugin.is_null());
+        let p = &*plugin;
+        assert!(p.init.unwrap()(plugin));
+        let ports = p.get_extension.unwrap()(plugin, CLAP_EXT_AUDIO_PORTS.as_ptr())
+            as *const clap_plugin_audio_ports;
+        assert!(!ports.is_null());
+        assert_eq!((*ports).count.unwrap()(plugin, false), 1);
+        assert_eq!((*ports).count.unwrap()(plugin, true), 1);
+        let latency = p.get_extension.unwrap()(plugin, CLAP_EXT_LATENCY.as_ptr())
+            as *const clap_plugin_latency;
+        assert!(!latency.is_null());
+        let state =
+            p.get_extension.unwrap()(plugin, CLAP_EXT_STATE.as_ptr()) as *const clap_plugin_state;
+        assert!(!state.is_null());
+        let state = &*state;
+        let save = || {
+            let mut bytes = Vec::new();
+            let stream = clap_ostream {
+                ctx: &mut bytes as *mut Vec<u8> as *mut c_void,
+                write: Some(write),
+            };
+            assert!(state.save.unwrap()(plugin, &stream));
+            bytes
+        };
+        let mut envelope: nih_plug::prelude::PluginState =
+            serde_json::from_slice(&save()[8..]).unwrap();
+        use nih_plug::wrapper::state::ParamValue;
+        envelope.params.insert("soft".into(), ParamValue::F32(40.));
+        envelope.params.insert("hold".into(), ParamValue::F32(100.));
+        envelope.params.insert("split".into(), ParamValue::F32(90.));
+        let encoded = serde_json::to_vec(&envelope).unwrap();
+        let mut framed = (encoded.len() as u64).to_le_bytes().to_vec();
+        framed.extend_from_slice(&encoded);
+        let mut bytes = Cursor::new(framed);
+        let stream = clap_istream {
+            ctx: &mut bytes as *mut Cursor<Vec<u8>> as *mut c_void,
+            read: Some(read),
+        };
+        assert!(state.load.unwrap()(plugin, &stream));
+        let restored: nih_plug::prelude::PluginState =
+            serde_json::from_slice(&save()[8..]).unwrap();
+        assert_eq!(
+            serde_json::to_value(&restored.params).unwrap(),
+            serde_json::to_value(&envelope.params).unwrap()
+        );
+        for rate in [44100., 48000., 96000.] {
+            assert!(p.activate.unwrap()(plugin, rate, 1, 512));
+            let delay = (*latency).get.unwrap()(plugin) as usize;
+            // Only the 4× oversampling filters: under a millisecond at every rate.
+            assert_eq!(delay, 37);
+            assert!(p.start_processing.unwrap()(plugin));
+            let total = delay + 9600;
+            let mut position = 0;
+            let (mut energy_in, mut energy_out) = (0f64, 0f64);
+            while position < total {
+                let frames = [1, 127, 512, 31][position % 4].min(total - position);
+                // A 1 kHz tone well under the ceiling passes unchanged.
+                let tone = |n: usize| {
+                    0.25 * (std::f64::consts::TAU * 1000. * n as f64 / rate).sin() as f32
+                };
+                let mut input_left = [0f32; 512];
+                let mut input_right = [0f32; 512];
+                for i in 0..frames {
+                    input_left[i] = tone(position + i);
+                    input_right[i] = -tone(position + i);
+                }
+                let mut left = [0f32; 512];
+                let mut right = [0f32; 512];
+                let mut in_channels = [input_left.as_mut_ptr(), input_right.as_mut_ptr()];
+                let mut out_channels = [left.as_mut_ptr(), right.as_mut_ptr()];
+                let incoming = clap_audio_buffer {
+                    data32: in_channels.as_mut_ptr(),
+                    data64: ptr::null_mut(),
+                    channel_count: 2,
+                    latency: 0,
+                    constant_mask: 0,
+                };
+                let mut outgoing_audio = clap_audio_buffer {
+                    data32: out_channels.as_mut_ptr(),
+                    data64: ptr::null_mut(),
+                    channel_count: 2,
+                    latency: 0,
+                    constant_mask: 0,
+                };
+                let input = clap_input_events {
+                    ctx: ptr::null_mut(),
+                    size: Some(count),
+                    get: Some(event),
+                };
+                let outgoing = clap_output_events {
+                    ctx: ptr::null_mut(),
+                    try_push: Some(push),
+                };
+                let process = clap_process {
+                    steady_time: position as i64,
+                    frames_count: frames as u32,
+                    transport: ptr::null(),
+                    audio_inputs: &incoming,
+                    audio_outputs: &mut outgoing_audio,
+                    audio_inputs_count: 1,
+                    audio_outputs_count: 1,
+                    in_events: &input,
+                    out_events: &outgoing,
+                };
+                assert_ne!(p.process.unwrap()(plugin, &process), CLAP_PROCESS_ERROR);
+                for i in 0..frames {
+                    let n = position + i;
+                    if n < delay + 4800 {
+                        // The tone's onset rings in the filters, but never past the ceiling.
+                        assert!(left[i].abs() <= 0.9661, "{}", left[i]);
+                    } else if n > delay + 4800 {
+                        energy_in += (tone(n - delay) as f64).powi(2);
+                        energy_out += (left[i] as f64).powi(2) + (right[i] as f64).powi(2);
+                    }
+                }
+                position += frames;
+            }
+            let ratio_db = 10. * (energy_out / (2. * energy_in)).log10();
+            assert!(ratio_db.abs() < 0.2, "{ratio_db}");
+            p.stop_processing.unwrap()(plugin);
+            p.deactivate.unwrap()(plugin);
+        }
+        p.destroy.unwrap()(plugin);
+        entry.deinit.unwrap()();
+    }
+}

plugins/quench/ui/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "quench-ui"
+version = "0.1.0"
+edition.workspace = true
+license.workspace = true
+
+[dependencies]
+egui = "0.31.1"
+quench-core = { path = "../core" }
+common-ui = { path = "../../common/ui" }
+common-dsp = { path = "../../common/dsp" }

plugins/quench/ui/src/lib.rs

@@ -0,0 +1,327 @@
+//! Quench editor, shared by the CLAP wrapper and the headless renderer.
+use common_ui::*;
+use egui::{self, Color32, FontId, Pos2, Rect, RichText, Sense, Stroke, Vec2};
+use quench_core::{
+    AnalyzerFrame, Monitor, Settings, CEILING_MIN, DRIVE_MAX, HOLD_MAX, HOLD_MIN, SCOPE, SPLIT_MAX,
+    SPLIT_MIN,
+};
+
+pub use common_ui::style;
+pub const WIDTH: u32 = 980;
+pub const HEIGHT: u32 = 640;
+
+pub struct State {
+    pub analyzer: AnalyzerFrame,
+    /// What the output plays. Not saved: the wrapper resets it when the editor opens.
+    pub monitor: Monitor,
+    /// True while a pointer button is held, so knob drags become one host gesture.
+    pub gesture_active: bool,
+    pub help: String,
+}
+impl Default for State {
+    fn default() -> Self {
+        Self {
+            analyzer: AnalyzerFrame::default(),
+            monitor: Monitor::Quench,
+            gesture_active: false,
+            help: DEFAULT_HELP.into(),
+        }
+    }
+}
+const DEFAULT_HELP: &str =
+    "Put Quench last on the master or the bass bus. Raise Drive until the top clips as hard as you want.";
+impl State {
+    pub fn accept_frame(&mut self, frame: AnalyzerFrame) {
+        self.analyzer = frame;
+    }
+}
+fn hint(r: &egui::Response, state: &mut State, text: &str) {
+    if r.hovered() || r.has_focus() {
+        state.help = text.into();
+    }
+}
+#[allow(clippy::too_many_arguments)]
+fn knob(
+    ui: &mut egui::Ui,
+    state: &mut State,
+    name: &str,
+    value: &mut f32,
+    range: std::ops::RangeInclusive<f32>,
+    default: f32,
+    unit: &str,
+    help: &str,
+) {
+    ui.vertical_centered(|ui| {
+        let r = rotary(ui, name, value, range, default, unit, 72., ACCENT);
+        hint(&r, state, help);
+    });
+}
+
+/// The selected output with the ceiling, the sub band, and the room the sub leaves the top.
+fn scope(ui: &mut egui::Ui, settings: &Settings, frame: &AnalyzerFrame, height: f32) {
+    let (rect, _) = ui.allocate_exact_size(Vec2::new(ui.available_width(), height), Sense::hover());
+    let p = ui.painter_at(rect);
+    p.rect_filled(rect, 2., SCREEN);
+    p.text(
+        rect.left_top() + Vec2::new(10., 8.),
+        egui::Align2::LEFT_TOP,
+        "OUTPUT · SUB · ROOM FOR THE TOP",
+        FontId::proportional(11.),
+        MUTED,
+    );
+    p.text(
+        rect.right_top() + Vec2::new(-12., 8.),
+        egui::Align2::RIGHT_TOP,
+        format!(
+            "{:.0} ms",
+            SCOPE as f32 * 8. / frame.sample_rate.max(1.) * 1000.
+        ),
+        FontId::proportional(11.),
+        MUTED,
+    );
+    let area = Rect::from_min_max(
+        rect.left_top() + Vec2::new(12., 28.),
+        rect.right_bottom() - Vec2::new(12., 10.),
+    );
+    let mid = area.center().y;
+    let scale = area.height() * 0.5 / 1.08;
+    let y = |v: f32| mid - v.clamp(-1.08, 1.08) * scale;
+    let x = |i: usize| area.left() + area.width() * i as f32 / (SCOPE - 1) as f32;
+    p.line_segment(
+        [Pos2::new(area.left(), mid), Pos2::new(area.right(), mid)],
+        Stroke::new(1.0_f32, Color32::from_rgb(32, 35, 40)),
+    );
+    let c = 10f32.powf(settings.ceiling / 20.);
+    for v in [c, -c] {
+        p.line_segment(
+            [Pos2::new(area.left(), y(v)), Pos2::new(area.right(), y(v))],
+            Stroke::new(1.0_f32, ACCENT.gamma_multiply(0.6)),
+        );
+    }
+    p.text(
+        Pos2::new(area.right() - 4., y(c) - 3.),
+        egui::Align2::RIGHT_BOTTOM,
+        format!("CEILING {:.1} dB", settings.ceiling),
+        FontId::proportional(10.),
+        ACCENT,
+    );
+    for i in 0..SCOPE {
+        let (lo, hi) = (frame.scope_min[i], frame.scope_max[i]);
+        let top = y(hi);
+        let bottom = y(lo).max(top + 1.);
+        p.line_segment(
+            [Pos2::new(x(i), top), Pos2::new(x(i), bottom)],
+            Stroke::new(2.0_f32, STEEL.gamma_multiply(0.55)),
+        );
+    }
+    // Where the output may go: the sub plus or minus the top's room.
+    for sign in [1., -1.] {
+        let line: Vec<Pos2> = (0..SCOPE)
+            .map(|i| Pos2::new(x(i), y(frame.scope_sub[i] + sign * frame.scope_room[i])))
+            .collect();
+        p.add(egui::Shape::line(line, Stroke::new(1.0_f32, MUTED)));
+    }
+    let sub: Vec<Pos2> = (0..SCOPE)
+        .map(|i| Pos2::new(x(i), y(frame.scope_sub[i])))
+        .collect();
+    p.add(egui::Shape::line(sub, Stroke::new(2.0_f32, FOCUS)));
+    p.rect_stroke(
+        rect,
+        2.,
+        Stroke::new(1.0_f32, EDGE),
+        egui::StrokeKind::Inside,
+    );
+}
+
+pub fn show(ui: &mut egui::Ui, settings: &mut Settings, state: &mut State) {
+    backdrop(ui);
+    state.help = DEFAULT_HELP.into();
+    state.gesture_active = ui.input(|i| i.pointer.any_down());
+    ui.add_space(2.);
+    header(ui, "QUENCH", "SUB-SAFE CLIPPER", |ui| {
+        let r = ui
+            .selectable_label(settings.bypass, RichText::new("BYPASS").size(13.))
+            .on_hover_text("Crossfade to the input, delayed by the latency.");
+        if r.clicked() {
+            settings.bypass = !settings.bypass;
+        }
+        ui.separator();
+        for (monitor, label, text) in [
+            (
+                Monitor::Delta,
+                "DELTA",
+                "Hear what Quench takes away. Not saved.",
+            ),
+            (
+                Monitor::Plain,
+                "PLAIN",
+                "Hear a plain clipper at the same settings, to compare the low end. Not saved.",
+            ),
+            (Monitor::Quench, "QUENCH", "Hear Quench."),
+        ] {
+            let r = ui
+                .selectable_label(state.monitor == monitor, RichText::new(label).size(13.))
+                .on_hover_text(text);
+            if r.clicked() {
+                state.monitor = monitor;
+            }
+        }
+        caption(ui, "LISTEN");
+    });
+    ui.add_space(6.);
+    let frame = state.analyzer;
+    ui.horizontal_top(|ui| {
+        panel(ui, |ui| {
+            ui.set_width(250.);
+            ui.set_min_height(TOP);
+            ui.vertical(|ui| readings(ui, settings, &frame));
+        });
+        ui.add_space(4.);
+        panel(ui, |ui| {
+            ui.set_width(ui.available_width());
+            scope(ui, settings, &frame, TOP);
+        });
+    });
+    ui.add_space(6.);
+    panel(ui, |ui| {
+        ui.set_width(ui.available_width());
+        ui.vertical(|ui| controls(ui, settings, state));
+    });
+    ui.separator();
+    ui.label(RichText::new(&state.help).color(MUTED));
+}
+const TOP: f32 = 330.;
+
+fn readings(ui: &mut egui::Ui, settings: &Settings, frame: &AnalyzerFrame) {
+    caption(ui, "LOW END CHANGED BY");
+    let has_sub = frame.low_quench.is_finite();
+    ui.label(
+        RichText::new(if has_sub {
+            format!("{:.0} dB", frame.low_quench)
+        } else {
+            "—".into()
+        })
+        .font(FontId::new(44., egui::FontFamily::Name("medium".into())))
+        .color(if has_sub { TEXT } else { DIM }),
+    );
+    ui.label(
+        RichText::new(if has_sub {
+            format!("plain clip: {:.0} dB", frame.low_plain)
+        } else {
+            "no sub playing".into()
+        })
+        .monospace()
+        .size(13.)
+        .color(MUTED),
+    );
+    ui.add_space(12.);
+    readout(
+        ui,
+        "TOP CLIPPED BY",
+        if frame.top_clip >= 40. {
+            "no room left".into()
+        } else if frame.top_clip > 0. {
+            format!("{:.1} dB", frame.top_clip)
+        } else {
+            "not clipping".into()
+        },
+        ACCENT,
+    );
+    let room = settings.ceiling - frame.sub_peak;
+    readout(
+        ui,
+        "SUB PEAK · ROOM LEFT",
+        if frame.sub_peak > -119. {
+            format!("{:.1} dBFS · {:.1} dB", frame.sub_peak, room.max(0.))
+        } else {
+            "—".into()
+        },
+        FOCUS,
+    );
+    if frame.sub_peak > settings.ceiling - 1. {
+        ui.label(
+            RichText::new(
+                "The sub alone reaches the ceiling: the top has no room and the safety clip \
+                 cuts the sub. Lower Drive or the sub.",
+            )
+            .size(12.)
+            .color(ACCENT),
+        );
+        ui.add_space(6.);
+    }
+    ui.add_space(4.);
+    meter(ui, "IN", frame.input_peak, STEEL, 150.);
+    meter(ui, "OUT", frame.output_peak, ACCENT, 150.);
+    ui.add_space(6.);
+    ui.label(
+        RichText::new(format!(
+            "safety clip {} · {:.1} ms latency",
+            if frame.safety > 0. {
+                format!("{:.2} dB", frame.safety)
+            } else {
+                "idle".into()
+            },
+            frame.latency as f32 / frame.sample_rate.max(1.) * 1000.
+        ))
+        .size(12.)
+        .color(MUTED),
+    );
+}
+
+fn controls(ui: &mut egui::Ui, settings: &mut Settings, state: &mut State) {
+    let d = Settings::default();
+    ui.columns(5, |c| {
+        knob(
+            &mut c[0],
+            state,
+            "Drive",
+            &mut settings.drive,
+            0. ..=DRIVE_MAX,
+            d.drive,
+            " dB",
+            "Gain into the clipper. The sub rises with it: watch the room it leaves.",
+        );
+        knob(
+            &mut c[1],
+            state,
+            "Ceiling",
+            &mut settings.ceiling,
+            CEILING_MIN..=0.,
+            d.ceiling,
+            " dB",
+            "Highest output peak. The sub keeps its level; the top gets what is left.",
+        );
+        knob(
+            &mut c[2],
+            state,
+            "Split",
+            &mut settings.split,
+            SPLIT_MIN..=SPLIT_MAX,
+            d.split,
+            " Hz",
+            "Below this the sub passes without clipping. Set it above the highest sub note, \
+             or at Anvil's Split.",
+        );
+        knob(
+            &mut c[3],
+            state,
+            "Hold",
+            &mut settings.hold,
+            HOLD_MIN..=HOLD_MAX,
+            d.hold,
+            " ms",
+            "How long the sub's peak keeps its room. Longer than half a period of the lowest \
+             note keeps the top from pumping with the sub.",
+        );
+        knob(
+            &mut c[4],
+            state,
+            "Soft",
+            &mut settings.soft,
+            0. ..=100.,
+            d.soft,
+            " %",
+            "Knee of the top's clip. 0 % is a hard clip, 100 % a soft curve.",
+        );
+    });
+}

tools/editor-check/Cargo.lock

@@ -60,6 +60,24 @@ version = "1.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
 
+[[package]]
+name = "ballast-core"
+version = "0.1.0"
+dependencies = [
+ "common-dsp",
+ "serde",
+]
+
+[[package]]
+name = "ballast-ui"
+version = "0.1.0"
+dependencies = [
+ "ballast-core",
+ "common-dsp",
+ "common-ui",
+ "egui",
+]
+
 [[package]]
 name = "bitflags"
 version = "2.13.2"
@@ -171,6 +189,8 @@ version = "0.1.0"
 dependencies = [
  "anvil-core",
  "anvil-ui",
+ "ballast-core",
+ "ballast-ui",
  "braze-core",
  "braze-ui",
  "common-dsp",
@@ -186,6 +206,8 @@ dependencies = [
  "patina-ui",
  "planish-core",
  "planish-ui",
+ "quench-core",
+ "quench-ui",
  "rivet-app",
  "rivet-core",
  "rivet-midi",
@@ -513,6 +535,24 @@ version = "0.1.30"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d55d956fa96f5ec02be2e13af0e20391a5aa83d6a074e3ad368959d0fab299ea"
 
+[[package]]
+name = "quench-core"
+version = "0.1.0"
+dependencies = [
+ "common-dsp",
+ "serde",
+]
+
+[[package]]
+name = "quench-ui"
+version = "0.1.0"
+dependencies = [
+ "common-dsp",
+ "common-ui",
+ "egui",
+ "quench-core",
+]
+
 [[package]]
 name = "quote"
 version = "1.0.47"

tools/editor-check/Cargo.toml

@@ -29,5 +29,9 @@ planish-core = { path = "../../plugins/planish/core" }
 planish-ui = { path = "../../plugins/planish/ui" }
 braze-core = { path = "../../plugins/braze/core" }
 braze-ui = { path = "../../plugins/braze/ui" }
+quench-core = { path = "../../plugins/quench/core" }
+quench-ui = { path = "../../plugins/quench/ui" }
+ballast-core = { path = "../../plugins/ballast/core" }
+ballast-ui = { path = "../../plugins/ballast/ui" }
 weld-core = { path = "../../plugins/weld/core" }
 weld-ui = { path = "../../plugins/weld/ui" }

tools/editor-check/src/main.rs

@@ -12,13 +12,13 @@ fn main() {
         .unwrap_or("rivet");
     if ![
         "rivet", "patina", "anvil", "crucible", "lathe", "temper", "weld", "knurl", "planish",
-        "braze",
+        "braze", "quench", "ballast",
     ]
     .contains(&plugin)
     {
         eprintln!(
-            "Use --plugin rivet, patina, anvil, crucible, lathe, temper, weld, knurl, planish \
-             or braze"
+            "Use --plugin rivet, patina, anvil, crucible, lathe, temper, weld, knurl, planish, \
+             braze, quench or ballast"
         );
         std::process::exit(2);
     }
@@ -32,7 +32,13 @@ fn main() {
     let knurl = plugin == "knurl";
     let planish = plugin == "planish";
     let braze = plugin == "braze";
-    let (width, height) = if braze {
+    let quench = plugin == "quench";
+    let ballast = plugin == "ballast";
+    let (width, height) = if ballast {
+        (ballast_ui::WIDTH, ballast_ui::HEIGHT)
+    } else if quench {
+        (quench_ui::WIDTH, quench_ui::HEIGHT)
+    } else if braze {
         (braze_ui::WIDTH, braze_ui::HEIGHT)
     } else if planish {
         (planish_ui::WIDTH, planish_ui::HEIGHT)
@@ -229,6 +235,58 @@ fn main() {
         }
         braze_state.accept_frame(engine.take_analyzer());
     }
+    let mut quench_settings = quench_core::Settings {
+        drive: 9.,
+        ..Default::default()
+    };
+    let mut quench_state = quench_ui::State::default();
+    if quench {
+        // A 49 Hz sub under a distorted saw top two octaves up, driven 9 dB into the clipper.
+        let mut engine = quench_core::Engine::new(48000., 2).unwrap();
+        engine.set_settings(quench_settings).unwrap();
+        let mut saw = common_dsp::Saw::new(48000., 196.);
+        for i in 0..48000 {
+            let t = i as f32 / 48000.;
+            let sub = 0.18 * (std::f32::consts::TAU * 49. * t).sin();
+            let top = (saw.sample() * 3.).tanh() * 0.3;
+            engine.process_sample([sub + top, sub + top], quench_core::Monitor::Quench);
+            if i % 1600 == 0 {
+                quench_state.accept_frame(engine.take_analyzer());
+            }
+        }
+        quench_state.accept_frame(engine.take_analyzer());
+    }
+    let mut ballast_settings = ballast_core::Settings {
+        segment: ballast_core::Segment::Grid,
+        target: -16.,
+        ..Default::default()
+    };
+    let mut ballast_state = ballast_ui::State::default();
+    if ballast {
+        // A switch-up every quarter at 140 BPM, cycling four patches of different loudness.
+        let mut engine = ballast_core::Engine::new(48000., 2).unwrap();
+        engine.set_settings(ballast_settings).unwrap();
+        let mut saw = common_dsp::Saw::new(48000., 43.65);
+        let quarter = 48000. * 60. / 140.;
+        for i in 0..48000 * 9 {
+            if i % 512 == 0 {
+                engine.set_transport(Some(140.), Some(i as f64 / 48000. * 140. / 60.));
+            }
+            let part = (i as f32 / quarter) as usize;
+            let s = saw.sample();
+            let x = match part % 4 {
+                0 => (s * 4.).tanh() * 0.6,
+                1 => s * 0.15,
+                2 => (s * 2.).tanh() * 0.35,
+                _ => (s * 8.).tanh() * 0.9,
+            };
+            engine.process_sample([x, x]);
+            if i % 1600 == 0 {
+                ballast_state.accept_frame(engine.take_analyzer());
+            }
+        }
+        ballast_state.accept_frame(engine.take_analyzer());
+    }
     let mut weld_settings = weld_core::Settings::default();
     let mut weld_state = weld_ui::State::default();
     if weld {
@@ -358,7 +416,11 @@ fn main() {
     let session_motif = session.motifs[0].id;
     shared.replace(session).unwrap();
     let ctx = egui::Context::default();
-    if braze {
+    if ballast {
+        ballast_ui::style(&ctx);
+    } else if quench {
+        quench_ui::style(&ctx);
+    } else if braze {
         braze_ui::style(&ctx);
     } else if planish {
         planish_ui::style(&ctx);
@@ -399,7 +461,11 @@ fn main() {
             },
             |ui| {
                 egui::CentralPanel::default().show(ui, |ui| {
-                    if braze {
+                    if ballast {
+                        ballast_ui::show(ui, &mut ballast_settings, &mut ballast_state);
+                    } else if quench {
+                        quench_ui::show(ui, &mut quench_settings, &mut quench_state);
+                    } else if braze {
                         braze_ui::show(ui, &mut braze_settings, &mut braze_state);
                     } else if planish {
                         planish_ui::show(ui, &mut planish_settings, &mut planish_state);

website/src/data/plugins.ts

@@ -199,6 +199,36 @@ const COPY: Record<string, Copy> = {
     latency: '≈ 67 ms',
     tracksNotes: true,
   },
+  quench: {
+    role: 'Sub-safe clipper',
+    metal: 'Quenching hardens hot metal in one fast step.',
+    problem:
+      'Hard-clipped masters clip the sub with the top: near the sub’s peaks only one side of the top clips, so the sub loses level and the low end fills with products that were not in the mix.',
+    points: [
+      'The sub below Split passes unclipped; the top is clipped in the room the sub leaves under the ceiling.',
+      'What the clip removes is high-passed, so its products stay out of the low band.',
+      'Compare against a plain clipper, or hear only what Quench takes away.',
+      'A meter shows how much the low end changed, for Quench and for a plain clip.',
+    ],
+    loadOn: 'Master or bass bus, last',
+    latency: '< 1 ms',
+    tracksNotes: false,
+  },
+  ballast: {
+    role: 'Switch-up leveller',
+    metal: 'Ballast is the weight that keeps a ship level.',
+    problem:
+      'Patches at the same peak level still sound louder or quieter, so every switch-up lands at a different loudness and gets hand-set gain or clipping. A compressor evens them out but changes their punch.',
+    points: [
+      'One gain per part: nothing moves inside a note or switch-up.',
+      'Parts start at note starts, from the audio or MIDI, or on the host’s beat grid.',
+      'Loudness is K-weighted (BS.1770) over each part’s first 100 ms; Learn takes a reference part.',
+      'Measure from leaves the sub out of the measurement when Anvil makes it.',
+    ],
+    loadOn: 'Bass, after the sound design',
+    latency: '≈ 172 ms',
+    tracksNotes: true,
+  },
 };
 
 export interface Plugin extends Copy {