fix(website): spell plugin counts above ten in the hero

PLUGINS grew to 13, past the end of the number-word list, so the count fell back to a number and toUpperCase failed during the static build.
chore: release Forge 0.1.0
2026-11-06 17:51:19 +01:00 · 2026-11-06 17:48:49 +01:00 · 2026-11-06 17:36:31 +01:00 · 2026-11-06 17:29:54 +01:00 · 2026-11-06 16:30:23 +01:00 · 2026-11-06 16:30:22 +01:00
270 changed files with 66042 additions and 533 deletions
@@ -22,7 +22,7 @@ jobs:
    strategy:
      fail-fast: false
      matrix:
-        plugin: [rivet, patina]
+        plugin: [rivet, patina, anvil, crucible, lathe, temper, weld, knurl, planish, braze, quench, ballast, forge]
    steps:
      - uses: https://github.com/actions/checkout@v4
        with:
@@ -56,6 +56,17 @@ jobs:
          cargo run --manifest-path tools/editor-check/Cargo.toml --locked -- target/editor/rivet.png --plugin rivet
          cargo run --manifest-path tools/editor-check/Cargo.toml --locked -- target/editor/patina.png --plugin patina
          cargo run --manifest-path tools/editor-check/Cargo.toml --locked -- target/editor/patina-compact.png --plugin patina --compact
+          cargo run --manifest-path tools/editor-check/Cargo.toml --locked -- target/editor/anvil.png --plugin anvil
+          cargo run --manifest-path tools/editor-check/Cargo.toml --locked -- target/editor/crucible.png --plugin crucible
+          cargo run --manifest-path tools/editor-check/Cargo.toml --locked -- target/editor/lathe.png --plugin lathe
+          cargo run --manifest-path tools/editor-check/Cargo.toml --locked -- target/editor/temper.png --plugin temper
+          cargo run --manifest-path tools/editor-check/Cargo.toml --locked -- target/editor/weld.png --plugin weld
+          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
+          cargo run --manifest-path tools/editor-check/Cargo.toml --locked -- target/editor/forge.png --plugin forge
      - uses: https://github.com/actions/upload-artifact@v3-node20
        with:
          name: editor-previews
@@ -81,11 +92,22 @@ jobs:
      - run: |
          python3 scripts/build-plugin.py --plugin rivet --target x86_64-pc-windows-gnu
          python3 scripts/build-plugin.py --plugin patina --target x86_64-pc-windows-gnu
+          python3 scripts/build-plugin.py --plugin anvil --target x86_64-pc-windows-gnu
+          python3 scripts/build-plugin.py --plugin crucible --target x86_64-pc-windows-gnu
+          python3 scripts/build-plugin.py --plugin lathe --target x86_64-pc-windows-gnu
+          python3 scripts/build-plugin.py --plugin temper --target x86_64-pc-windows-gnu
+          python3 scripts/build-plugin.py --plugin weld --target x86_64-pc-windows-gnu
+          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/build-plugin.py --plugin forge --target x86_64-pc-windows-gnu
          python3 scripts/package-windows.py
      - uses: https://github.com/actions/upload-artifact@v3-node20
        with:
-          name: rivet-patina-windows-x86_64
+          name: bass-foundry-windows-x86_64
          path: |
-            dist/rivet-patina-windows-x86_64.zip
-            dist/rivet-patina-windows-x86_64.zip.sha256
+            dist/bass-foundry-windows-x86_64.zip
+            dist/bass-foundry-windows-x86_64.zip.sha256
          retention-days: 30
@@ -1,7 +1,7 @@
 name: Independent plugin release
 on:
  push:
-    tags: ["rivet-v*", "patina-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*", "forge-v*"]

 permissions:
  contents: read
@@ -30,24 +30,92 @@ dependencies = [
 "zerocopy",
 ]

+[[package]]
+name = "anvil-core"
+version = "0.1.0"
+dependencies = [
+ "common-dsp",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "anvil-ui"
+version = "0.1.0"
+dependencies = [
+ "anvil-core",
+ "common-dsp",
+ "common-ui",
+ "egui",
+]
+
 [[package]]
 name = "autocfg"
 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"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06"

+[[package]]
+name = "braze-core"
+version = "0.1.0"
+dependencies = [
+ "common-dsp",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "braze-ui"
+version = "0.1.0"
+dependencies = [
+ "braze-core",
+ "common-dsp",
+ "common-ui",
+ "egui",
+]
+
 [[package]]
 name = "cfg-if"
 version = "1.0.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"

+[[package]]
+name = "common-dsp"
+version = "0.1.0"
+
+[[package]]
+name = "common-ui"
+version = "0.1.0"
+dependencies = [
+ "egui",
+]
+
 [[package]]
 name = "crossbeam-queue"
 version = "0.3.14"
@@ -63,6 +131,26 @@ version = "0.8.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a31eee39dddec8330830986fcd7625edb5a24ec90ea038215273bbc3adb08ac6"

+[[package]]
+name = "crucible-core"
+version = "0.1.0"
+dependencies = [
+ "common-dsp",
+ "crossbeam-queue",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "crucible-ui"
+version = "0.1.0"
+dependencies = [
+ "common-dsp",
+ "common-ui",
+ "crucible-core",
+ "egui",
+]
+
 [[package]]
 name = "ecolor"
 version = "0.31.1"
@@ -114,12 +202,78 @@ version = "0.31.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "fc7e7a64c02cf7a5b51e745a9e45f60660a286f151c238b9d397b3e923f5082f"

+[[package]]
+name = "forge-core"
+version = "0.1.0"
+dependencies = [
+ "common-dsp",
+ "knurl-core",
+ "lathe-core",
+ "serde",
+ "serde_json",
+ "temper-core",
+]
+
+[[package]]
+name = "forge-ui"
+version = "0.1.0"
+dependencies = [
+ "common-dsp",
+ "common-ui",
+ "egui",
+ "forge-core",
+ "knurl-core",
+ "knurl-ui",
+ "lathe-core",
+ "lathe-ui",
+ "temper-core",
+ "temper-ui",
+]
+
 [[package]]
 name = "itoa"
 version = "1.0.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"

+[[package]]
+name = "knurl-core"
+version = "0.1.0"
+dependencies = [
+ "common-dsp",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "knurl-ui"
+version = "0.1.0"
+dependencies = [
+ "common-dsp",
+ "common-ui",
+ "egui",
+ "knurl-core",
+]
+
+[[package]]
+name = "lathe-core"
+version = "0.1.0"
+dependencies = [
+ "common-dsp",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "lathe-ui"
+version = "0.1.0"
+dependencies = [
+ "common-dsp",
+ "common-ui",
+ "egui",
+ "lathe-core",
+]
+
 [[package]]
 name = "libc"
 version = "0.2.191"
@@ -216,6 +370,7 @@ dependencies = [
 name = "patina-core"
 version = "0.2.0"
 dependencies = [
+ "common-dsp",
 "rustfft",
 "serde",
 "serde_json",
@@ -233,10 +388,30 @@ dependencies = [
 name = "patina-ui"
 version = "0.2.0"
 dependencies = [
+ "common-ui",
 "egui",
 "patina-core",
 ]

+[[package]]
+name = "planish-core"
+version = "0.1.0"
+dependencies = [
+ "common-dsp",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "planish-ui"
+version = "0.1.0"
+dependencies = [
+ "common-dsp",
+ "common-ui",
+ "egui",
+ "planish-core",
+]
+
 [[package]]
 name = "primal-check"
 version = "0.3.4"
@@ -261,6 +436,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"
@@ -409,6 +603,25 @@ dependencies = [
 "unicode-ident",
 ]

+[[package]]
+name = "temper-core"
+version = "0.1.0"
+dependencies = [
+ "common-dsp",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "temper-ui"
+version = "0.1.0"
+dependencies = [
+ "common-dsp",
+ "common-ui",
+ "egui",
+ "temper-core",
+]
+
 [[package]]
 name = "transpose"
 version = "0.2.3"
@@ -437,6 +650,25 @@ version = "0.9.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"

+[[package]]
+name = "weld-core"
+version = "0.1.0"
+dependencies = [
+ "crossbeam-queue",
+ "rustfft",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "weld-ui"
+version = "0.1.0"
+dependencies = [
+ "common-ui",
+ "egui",
+ "weld-core",
+]
+
 [[package]]
 name = "windows-link"
 version = "0.2.1"
@@ -1,7 +1,7 @@
 [workspace]
 resolver = "2"
-members = ["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"]
+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/forge/core", "plugins/forge/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]
 edition = "2021"
@@ -16,3 +16,24 @@ rivet-midi = { path = "plugins/rivet/midi" }
 [profile.release]
 lto = "thin"
 strip = "symbols"
+
+# Signal-level tests render seconds of audio; unoptimised DSP makes them crawl.
+[profile.dev.package.common-dsp]
+opt-level = 2
+[profile.dev.package.lathe-core]
+opt-level = 2
+[profile.dev.package.temper-core]
+opt-level = 2
+[profile.dev.package.knurl-core]
+opt-level = 2
+[profile.dev.package.planish-core]
+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
+[profile.dev.package.forge-core]
+opt-level = 2
@@ -1,70 +1,223 @@
-# Rivet & Patina
+# Bass Foundry

-Two Rust CLAP plugins for writing and refining bass music.
+**Rust CLAP plugins for writing, designing and mixing bass music in FL Studio.**

-| Plugin | Purpose | Guide |
-| --- | --- | --- |
-| **Rivet** | Tell a MIDI motif as a story on a storyboard of roles, with joined seams | [Rivet](docs/rivet/README.md) |
-| **Patina** | Smooth harsh resonances while retaining tone and transient character | [Patina](docs/patina/README.md) |
+Website: [fl.narl.io](https://fl.narl.io)
+
+![CLAP](https://img.shields.io/badge/format-CLAP-6c5ce7)
+![FL Studio 2024.1+](https://img.shields.io/badge/FL%20Studio-2024.1%2B-ff8a00)
+![Windows x64](https://img.shields.io/badge/platform-Windows%20x64-0078d4)
+![Rust stable](https://img.shields.io/badge/Rust-stable-b7410e)
+![License ISC](https://img.shields.io/badge/license-ISC-2ea44f)
+
+Riddim and dubstep basses change patch on every switch-up. Fixed-frequency tools
+then act differently on every note: the sub jumps, an EQ cut lands on another
+harmonic, the distortion gets fizzy on one note and dull on the next. Most plugins
+in this suite follow the played note, so a setting means the same thing on every
+note. Each plugin is a separate product with its own version, guide and release.
+
+## Plugins
+
+| Plugin | What it does | Load it on | Latency | Docs |
+| --- | --- | --- | --- | --- |
+| **[Rivet](docs/rivet/README.md)** | Tells a MIDI motif as a story on a storyboard of roles and joins the seams into one phrase | Channel Rack | none | [Guide](docs/rivet/README.md) · [Changes](docs/rivet/CHANGELOG.md) |
+| **[Patina](docs/patina/README.md)** | Smooths harsh, ringing resonances while plain harmonic tone and transients pass | Any mixer track | one analysis frame | [Guide](docs/patina/README.md) · [Changes](docs/patina/CHANGELOG.md) |
+| **[Anvil](docs/anvil/README.md)** | Replaces the sub with a clean mono sine: one level and one start phase on every note, locked to the kick | Bass bus, kick as sidechain | 80 ms | [Guide](docs/anvil/README.md) · [Changes](docs/anvil/CHANGELOG.md) |
+| **[Crucible](docs/crucible/README.md)** | Records the last bars all the time, then slices, cleans and exports key-labelled samples with one button | End of the chain to resample | none | [Guide](docs/crucible/README.md) · [Changes](docs/crucible/CHANGELOG.md) |
+| **[Lathe](docs/lathe/README.md)** | EQ with one band on each harmonic of the played note: a cut on harmonic 3 stays on harmonic 3 | Bass, after the synth | ≈ 67 ms | [Guide](docs/lathe/README.md) · [Changes](docs/lathe/CHANGELOG.md) |
+| **[Temper](docs/temper/README.md)** | Distortion that drives every note the same: level and tone filters follow the note | Bass | ≈ 67 ms + oversampling | [Guide](docs/temper/README.md) · [Changes](docs/temper/CHANGELOG.md) |
+| **[Weld](docs/weld/README.md)** | Phase-aligns one bass layer to another layer through the sidechain, so the layers sum in the mids instead of cancelling | One layer's track, other layer as sidechain | none | [Guide](docs/weld/README.md) · [Changes](docs/weld/CHANGELOG.md) |
+| **[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) |
+| **[Forge](docs/forge/README.md)** | Lathe, Temper and Knurl as one channel strip behind one note tracker, in any order: one lookahead, and no module hears Knurl's sub-octave | Bass, after the synth | ≈ 72 ms | [Guide](docs/forge/README.md) · [Changes](docs/forge/CHANGELOG.md) |
+
+Plugins with latency report it to the host, so FL Studio compensates the delay.
+Anvil, Lathe, Temper, Knurl, Planish, Braze, Ballast and Forge 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
-surface while leaving its character. They share a Rust foundation and keep
-their own musical purpose, code, documentation, and version.
+surface and keeps its character; an **anvil** is the solid base that everything
+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; **quenching** hardens hot metal in one
+fast step; **ballast** is the weight that keeps a ship level; a **forge** is the hearth where
+every piece is heated and worked.
+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*.
+
+## Editors
+
+<table>
+  <tr>
+    <td width="50%"><a href="docs/rivet/README.md"><img src="docs/rivet/assets/editor.png" alt="Rivet editor"></a><br><b>Rivet</b>: storyboard composition</td>
+    <td width="50%"><a href="docs/patina/README.md"><img src="docs/patina/assets/editor.png" alt="Patina editor"></a><br><b>Patina</b>: resonance smoothing</td>
+  </tr>
+  <tr>
+    <td><a href="docs/anvil/README.md"><img src="docs/anvil/assets/editor.png" alt="Anvil editor"></a><br><b>Anvil</b>: sub anchor</td>
+    <td><a href="docs/crucible/README.md"><img src="docs/crucible/assets/editor.png" alt="Crucible editor"></a><br><b>Crucible</b>: resampler</td>
+  </tr>
+  <tr>
+    <td><a href="docs/lathe/README.md"><img src="docs/lathe/assets/editor.png" alt="Lathe editor"></a><br><b>Lathe</b>: harmonic EQ</td>
+    <td><a href="docs/temper/README.md"><img src="docs/temper/assets/editor.png" alt="Temper editor"></a><br><b>Temper</b>: tracked distortion</td>
+  </tr>
+  <tr>
+    <td><a href="docs/weld/README.md"><img src="docs/weld/assets/editor.png" alt="Weld editor"></a><br><b>Weld</b>: layer phase alignment</td>
+    <td><a href="docs/knurl/README.md"><img src="docs/knurl/assets/editor.png" alt="Knurl editor"></a><br><b>Knurl</b>: cycle texture</td>
+  </tr>
+  <tr>
+    <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>
+  <tr>
+    <td><a href="docs/forge/README.md"><img src="docs/forge/assets/editor.png" alt="Forge editor"></a><br><b>Forge</b>: tracked channel strip</td>
+  </tr>
+</table>
+
+The previews are rendered headless from the real editor code by
+`tools/editor-check`, so they match what the plugin draws.

 ## Install

-Download the desired plugin's Windows ZIP from its Gitea release. Extract it
-and copy `Rivet.clap` or `Patina.clap` into:
+1. Open the plugin's release on Gitea. Every plugin has its own release tag,
+   for example `lathe-v0.1.0`.
+2. Download `<plugin>-windows-x86_64-<version>.zip`. You can check it against
+   the `.zip.sha256` file next to it.
+3. Extract the ZIP and copy the `.clap` file into:

-```text
-C:\Program Files\Common Files\CLAP\
+   ```text
+   C:\Program Files\Common Files\CLAP\
+   ```
+
+4. In FL Studio 2024.1 or newer, open **Options → Manage plugins**, enable
+   **Verify plugins**, and click **Find installed plugins**.
+5. Load Rivet in the Channel Rack. Load the other plugins in mixer effect slots.
+
+Keep the font license (`licenses/`) with redistributed packages.
+
+Every branch and pull-request pipeline also builds a combined Windows preview
+ZIP, `bass-foundry-windows-x86_64.zip`, in its **windows** job. Use it to test unreleased changes.
+
+> **Upgrading from an earlier build?** The CLAP IDs changed from
+> `io.storyboard.*` to `io.narl.bass-foundry.<product>`, so hosts see each
+> plugin as new. Delete the old `.clap` files, rescan, and add the plugins again
+> in existing projects. Motif Storyboard and Resonance Compressor are now Rivet
+> and Patina, and the vendor is "Bass Foundry".
+
+## Build from source
+
+You need:
+
+- Rust stable and Python 3.11 or newer.
+- For the Windows target on Linux: the `x86_64-pc-windows-gnu` Rust target and
+  MinGW (`x86_64-w64-mingw32-gcc`).
+- For the native wrapper tests on Linux: pkg-config and the X11/XCB and OpenGL
+  development headers. Rivet's optional standalone also needs ALSA/JACK headers.
+
+```sh
+# Tests for all engines, editors and tools
+cargo test --workspace --locked
+
+# Formatting, tests and lints for one product, including its CLAP wrapper
+python3 scripts/check-plugin.py --plugin lathe
+
+# Windows build, then the ZIPs (all plugins, or --plugin <name>)
+python3 scripts/build-plugin.py --plugin lathe --target x86_64-pc-windows-gnu
+python3 scripts/package-windows.py
+
+# Headless editor preview
+cargo run --manifest-path tools/editor-check/Cargo.toml -- target/editor/lathe.png --plugin lathe
 ```

-In FL Studio 2024.1 or newer, open **Options → Manage plugins**, enable
-**Verify plugins**, and **Find installed plugins**. Load Rivet in the Channel Rack;
-load Patina in a mixer effect slot.
+Plugin names for the scripts are `rivet`, `patina`, `anvil`, `crucible`,
+`lathe`, `temper`, `weld`, `knurl`, `planish`, `braze`, `quench`, `ballast` and `forge`. 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.

-Normal branch/PR pipelines also provide a combined Windows preview ZIP in the
-**windows** job. Releases are separate: `rivet-v0.3.0` and `patina-v0.2.0`
-publish independently. See [release workflow](docs/releases.md).
+## Quality checks

-These names replace Motif Storyboard and Resonance Compressor. Their CLAP IDs
-and saved-state identifiers are preserved; replace old scanned copies and rescan.
+Every push and pull request runs these checks in CI
+(`.gitea/workflows/check.yml`):
+
+- **Engine tests.** Every engine has tests for its signal behaviour and latency
+  against measured targets.
+- **Realtime safety.** Every audio effect has a test that fails if the audio
+  thread allocates memory.
+- **Host tests.** Each wrapper is loaded through the exported CLAP ABI, without
+  a DAW. The tests check the ports, the reported latency, state save and load,
+  and processing at 44.1, 48 and 96 kHz.
+- **Lints.** `rustfmt` and `clippy -D warnings` for every package and wrapper.
+- **Editor previews.** All editors are rendered headless and kept as CI
+  artifacts.
+- **Windows builds.** Every `.clap` is cross-compiled and packaged.
+
+Release ZIPs are deterministic and contain checksums for every file. Things CI
+cannot check stay manual: FL Studio routing, native window behaviour, and
+listening.

 ## Repository

 ```text
 plugins/
-  catalog.json         Product metadata used by build and release tools
-  rivet/
-    core/              Motifs, harmony, variation, history, performance
-    midi/              Standard MIDI import/export
-    app/               Worker jobs and real-time audition control
-    preview/           Offline MIDI/WAV development tool
-    plugin/            CLAP wrapper, editor, optional standalone
-  patina/
-    core/              Spectral detector and attenuation engine
-    ui/                Shared native editor and embedded fonts
-    render/            Offline WAV evaluation
-    plugin/            CLAP audio-effect wrapper
-tools/editor-check/    Headless visual QA for both editors
-scripts/               Shared build, packaging, release, and analysis tools
-docs/rivet/            Rivet guide, theory, research, and editor previews
-docs/patina/           Patina guide, research, and editor preview
-references/            Local reference audio; excluded from distribution
+  catalog.json         Product metadata for the build, check and release tools
+  rivet/               core · midi · app · preview · plugin
+  patina/              core · ui · render · plugin
+  anvil/               core · ui · plugin
+  crucible/            core · ui · plugin
+  lathe/               core · ui · plugin
+  temper/              core · ui · plugin
+  weld/                core · ui · plugin
+  knurl/               core · ui · plugin
+  planish/             core · ui · plugin
+  braze/               core · ui · plugin
+  quench/              core · ui · plugin
+  ballast/             core · ui · plugin
+  forge/               core · ui · plugin
+  common/
+    ui/                Shared look: palette, embedded fonts, knobs, panels, meters
+    dsp/               Shared filters, pitch tracking, oversampling, meters, WAV files
+tools/editor-check/    Headless editor renderer for visual QA
+scripts/               Build, check, packaging, release and analysis tools
+docs/<plugin>/         Guide, changelog and editor preview for each plugin
+docs/ideas.md          Problems in bass-music production and the plugin ideas for them
+references/            Local reference audio; never distributed
+website/               The fl.narl.io site: Astro, nginx container, reads catalog and previews
 ```

-The root Cargo workspace contains the engines and supporting tools. Each CLAP
-wrapper has an independent workspace and lockfile so SDK dependencies stay
-separate. [Development and testing](docs/development.md) covers the commands.
+Each product follows the same split:

-```sh
-cargo test --workspace --locked
-python scripts/build-plugin.py --plugin rivet --target x86_64-pc-windows-gnu
-python scripts/build-plugin.py --plugin patina --target x86_64-pc-windows-gnu
-python scripts/package-windows.py
-```
+- `core` is the engine. It is plain Rust, does not depend on a plugin SDK, and
+  is tested on its own.
+- `ui` is the egui editor, built on `common-ui`.
+- `plugin` is the CLAP wrapper on a pinned NIH-plug revision.

-Windows is the release target. Linux remains useful for tests, cross-compilation,
-and headless editor previews. FL Studio routing, native window behavior, and
-artistic listening still require manual checks in the target setup.
+The root Cargo workspace holds the engines, editors and tools. Each wrapper is
+its own workspace with its own lockfile, so SDK dependencies stay separate.
+`plugins/catalog.json` is the single list of products. The scripts and CI read
+it, so adding a plugin starts there.
+
+## Releases
+
+Each plugin is versioned and released on its own. Its version is the `version`
+in `plugins/<plugin>/plugin/Cargo.toml`. A tag `<plugin>-v<version>`, for example
+`temper-v0.1.0`, starts the release workflow. The workflow builds, checks and
+publishes that plugin's Windows ZIP to a Gitea release. See
+[docs/releases.md](docs/releases.md).
+
+## Roadmap
+
+[docs/ideas.md](docs/ideas.md) lists the production problems the suite targets,
+the released plugins and the ideas for the next ones.
+
+## License
+
+ISC, see [LICENSE](LICENSE). The embedded Roboto Condensed fonts are under the
+SIL Open Font License ([OFL.txt](plugins/common/ui/assets/OFL.txt)).
@@ -0,0 +1,34 @@
+# Anvil changelog
+
+## 0.3.0
+
+- Add Ghost harmonics: **Ghost** and **Ghost from** add the sub's harmonics 2–10
+  above a chosen frequency, so phones hear the note. Anvil measures the patch's own
+  harmonics above the split and fills only the ones that are missing. The sub level
+  does not change.
+- Add **Phone**, a listen mode: mono, band-limited to 400 Hz–7 kHz. Not saved.
+- Show the patch's harmonics and the added ones in an inset in the scope.
+- Add Kick lock: with the kick in the sidechain, each kick ducks the sub
+  (**Duck**, **Release**) and restarts it at Phase, shifted by **Offset**
+  (−30 to +30 ms, also before the kick).
+- Add the offset **Audition**: steps the offset from −30 to +30 ms, 4 kicks each,
+  shows how kick and sub summed per offset, and **Keep** takes the offset heard.
+- Anvil now has a sidechain input named Kick. Without Kick lock it is ignored.
+
+## 0.2.0
+
+- Change the CLAP ID to `io.narl.bass-foundry.anvil`. Hosts see this as a new
+  plugin: delete the old `.clap` file, rescan, and add the plugin again in
+  existing projects.
+
+## 0.1.0
+
+- Introduce Anvil, a sub anchor for bass music.
+- Replace the band below Split with a clean mono sine. Every note gets the same
+  peak level and starts at the same phase, so switch-ups and kick hits line up.
+- Detect pitch and note starts from the audio with 80 ms lookahead, or follow
+  MIDI notes sent to the effect.
+- Controls: Sub level, Split, Dynamics, Drive, Octave, Glide, Phase, Gate, Keep,
+  Output, Retrigger, Snap to semitone, Bypass. Solo sub monitors only the new sub.
+- Note readout, level meters and an oscilloscope of the original low band against
+  the new sub.
@@ -0,0 +1,127 @@
+# Anvil
+
+Anvil gives every bass note the same solid sub. Current version **0.3.0**.
+
+In riddim and dubstep, each switch-up patch brings its own sub: a different level,
+a different phase, sometimes two layers that cancel. The drop's weight jumps from
+note to note and the kick lands differently on each one. Anvil removes the
+original band below **Split** and puts a clean mono sine in its place. The sine
+follows the bass pitch, has the same peak level on every note, and starts at the
+same phase on every note.
+
+![Anvil](assets/editor.png)
+
+## Install on Windows
+
+Copy `Anvil.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 Anvil in the mixer slot of the bass bus. Keep the font license with
+redistributed packages.
+
+## Work with it
+
+1. Put Anvil on the bass bus, after the sound design and before the bus
+   compression or clipping.
+2. Set **Split** just above the sub. 80–100 Hz suits most riddim basses.
+3. Set **Sub level** once. Every patch on the bus now gets this level.
+4. Use **Phase** to line the start of each note up with your kick. With
+   **Retrigger** on, every note starts at this phase.
+5. Turn on **Solo sub** to hear only the new sub; the scope shows the original
+   low band (grey) against the new sub (accent).
+6. Turn on **Phone** to check the drop the way phones and laptop speakers play
+   it: mono, nothing below 400 Hz. A clean sub vanishes there. If the note
+   disappears with it, raise **Ghost**.
+
+### Ghost harmonics
+
+Phone speakers play almost nothing below 300–500 Hz. A clean 50 Hz sub sends all
+its energy below that, so on a phone the note is gone. The ear rebuilds a note's
+pitch from its harmonics, so harmonics alone carry the note.
+
+**Ghost** adds the sub's harmonics 2–10 above **Ghost from**, falling 1/k like a
+saw. At 100 %, harmonic k sits at 2/k of the sub's level. They fade in over half
+an octave above Ghost from, and never reach below Split. The sub itself does not
+change, so the weight on a club system stays where Sub level puts it.
+
+Anvil measures each harmonic of the patch above the split and adds only what is
+missing. A harmonic the patch already has meets an added one at an unrelated
+phase and could cancel it, so Ghost leaves those alone. The inset in the scope
+shows both, per harmonic: what the patch carries (grey) and what Ghost adds
+(accent). A riddim patch usually needs little; 808s and clean sine subs need the
+most. Each new note is measured from its first 60 ms; during that time every
+harmonic counts as missing.
+
+Drive works differently: it saturates the sine itself, adds only odd harmonics,
+and changes the sub's own shape.
+
+### Kick lock
+
+With **Retrigger**, every note starts at Phase, but a kick that falls in the
+middle of a long note meets the sub at whatever phase it has reached. Kick lock
+listens to the kick through the sidechain. On each kick it dips the sub by
+**Duck** (coming back over **Release**) and restarts the sub at Phase, so the
+kick and the sub meet the same way on every hit.
+
+Set it up in FL Studio:
+
+1. Select the kick's mixer track. Right-click the route arrow under the bass
+   bus and choose **Sidechain to this track**. The kick still goes to the
+   master on its own; the sidechain only lets Anvil hear it.
+2. In Anvil's plugin wrapper, open the settings (gear icon) and set the
+   sidechain input to the kick's track.
+3. Turn on **Kick lock**. The kick count under the switch must rise with the
+   kicks.
+
+**Offset** moves the restart against the kick, from 30 ms before it to 30 ms
+after. Kicks are found on the undelayed sidechain, so with the lookahead the
+sub can restart before the kick is heard.
+
+Where the kick and sub sound like one hit is not always where they sum
+loudest: offsets one period of the note apart sum the same, and the attack of
+the kick decides where the hit is heard. So the offset is set by ear:
+
+1. Turn on **Audition** and play a loop with kicks and a long bass note. Each
+   offset from −30 to +30 ms plays for 4 kicks; the line under the bars says
+   which one plays now.
+2. Press **Keep** when kick and sub sound like one hit. Offset takes that
+   value and the audition stops.
+
+The bars show, per offset, how the kick and the sub summed below 150 Hz in the
+60 ms after each hit: +3 dB is a full sum of equal levels, 0 dB unrelated,
+below 0 dB they cancel. Use them to check the choice, not to make it.
+
+Other controls:
+
+- **Dynamics** at 0 % holds the level for the whole note. Raise it to let the sub
+  follow the original's volume shape, for example a wobble.
+- **Drive** saturates the sine: odd harmonics and a thicker sub.
+- **Octave** moves the sub against the detected note. Use −1 for a bass played
+  one octave up.
+- **Glide** slides between overlapping notes; 0 jumps.
+- **Gate** is the input level that counts as a note. Raise it if tails or reverb
+  start new notes.
+- **Keep** blends some of the original low band back under the new sub.
+- **Snap to semitone** rounds detected pitch. Turn it off for pitch bends and slides.
+
+If Knurl is on the bass before the bus, use **MIDI**: Knurl's patterns make
+detection read notes from C2 upwards an octave low. See
+[Signal chain](../chain.md).
+
+### Pitch from MIDI
+
+Detection follows the audio by default. For heavy formant or FM basses where the
+fundamental is unclear, select **MIDI** and route the bass's MIDI notes to Anvil.
+In FL Studio, set the bass channel's MIDI output port and Anvil's input port to the
+same number, or duplicate the notes into a pattern on a channel that feeds Anvil.
+
+## Timing and limits
+
+Detection uses 80 ms of lookahead, reported to the host for delay compensation,
+so each note's pitch is known before its attack leaves the plugin. Pitch range is
+25–250 Hz, one voice: chords and layered notes in the sub band are not separated.
+Notes shorter than about 15 ms may not be recognised. A pitch move of more than
+0.7 semitone that holds for two analysis hops (10 ms) starts a new note.
+
+The crossover is a 4th-order Linkwitz–Riley pair, so with Keep at 100 % and no
+note playing, the signal passes with flat magnitude. Stereo above the split is
+kept; the new sub is mono.
@@ -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.
@@ -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.
@@ -0,0 +1,18 @@
+# Braze changelog
+
+## 0.1.0
+
+- Introduce Braze, a detuned copy of the bass whose beating stays on the tempo
+  grid on every note.
+- The chosen harmonic (1–8) beats once per Rate note value (1/1 to 1/32, and
+  triplets); harmonic n beats n/harmonic times as fast, so every harmonic beats
+  on the grid. The beat peaks land on the host's beat position.
+- The detune follows the tracked note. The copy jumps by exactly one period of
+  the note, so the jumps are seamless on a steady note.
+- Low cut keeps the copy out of the sub, so the sub neither beats nor changes
+  level.
+- Depth, Width (right channel's beat against the left), Phase, Gate, Output,
+  Snap to semitone, Bypass.
+- Detect pitch and note starts from the audio with about 67 ms of latency, or
+  follow MIDI notes sent to the effect.
+- Editor: one bar of the beat per harmonic with the grid and a playhead.
@@ -0,0 +1,76 @@
+# Braze
+
+Braze makes a reese's movement play in time. Current version **0.1.0**.
+
+Two layers detuned against each other beat: harmonic k of a note at f0 swells
+and fades k·f0·(r − 1) times per second, where r is the detune ratio. With a
+fixed detune that rate changes with every note, so the movement of a reese
+never lines up with the track. Braze adds a detuned copy of the bass and sets
+its detune on every note so that the beating follows the tempo.
+
+![Braze](assets/editor.png)
+
+## Install on Windows
+
+Copy `Braze.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 Braze in the mixer slot of the bass. Keep the font license with
+redistributed packages.
+
+## Work with it
+
+1. Put Braze on a single bass layer: a plain saw, or a reese whose own detune
+   you have turned down.
+2. Pick **Rate**: the note value one beat lasts. 1/8 at 140 BPM is 4.67 beats
+   per second.
+3. Pick the **harmonic** that should beat at Rate. Harmonic n beats
+   n/harmonic times as fast, so all of them beat on the grid: with harmonic 4 at
+   1/8, harmonic 2 beats in quarters, harmonic 8 in sixteenths, harmonic 3 in
+   quarter triplets.
+4. Set **Depth**. At 100 % the beating goes down to full nulls; 50–70 % keeps
+   the note present.
+5. Use **Phase** to move where the beat peaks. At 0° all harmonics peak
+   together on every beat of the chosen harmonic's cycle.
+
+The display shows one bar: a row per harmonic with the level it gets from the
+beating, the grid at Rate, and the playhead.
+
+Other controls:
+
+- **Low cut** removes the copy below a frequency, so the sub does not beat.
+  The sub keeps its level. Harmonics under the cut show *cut* in the display.
+  Under 20 Hz the cut is off. If the chosen harmonic is under the cut on a
+  note, it does not beat: the note panel says so; pick a higher harmonic.
+- **Width** moves the right channel's beat against the left, up to half a
+  cycle. At 100 % one side peaks while the other nulls. Check the mono sum.
+- **Gate** is the input level that counts as a note.
+- **Snap to semitone** rounds the detected pitch. Leave it off on detuned or
+  bent notes: the copy jumps by one period of the pitch in use.
+
+### How the detune is made
+
+The copy is the bass read from a delay line. Its delay falls by one period of
+the note per beat cycle of the chosen harmonic, which tunes the copy up by
+exactly r = 1 + B/(k·f0) (B: beats per second, k: the chosen harmonic). When it
+has fallen a whole period, it jumps back by one period: on a steady note both
+read positions hold the same waveform, so the jump is crossfaded over 6 ms
+without a seam. At a beat peak the copy lines up with the bass sample for
+sample.
+
+The low detune that low notes need is large: harmonic 1 at 1/8 and 140 BPM on
+F1 (43.7 Hz) is r = 1.107, about 1.8 semitones. Higher harmonics need less:
+harmonic 4 asks for about 45 cents on F1.
+
+## Timing and limits
+
+Detection uses about 67 ms of lookahead, reported to the host for delay
+compensation. Pitch range is 30–500 Hz, one voice. The beat position comes from
+the host while it plays, shifted by the lookahead so the beat stays on the
+timeline. When the host is stopped, the beat runs on freely at the last tempo.
+
+Noise, chords and the attack of a note are not periodic, so the copy's jumps
+are heard there as a short blur. Before the first note, the copy assumes 55 Hz.
+
+Braze changes the waveform in time, so pitch detection after it can be less
+sure: put tracked plugins before Braze, or use MIDI. See
+[Signal chain](../chain.md).
@@ -0,0 +1,78 @@
+# Signal chain
+
+The order of the Bass Foundry plugins in a chain matters. Anvil, Lathe, Temper,
+Knurl, Planish, Braze, Ballast and Forge 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 → Ballast → Weld
+  or:         synth → Forge (Lathe, Temper, Knurl) → Planish → Braze → 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
+  is clear.
+- **Or Forge in their place.** Forge runs Lathe, Temper and Knurl behind one
+  tracker that reads its input, so the order inside it does not upset the pitch
+  detection, and the three cost one lookahead (about 72 ms) instead of three.
+  Planish and Braze then come after Knurl: run them from MIDI.
+- **Planish after the distortion, before Knurl.** OTT usually comes after
+  distortion. Planish's band edges follow the tracked note, so it also needs a
+  clear pitch: after Knurl, use MIDI.
+- **Braze after Planish.** Its copy beats against the bass, so a pitch
+  detector after it is less sure: Knurl after Braze works best in MIDI mode.
+  Weld after Braze sees the beating as a looser match between the layers; if
+  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.
+- **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
+  layer but cannot move it earlier. If FL Studio does not compensate the
+  sidechain route, any latency added after Weld's input on the main layer makes
+  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
+
+Knurl's patterns make every second (or third) cycle quieter. That is a real
+sub-octave in the signal, so a pitch detector after Knurl hears the note one
+octave low, or with Triple an octave and a fifth low. Measured with the suite's
+tracker on a saw bass:
+
+- From C2 (65 Hz) upwards, Double, Fry (the default), Triple and Gallop make
+  the detector read the wrong octave for about 85 % of the note.
+- Below C2 the false sub-octave is under 30 Hz, out of the detection range, so
+  low notes are tracked correctly.
+- Level and time jitter add 5–25 false note starts per second. Anvil restarts
+  its phase on each, Lathe, Temper and Planish retune on each.
+
+When a tracked plugin must come after Knurl, select **MIDI** as its pitch source
+and route the bass's MIDI notes to it. Inside Forge this does not apply: its one
+tracker reads the input before Knurl.
+
+## 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, Ballast
+about 172 ms, Quench under 1 ms. Forge holds Lathe, Temper and Knurl in about
+72 ms, against about 206 ms for the three plugins in a row. 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
+rest for the mix.
@@ -0,0 +1,26 @@
+# Crucible changelog
+
+## 0.3.0
+
+- **Keep takes** (on by default) saves every capture's loop to a `takes`
+  subfolder of the export folder at once. Takes are still not part of the
+  project, but a reload or a crash no longer loses them. Existing files are
+  never overwritten.
+
+## 0.2.0
+
+- Change the CLAP ID to `io.narl.bass-foundry.crucible`. Hosts see this as a new
+  plugin: delete the old `.clap` file, rescan, and add the plugin again in
+  existing projects.
+
+## 0.1.0
+
+- Introduce Crucible, a resampler that always records its input.
+- Capture the newest 1–16 complete bars on the host's bar grid, or the newest
+  audio when the transport is stopped. Tempo changes inside a take are followed.
+- Slice on a straight or triplet grid, or at transients. Add and remove cuts by
+  hand, include or exclude slices, and audition them in place.
+- Clean every slice: trim leading silence, fade both ends, normalise to −0.3 dBFS.
+  The root note of each pitched slice is detected and written into the file.
+- Export the loop, every slice, and optionally a 2048-sample wavetable for Serum
+  and Vital into a dated folder.
@@ -0,0 +1,63 @@
+# Crucible
+
+Crucible melts the bars you just played into ready-to-use samples. Current version
+**0.3.0**.
+
+Resampling is the core loop of riddim sound design: bounce, open in Edison, chop,
+trim, declick, normalise, find the key, name, save, load into a sampler. Crucible
+does all of it from one button. It always records its input, so the take you
+liked is already there when you press **Capture**.
+
+![Crucible](assets/editor.png)
+
+## Install on Windows
+
+Copy `Crucible.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 Crucible in a mixer slot at the end of the chain you want
+to resample. Keep the font license with redistributed packages.
+
+## Work with it
+
+1. Play the pattern or song section.
+2. Choose **Bars** (1–16) and press **Capture**. Crucible takes the newest complete
+   bars on FL's bar grid. With the transport stopped, it takes the newest audio at
+   the last known tempo instead.
+3. Choose how to slice: **Grid** (1/4, 1/8, 1/16, 1/8T, 1/16T) or **Transients**
+   with a Sensitivity. Double-click the waveform to add a cut, right-click to remove
+   the nearest one.
+4. Click a slice to hear it. Untick **Export** to leave it out.
+5. Press **Export**.
+
+Each export creates a folder named after the date, time and tempo, holding:
+
+- `loop.wav`: the whole take, for Slicex or Edison;
+- `s01_F1.wav`, `s02_G#1.wav`, …: one file per slice, named by its detected root
+  note. The root is also stored in the file's sampler chunk;
+- `wavetable.wav` when **Wavetable** is on: up to 256 single-cycle frames of 2048
+  samples from the selected slice. Each frame starts on a rising zero crossing, so
+  frames morph without phase jumps. Serum reads the frame size from the file; in
+  Vital, import it as a wavetable with 2048-sample frames.
+
+Every slice is cleaned on export: **Trim silence** removes leading silence below
+−60 dBFS, **Declick** fades both ends (default 2 ms), **Normalize** peaks it at
+−0.3 dBFS. Files are 32-bit float WAV at the session rate.
+
+Add the export folder to FL's browser once (Options → File settings → Browser extra
+search folders). New exports then appear there and can be dragged into channels,
+the playlist or Edison. **Open folder** shows the latest export in Explorer.
+
+## Timing and limits
+
+Crucible adds no latency and passes audio through untouched. Auditioned slices are
+mixed into its output only while they play. The history holds 72 s, enough for
+16 bars at 60 BPM. The newest eight takes stay in memory until the plugin is
+removed; they are not saved with the project. With **Keep takes** on (the
+default), every capture's loop is also written at once to
+`takes/<date>_<time>_<tempo>bpm_<bars>bars.wav` in the export folder, so a reload
+or a crash loses nothing. Existing files are never overwritten.
+
+Bar alignment follows the host's song position and time signature. Root notes are
+detected between 35 Hz and 1 kHz. Unpitched slices, such as drums or noise, get
+no note in their name. Transient slicing finds hits that rise out of quieter
+audio; for legato basses, slice on the grid.
@@ -1,93 +1,166 @@
 # Development

-Run commands from the repository root. Rust stable and Python **3.11 or newer**
-are required. Lockfiles are committed for the core workspace, both CLAP wrappers,
-and the headless editor tool.
+Run commands from the repository root. You need Rust stable and Python **3.11 or
+newer**. Lockfiles are committed for the root workspace, every CLAP wrapper and
+the headless editor tool. Use `--locked` so a build never changes them silently.

 ## Product boundaries

-The catalog in [plugins/catalog.json](../plugins/catalog.json) defines product
-names, wrapper manifests, documentation, internal packages, and distribution
-licenses. Shared build/check/release tools consume it. Each wrapper's Cargo
-package version is the authoritative release version.
+[plugins/catalog.json](../plugins/catalog.json) is the single list of products.
+For each product it defines the display name, the wrapper manifest, the library
+name, the documentation folder, the CLAP ID, the internal packages and the
+licenses to ship. The build, check, package and release scripts and the script
+tests read it. The version in each wrapper's `Cargo.toml` is the release version.

-The root workspace contains Rivet's core, MIDI, application, and offline preview
-crates, plus Patina's core, editor, and renderer. Wrappers under
-`plugins/<product>/plugin/` remain independent workspaces because they depend on
-a pinned NIH-plug Git revision. Their host identities and persistence stay separate.
+Every product has the same split:
+
+| Folder | Content | Workspace |
+| --- | --- | --- |
+| `plugins/<product>/core/` | Engine. Plain Rust, no plugin SDK, tested on its own | root |
+| `plugins/<product>/ui/` | egui editor, built on `common-ui` | root |
+| `plugins/<product>/plugin/` | CLAP wrapper on a pinned NIH-plug revision | own |
+
+Rivet has more crates in the root workspace (`midi`, `app`, `preview`), and
+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, Braze, Ballast and Forge (with the `Tracked`
+  module trait that lets Lathe, Temper and Knurl run behind one shared tracker),
+  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
+saved state are separate for every product.
+
+The engines run allocation-free on the audio thread. Analysis that is too heavy
+for the audio thread (Rivet's generation jobs, Weld's cross-spectrum and fit) runs on a worker
+thread. Data goes to the editor through lock-free queues.

 ## Checks

 ```sh
 cargo test --workspace --locked
 cargo clippy --workspace --all-targets --locked -- -D warnings
-python scripts/check-plugin.py --plugin rivet
-python scripts/check-plugin.py --plugin patina
-python -m unittest discover -s scripts/tests -v
+python3 scripts/check-plugin.py --plugin <product>
+python3 -m unittest discover -s scripts/tests -v
 ```

-The product check script checks formatting, tests, and lints that product's
-packages and wrapper without compiling the other plugin. Offline builds work
-once dependencies are cached; append `--offline` to manual Cargo commands.
+Products: `rivet`, `patina`, `anvil`, `crucible`, `lathe`, `temper`, `weld`,
+`knurl`, `planish`, `braze`, `quench`, `ballast`, `forge`.

-Native wrapper tests on Linux require pkg-config, X11/XCB, and OpenGL development
-headers. Rivet's optional standalone also needs ALSA/JACK headers. Gitea installs
-the headers needed by its check jobs.
+`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
+when you change a shared crate or the root workspace. Offline builds work once
+the dependencies are cached; add `--offline` to manual Cargo commands.
+
+The test types are:
+
+- **Engine tests** (`core/tests/dsp.rs` and similar) measure signal behaviour
+  and latency against fixed targets.
+- **Realtime tests** (`core/tests/realtime.rs`) install a counting allocator
+  and fail if the audio-thread path allocates.
+- **Host tests** (`plugin/tests/host.rs`) load the wrapper through the exported
+  CLAP ABI without a DAW. They check the ports, latency, state save and load,
+  and processing at 44.1, 48 and 96 kHz with odd block sizes.
+- **Script tests** (`scripts/tests/`) cover the catalog, release planning,
+  packaging and the publish client with fake transports. They also fail when a
+  catalog product is missing from a CI workflow.
+
+The native wrapper tests on Linux need pkg-config and the X11/XCB and OpenGL
+development headers. Rivet's optional standalone also needs ALSA/JACK headers.
+The Gitea check jobs install these headers.

 ## Windows builds

-On Windows, install Rust and the MSVC build tools. For Linux cross-compilation,
-install the Rust `x86_64-pc-windows-gnu` target and MinGW's
-`x86_64-w64-mingw32-gcc`.
+On Windows, install Rust and the MSVC build tools. To cross-compile on Linux,
+install the Rust `x86_64-pc-windows-gnu` target and MinGW
+(`x86_64-w64-mingw32-gcc`).

 ```sh
-python scripts/build-plugin.py --plugin rivet --target x86_64-pc-windows-gnu
-python scripts/build-plugin.py --plugin patina --target x86_64-pc-windows-gnu
-python scripts/package-windows.py
-python scripts/package-windows.py --plugin rivet
-python scripts/package-windows.py --plugin patina
+python3 scripts/build-plugin.py --plugin <product> --target x86_64-pc-windows-gnu
+python3 scripts/package-windows.py                    # combined preview ZIP
+python3 scripts/package-windows.py --plugin <product> # one product's release ZIP
 ```

-Build outputs use `dist/<target>/Rivet.clap` and `Patina.clap`, with docs and
-licenses retaining their directory structure. `CARGO_TARGET_DIR` is supported
-for sharing compilation between wrappers. MSVC packaging accepts
+Builds go to `dist/<target>/<Name>.clap`, with the docs and licenses in the same
+folder structure. `CARGO_TARGET_DIR` is supported for sharing one build
+directory between wrappers. MSVC packaging accepts
 `--target x86_64-pc-windows-msvc`.

-The combined ZIP is `dist/rivet-patina-windows-x86_64.zip`. Individual ZIPs use
-`<product>-windows-x86_64-<version>.zip`. Each ZIP has internal file checksums and
-an external `.zip.sha256`. ZIP metadata is deterministic; binaries still depend
-on the toolchain and build environment. Packaging includes only selected catalog
-entries, never old binaries left in `dist`.
+- The combined ZIP is `dist/bass-foundry-windows-x86_64.zip`. It holds every
+  product that has been built.
+- A product ZIP is `<product>-windows-x86_64-<version>.zip` and holds only that
+  product.

-Linux builds remain available for local development; CI produces Windows release
-binaries only. Neither build nor packaging installs plugins into a DAW.
+Every ZIP has a `SHA256SUMS` file inside and a `.zip.sha256` file next to it.
+ZIP metadata is deterministic; the binaries still depend on the toolchain and
+the build environment. Packaging takes only the selected catalog entries, never
+old binaries left in `dist`.
+
+Linux builds are for local development; CI produces only Windows binaries. No
+script installs a plugin into a DAW.

 ## Editor previews

 ```sh
-cargo run --manifest-path tools/editor-check/Cargo.toml -- /tmp/rivet.png --plugin rivet
-cargo run --manifest-path tools/editor-check/Cargo.toml -- /tmp/rivet-creative.png --plugin rivet --creative
-cargo run --manifest-path tools/editor-check/Cargo.toml -- /tmp/patina.png --plugin patina
-cargo run --manifest-path tools/editor-check/Cargo.toml -- /tmp/patina-compact.png --plugin patina --compact
+mkdir -p target/editor
+cargo run --manifest-path tools/editor-check/Cargo.toml -- target/editor/<product>.png --plugin <product>
+cargo run --manifest-path tools/editor-check/Cargo.toml -- target/editor/rivet-creative.png --plugin rivet --creative
+cargo run --manifest-path tools/editor-check/Cargo.toml -- target/editor/patina-compact.png --plugin patina --compact
 ```

-Patina also accepts `--silent`, `--delta`, and `--bypass` as render fixtures.
-The tool compiles actual editor code and software-renders without a display.
-These checks do not establish native host embedding, keyboard routing, or audible
-artistic quality. Use the product guides for FL Studio acceptance checks.
+Patina also accepts `--silent`, `--delta` and `--bypass`. The tool compiles the
+real editor code, feeds it synthetic analysis data and renders it in software
+without a display. Copy a checked render to `docs/<product>/assets/editor.png`
+to update the guide. These renders do not prove native host embedding, keyboard
+routing or how the plugin sounds; use the FL Studio checks in each product guide.
+
+## Add a product
+
+1. Create `plugins/<product>/{core,ui,plugin}`. Copy the wrapper `Cargo.toml`
+   and `Cargo.lock` of a similar product so the NIH-plug revision matches.
+2. Add `core` and `ui` to the root `members`, the wrapper to `exclude`, and a
+   `[profile.dev.package.<product>-core] opt-level = 2` entry if the tests run
+   heavy DSP.
+3. Add the product to `plugins/catalog.json` with a new, unique CLAP ID.
+4. Add it to `.gitea/workflows/check.yml` (check matrix, editor preview,
+   Windows build) and to the tag list in `release.yml`. The script tests fail
+   until you do.
+5. Add a `--plugin <product>` fixture to `tools/editor-check`.
+6. Write `docs/<product>/README.md`, `CHANGELOG.md` and `assets/editor.png`, and
+   add the product to the root README.

 ## Compatibility and naming

-| Product | Former display name | Preserved CLAP ID |
+The suite is called **Bass Foundry**; this is the vendor name hosts show. Hosts
+identify plugins by CLAP ID, so the vendor name does not affect saved projects.
+
+| Product | Former display name | CLAP ID |
 | --- | --- | --- |
-| Rivet | Motif Storyboard | `io.storyboard.motif` |
-| Patina | Resonance Compressor | `io.storyboard.resonance-compressor` |
+| Rivet | Motif Storyboard | `io.narl.bass-foundry.rivet` |
+| Patina | Resonance Compressor | `io.narl.bass-foundry.patina` |
+| Anvil | (new) | `io.narl.bass-foundry.anvil` |
+| Crucible | (new) | `io.narl.bass-foundry.crucible` |
+| Lathe | (new) | `io.narl.bass-foundry.lathe` |
+| Temper | (new) | `io.narl.bass-foundry.temper` |
+| Weld | (new) | `io.narl.bass-foundry.weld` |
+| 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` |
+| Forge | (new) | `io.narl.bass-foundry.forge` |

-Rivet retains `story-session-v1` and its session migration support; Patina retains
-all parameter IDs. No JSON/state migration is introduced by the rename. These
-historical identifiers and copyright notices intentionally remain in source.
-Replace old scanned plugin files before rescanning, rather than keeping duplicate
-CLAP IDs installed. Verify existing-project recall in FL Studio.
+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
+plugins, so projects saved with those builds need the plugin added again. From now on an ID is frozen: if a product is renamed, its CLAP ID
+stays. A new plugin gets `io.narl.bass-foundry.<slug>` with its product slug.

-See [release workflow](releases.md) for tagged publishing. Actual Gitea runner
-execution and FL Studio validation remain separate from local checks.
+Rivet keeps `story-session-v1` and its session migration. Patina keeps all
+parameter IDs. The copyright notice keeps its original holder name. Delete old
+plugin files before rescanning, so FL Studio does not list both builds.
+
+See [releases](releases.md) for tagged publishing. Runs on the real Gitea runner
+and checks in FL Studio are separate from the local checks.
@@ -0,0 +1,13 @@
+# Forge changelog
+
+## 0.1.0
+
+- Introduce Forge, one tracked channel strip: Lathe, Temper and Knurl behind a
+  single note tracker, in any of the six orders, each module on or off.
+- Every module follows the note read from the strip's input, so a module after
+  Knurl no longer hears Knurl's sub-octave.
+- One latency of about 72 ms, the same in every order, instead of more than
+  200 ms for the three plugins in a row.
+- A single module on its own gives the same output, sample for sample, as its
+  standalone plugin.
+- Editor: the chain, and each module's standalone editor as its page.
@@ -0,0 +1,63 @@
+# Forge
+
+Forge is one tracked channel strip: Lathe, Temper and Knurl run behind a single
+note tracker, in the order you choose. Current version **0.1.0**.
+
+Each of the three plugins detects the played note itself. In a row, their
+lookaheads add up (Lathe 67 ms, Temper 68 ms, Knurl 71 ms: more than 200 ms),
+and a tracker after Knurl hears Knurl's sub-octave and follows a note an octave
+low. Forge reads the note once, from its input, and every module follows that
+one tracker. In a test with Knurl's sub-octave pattern in front of Lathe, a
+standalone Lathe after Knurl followed the note an octave low in every frame;
+Lathe inside Forge followed the played note in every frame.
+
+![Forge](assets/editor.png)
+
+## Install on Windows
+
+Copy `Forge.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 Forge in the mixer slot of the bass, right after the
+synth. Keep the font license with redistributed packages.
+
+## Work with it
+
+1. Choose **Pitch from** in the header: **AUDIO** detects the note from the
+   input; **MIDI** follows MIDI notes sent to the effect. All modules use it.
+2. The **Chain** row shows the modules in processing order. Click a module's
+   name to edit it below; **ON** switches it on or off. The button between two
+   modules swaps them. The default order is Lathe, Temper, Knurl, as in the
+   standalone chain.
+3. Each module's page is its standalone editor: [Lathe](../lathe/README.md),
+   [Temper](../temper/README.md) and [Knurl](../knurl/README.md) explain the
+   controls. Temper's **AUTO GAIN** sits in the Chain row while its page is
+   open.
+4. The **Gate** knob on every page is the one shared tracker gate: turning it on
+   one page turns it on all.
+
+**Bypass** in the header crossfades the whole strip to the delayed input.
+
+## How it works
+
+The tracker reads the strip's input, and the audio is delayed by its lookahead
+once. Every module gets the note events delayed by the latency of the modules
+in front of it, so each module sees a note start exactly on the attack of the
+audio it receives. A single module on its own in Forge gives the same output,
+sample for sample, as its standalone plugin, in every position of the chain.
+
+Temper's **Normalize** measures each note's level one lookahead ahead. In Forge
+it measures the strip's input, not the output of the modules in front of it.
+Lathe and Knurl change the level about equally on every note, so the notes
+still reach the shaper at one level.
+
+## Timing and limits
+
+Latency is the tracker's lookahead (about 67 ms), Temper's oversampling filters
+(under 1 ms) and Knurl's room for timing jitter (about 4 ms): about 72 ms in
+all, reported to the host. A module that is off still delays its audio by its
+own latency, so the latency stays the same in every order and with any module
+off.
+
+Changing the order while audio plays switches the routing at once and can
+click. The standalone plugins stay: use them when you need only one module, or
+when another plugin must sit between two of them.
@@ -0,0 +1,560 @@
+# Plugin ideas
+
+A running list of plugin ideas for riddim, dubstep and bass-music sound design.
+Each entry names the problem first. Entries are grouped as released or idea. Names follow the metalwork theme of the Bass Foundry suite.
+
+## Problems seen in bass-music production
+
+1. Every bass patch brings its own sub level and phase, so the weight of a drop
+   jumps between switch-ups, and layered patches cancel in the sub.
+2. Patches at the same peak level still differ in perceived loudness and
+   brightness. The usual fix is hand-set gain or clipping per patch.
+3. Resampling is repetitive: bounce, chop, trim, declick, normalise, find the
+   root key, name, save, load into a sampler.
+4. Writing wobbles: LFO shapes are drawn, synced, copied and edited for every
+   variation. Triplet and dotted patterns plus per-note changes take long.
+5. Unison, OTT and stereo distortion widen the mids. Parts disappear in mono or
+   on club systems.
+6. Kick and bass clash. Sidechain helps, but the sub phase at each note start
+   changes how the kick hits.
+7. Distortion chains build up harsh resonances. (Patina covers this.)
+8. Comparing a drop with a reference: the difference is usually sub/mid balance
+   over time, which generic meters do not show clearly.
+9. Fixed-frequency tools act differently on every note. An EQ boost at 300 Hz
+   lifts the 4th harmonic of one note and the 7th of another; a distortion with
+   a fixed tone filter sounds brighter on low notes than on high notes.
+10. Layered bass patches partly cancel in the mids, not only in the sub.
+11. Texture makes a riddim patch: grit, rattle, metal, vowel, noise. It takes long
+    chains (distortion, comb, formant, OTT, resample, repeat), and the result
+    changes from note to note.
+12. Grit and tone cannot be shaped separately. More distortion for more grit
+    also changes the body, the level and the low end.
+13. Resampled textures sound printed: a loop of one moment, with no movement
+    inside the note.
+14. Texture changes inside a note (the switch-up within one held note) need
+    automation lanes or chopping.
+15. There is no meter for texture. Two switch-ups can sound "the same" without
+    a clear reason, and generic analysers show only level and spectrum.
+16. OTT and multiband compression use fixed band edges, so the same setting
+    squashes different harmonics on every note.
+17. Riddim masters rely on clipping. A clipper that also clips the sub turns
+    the low end into distortion.
+18. Resampled basslines have no MIDI, so tools that need the notes have nothing
+    to follow.
+19. A clean sub carries the note on a club system but vanishes on phones and
+    laptops. Distortion makes the note readable there, but also changes the
+    patch.
+20. Detuned layers (reese) beat at a rate that changes with every note and every
+    harmonic, so the movement is never in time with the track.
+21. Kick and sub on the same MIDI tick are not heard at the same moment: the
+    heard hit depends on the attack shapes and on the offset between them.
+
+## Signal flow and suite audit (2026-11)
+
+How the released plugins fit into one production:
+
+```text
+WRITE      Rivet (motif → storyboard) ──MIDI──► synth
+DESIGN     synth → Lathe → Temper → Knurl → Patina
+RESAMPLE   Crucible (capture → slice → export) ──► sampler / wavetable synth ──► DESIGN
+LAYER      layer A + layer B → Weld (mids) → bass bus → Anvil (sub)
+MIX        gap: loudness, clipping, OTT, mono check, kick against sub, reference
+```
+
+Writing and sound design are covered. Mixing and mastering have only Anvil and
+Patina. Findings from the audit:
+
+- **Latency adds up.** A full chain (Knurl 71 + Temper 67 + Lathe 67 + Patina
+  about 45 + Anvil 80 ms) is about 330 ms. FL Studio compensates it for
+  playback, but a chain this long cannot be played live.
+- **MIDI mode keeps the lookahead.** `Tracker::latency()` depends on the pitch
+  range only. With MIDI as the source, the note is known at its attack, so the
+  lookahead could be close to zero. This needs a latency change at runtime,
+  which must be checked in FL Studio first.
+- **Knurl confuses every tracker after it.** Measured: Knurl output fed into
+  `TrackerConfig::BASS`. From C2 (65 Hz) upwards, Double, Fry (the default),
+  Gallop and Triple make the next tracker read the note one octave (Triple:
+  an octave and a fifth) too low for about 85 % of the note. Below C2 the false
+  sub-octave is under 30 Hz, out of range, so low notes are safe. Level and time
+  jitter also cause 5–25 false note starts per second. Anvil on the bus after
+  Knurl then plays the sub an octave low and restarts its phase. Until there is
+  a shared tracker: put Knurl after the other tracked plugins, and use MIDI as
+  the source for any tracked plugin after Knurl. See [Signal chain](chain.md).
+- **Each tracked plugin needs its own MIDI route.** Four plugins in MIDI mode
+  are four FL routing setups.
+- **Weld and delay compensation are untested together.** If the main layer's
+  chain has more latency than the sidechain layer and FL does not compensate
+  the sidechain route, the main layer arrives late, which an allpass cannot
+  fix. Put Weld after every plugin with latency on that track.
+- **Crucible lost takes on reload.** Takes are not saved with the project.
+  Fixed: Keep takes writes every capture's loop to disk at once.
+- **Settings handling differs.** Patina has presets and A/B; the others do not.
+  Lathe's drawn gains and Knurl's drawn pattern cannot be automated.
+
+## Research findings (2026-11)
+
+From the papers in `research/` (local, not committed). Each finding names where
+it goes in the suite. They are starting points to test by ear, not rules.
+
+- **A published bass fatness model.** Schmedeke's dissertation (Hamburg 2021,
+  "BASS DROP!", section 5.4.3) models momentary fatness of dance-music excerpts
+  over 50 ms windows from two inputs only, with adjusted R² 0.773:
+  `l = 10 / (1 + 4.5487·exp(0.13·(62.9366 − SPL<200)))`,
+  `h = 10 / (1 + 1.4317·exp(2.5575·(0.3299 − HR<200)))`,
+  `Fat = 0.14689·l·h` (0 to 14.7). SPL<200 is the C-weighted level below
+  200 Hz in dB(C) with the material normalised to −23 LUFS; HR<200 is the
+  MPEG-7 harmonic ratio (how periodic) of the same band. Chapter 4's earlier
+  linear model on synthetic tones (R² 0.597) points the same way: a tonal low
+  band is fatter, a noisy one is not. Anvil's clean sine maximises HR; Quench
+  keeps it when the top is clipped. The thesis does not state the dB(C) of its
+  reference, so the dBFS-to-dB(C) offset is an assumption. Measured with
+  `scripts/fatness.py` on the seven Devath references (offset 100 dB): drops
+  sit at 4–6, breakdowns near 0, kick gaps show as 50 ms dips; SPL<200 medians
+  are 67–69 dB(C), a few dB under the thesis's "mostly 70–80", so the offset
+  may be 2–5 dB low. Goes into Assay as one lane, never as an overall score.
+- **Virtual bass from known harmonics.** Moliner, Rämö and Välimäki (DAFx 2020)
+  boost the harmonics that exist with weights that follow the sound's spectral
+  envelope (limits 10 dB/oct below, 3 dB/oct above) and generate the missing
+  ones, so a small speaker suggests the fundamental. Their nonlinear stage fails
+  intermodulation tests, so they use it on transients only. The suite knows f0,
+  so it can add harmonics at exactly k·f0 with no intermodulation (problem 19).
+  Anvil's sub is a pure sine, so Lathe has no harmonics there to boost.
+- **Group-delay audibility.** Liski, Mäkivirta and Välimäki (2021): between
+  500 Hz and 4 kHz, listeners hear a group-delay peak from about 0.64 ms
+  (positive) or 0.56 ms (negative) on clicks over headphones; a fast-decaying
+  hi-hat hides it. Weld's allpass sections add positive group delay there.
+  Done: Weld shows the delay spread (released in 0.3.0). Measured: common fits from
+  Weld's own tests spread 0.82–1.03 ms, above the click threshold, so the
+  display gives a note, not a warning.
+- **Timbral tension.** Farbood and Price (2017): more roughness, inharmonicity
+  and spectral flatness raise judged tension; brightness (centroid) gives no
+  clear result. These are the measures planned for Loupe, and the controls a
+  tension macro would move.
+- **Coupled one-knob controls.** A 2026 distance renderer derives five distance
+  cues from one control, so they always agree; in its listening test it roughly
+  halved placement error and every participant preferred it. A pattern for
+  macros in Forge.
+- **Shared motion binds layers.** Temporal coherence (Elhilali et al. 2009) is
+  a grouping cue: sub, body and top sound like one sound when their main
+  movements line up. One modulation source inside Forge gives that by
+  construction; across separate `.clap` files it needs the shared memory
+  rejected below.
+- **Heard timing of layered hits.** Danielsen et al. (2026): attack shape and
+  the offset between two layers together set when the compound hit is heard
+  and whether it fuses. Hove et al. (2014): timing deviations are heard more
+  clearly in lower voices, so the bass sets the grid (problem 21).
+- **Loopback FM.** Smyth (DAFx 2026): an oscillator that frequency-modulates
+  itself shifts its own sounding pitch as feedback rises. Her closed-form
+  solution gives the sounding frequency, so a growl can stay on the tracked
+  note at any feedback.
+- **Beating depends on note and harmonic.** For two layers detuned by ratio r,
+  harmonic k beats at k·f0·(r − 1) Hz (Plomp and Levelt 1965 for the roughness
+  context). Fixed cents beat faster up the keyboard; fixed Hz beats the same on
+  every harmonic (problem 20).
+- **Do not encode as rules:** a best sub frequency, crossover or kick/bass
+  offset; one number for loudness, roughness, groove and preference; random
+  jitter sold as humanisation; more harmonics sold as more physical bass;
+  largest correlation sold as the best alignment.
+
+## Released
+
+### Anvil — sub anchor (problems 1, 6)
+
+Replaces the band below a split frequency with a clean mono sine that follows
+the bass pitch, at one level and one start phase for every note. Pitch comes
+from detection with 80 ms lookahead or from MIDI. See [Anvil](anvil/README.md).
+
+### Crucible — resampler (problem 3)
+
+Records the input continuously. One click captures the last bars on the host
+bar grid, slices on a grid or on hits, trims, declicks, normalises, detects the
+root key and exports labelled WAVs, a full loop and an optional Serum/Vital
+wavetable. See [Crucible](crucible/README.md).
+
+### Lathe — harmonic EQ (problem 9)
+
+EQ bands placed on harmonics 1–32 of the detected note instead of fixed
+frequencies. "+4 dB on harmonic 3, −6 dB on harmonic 7" sounds the same on F1
+and on C2. Odd/even balance, tilt over harmonic number, and a Focus control
+that lifts or cuts everything between the harmonics. Uses Anvil's pitch
+tracker, or MIDI. See [Lathe](lathe/README.md).
+
+### Temper — note-tracked distortion (problem 9)
+
+A waveshaper whose tone filters before and after the shaper follow the note, so
+every note distorts with the same character and the same harmonic content.
+Input level is normalised before the shaper, so drive does not depend on how
+loud the patch is, and the output is gain-matched. Oversampled to keep aliasing
+(which is never harmonic) out. See [Temper](temper/README.md).
+
+### Weld — layer phase alignment (problem 10)
+
+Takes a second bass layer through the sidechain. It fits polarity and a chain
+of up to four allpass sections to the measured cross-spectrum (no added
+delay), so the layers sum instead of cancel. A display shows how much level the
+cancellation cost and how much Weld recovered. Anvil solves the sub band; Weld
+solves the mids. See [Weld](weld/README.md).
+
+### Knurl — cycle texture (problems 11, 13)
+
+Follows the played note and treats every cycle on its own: a repeating level
+pattern (in-tune subharmonics), random level and timing per cycle, and a noise
+burst per cycle tuned to the note. Amounts are counted in cycles, so the texture
+is the same on every note. Slow per-harmonic drift is postponed. See
+[Knurl](knurl/README.md).
+
+### Planish — harmonic OTT (problem 16)
+
+Upward and downward compression in four bands whose edges are harmonic numbers
+of the tracked note (default 1, 2–4, 5–16, 17 and up), so the same setting
+squashes the same harmonics on every note. Each band's level is measured over
+one period of the note, so heavy settings do not ripple at f0. See [Planish](planish/README.md).
+
+## Next for released plugins
+
+- **Anvil**: *Kick lock* and the *offset audition* are done (Anvil 0.3.0, see
+  [Anvil](anvil/README.md)): the kick through the sidechain ducks the sub and
+  restarts its phase at an offset (problem 6); the audition steps −30 to +30 ms,
+  4 kicks each, Keep takes the offset heard, and the low-band sum per offset is
+  shown apart from that choice (problem 21). Measured on a 55 Hz kick burst
+  against a 55 Hz sub: +2.4 dB at 0 ms, −4.6 dB at −10 ms, −5.9 dB at +10 ms,
+  and +1.8 to +2.2 dB again one period away (±20 ms), so the sum alone cannot
+  pick the hit. Open: a finer second sweep around the kept offset; a gate or
+  sensitivity for kicks with long tails or a kick bus with other drums.
+  A sub shape from sine to rounded
+  triangle. A note attack counted in cycles. *Ghost harmonics* and the
+  *Phone* listen are done (Anvil 0.3.0, see [Anvil](anvil/README.md)): harmonics
+  2–10 above a "from" frequency, filled only where the patch lacks them, with
+  the sub level unchanged (problem 19). Open for Ghost: weights that follow the
+  patch's own harmonic slope instead of a fixed 1/k; measuring a new note's
+  harmonics from the lookahead, so its first 60 ms do not count them as
+  missing; a listening check on an 808 over a real phone.
+- **Lathe**: A/B gain snapshots with one automatable Morph parameter. A
+  keyswitch note that selects the drawn shape (EQ switch-ups without
+  automation). A dynamic mode per harmonic.
+- **Temper**: a harmonic split: harmonics 1–2 clean, 3 and up driven. More than
+  one Push band. A bias that changes per cycle from Knurl's cycle clock.
+- **Knurl**: velocity or note selects the pattern. Stereo grit above a split
+  only. Drift (planned for 0.3).
+- **Patina**: Tone guard (done, Patina 0.4.0). MIDI as its pitch source. M/S
+  processing. Threshold, Ratio and Soft/Hard knee from tester feedback (done,
+  Patina 0.5.0). Next, from the same feedback round:
+  - An absolute level gate (dBFS) so quiet passages are never cut, if the
+    tester meant a loudness threshold rather than a prominence threshold.
+  - Narrow rings on dense or noisy material are under-read: a +12 dB ring
+    (Q 25) on noise reads only 3–6 dB above the floor, so it is cut by 1–3 dB.
+    Two causes, measured: the joined-tops envelope lifts the floor to the noise
+    peaks (about 5 dB above the noise mean), and envelope smoothing loses about
+    3 dB on a narrow ring. A floor that follows Sharpness (1/3–2 octaves) was
+    tried and rejected: it lost a resonant lowpass, absorbed broad bumps and cut
+    plain harmonic tones. Better candidates: join tops only across deep gaps
+    (harmonic spacing), or a mean-based floor for noise-like regions.
+  - A finer analysis grid (1024 cells) for narrow rings at high frequencies.
+- **Weld**: delay spread display (done, Weld 0.3.0). A *gentle* fit option
+  that keeps the delay spread under a limit, for plucky layers. Alignment slots
+  per note or per switch-up. The External
+  sender/receiver fallback if FL's sidechain does not arrive.
+- **Crucible**: a heard-onset marker per slice next to the technical cut, set
+  by ear and written to the WAV (problem 21). A switch-up slicer that cuts where the spectrum changes, for
+  legato basses. Optional retune of slices to one root. Reopening saved takes
+  from the `takes` folder in the take list.
+- **Rivet**: more than two sound roles, one per switch-up patch. Its MIDI
+  output as the one note source for the tracked plugins.
+- **Suite**: presets and A/B in `common-ui` for every plugin.
+
+## Ideas
+
+### Order
+
+1. Small fixes from the audit. Done: chain-order guide
+   ([Signal chain](chain.md)), Crucible Keep takes. Open: Weld test with delay
+   compensation (in FL), MIDI mode without lookahead (needs an FL check that a
+   latency change at runtime is accepted).
+2. Patina pitch-aware mode. Done as **Tone guard** (Patina 0.4.0): bumps that
+   follow the note are protected, bumps fixed in Hz are cut. Measured first:
+   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 (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
+     (done, Anvil 0.3.0); Braze (done, 0.1.0); Anvil Kick lock with offset
+     audition (done, Anvil 0.3.0).
+4. Forge (done, released 0.1.0): Lathe, Temper and Knurl behind one tracker.
+5. Assay, one plugin for the display-only ideas.
+6. Texture plugins (Anneal, Swarf, Etch, Bellows) and the note-keyed sequencer.
+
+Merges: Gauge, Loupe and Drop compare share one analysis core and one display,
+so they become one plugin, **Assay**. The wobble sequencer, Damascus and Chase
+are all "step grid, note selects the pattern", so they become one sequencer.
+
+### Forge — one tracked channel strip (problems 9, 11, latency)
+
+One tracker, one latency, and Lathe, Temper, Knurl and later Anneal as modules
+in an order you choose. Two further reasons from the research findings: one
+modulation source for all modules moves sub, body and top together, which
+binds them into one sound; and coupled macros become possible, for example a
+*Tension* knob that raises roughness (Knurl), inharmonicity and noise (Anneal)
+together at matched loudness, measured by the same descriptors as Loupe. It removes the stacked lookahead, the trackers that
+disagree (Knurl's sub-octave cannot confuse a tracker that reads the input
+before Knurl) and the repeated MIDI routing. The standalone plugins stay.
+Sharing one tracker between separate `.clap` files would need named shared
+memory across DLLs, which is fragile; one strip is simpler.
+
+Built (released 0.1.0, see [Forge](forge/README.md)). Lathe, Temper and Knurl
+became modules (a `Tracked` trait in common-dsp: `ahead`, `event`, `process`);
+each standalone plugin is now its tracker plus its module, Lathe and Temper
+bit-exact against the old engines, Knurl one sample later (its interpolation
+needs one newer sample) and equal within float rounding. In the strip one
+tracker reads the input; a per-sample record of the tracker's events, note state
+and input is replayed to each module, delayed by the latency of the modules in
+front of it. Findings:
+
+- One module alone in Forge matches its standalone plugin sample for sample, in
+  all six orders (tested).
+- Knurl's Double-style pattern (0, −12 dB) in front of Lathe: standalone Lathe
+  after Knurl read the note an octave low in 149 of 149 frames on an A2 saw;
+  Lathe inside Forge read A2 in 149 of 149.
+- Latency 72 ms against 206 ms for the three in a row (48 kHz).
+- Temper's Normalize looks one lookahead ahead; in the strip it reads the strip
+  input, not the modules in front of it. Fine while those change every note's
+  level alike.
+
+Next for Forge: the *Tension* macro over Knurl (and later Anneal) at matched
+loudness; Planish and Braze as modules (both are tracked, and Braze after
+Knurl is the next tracker that hears the sub-octave); a short crossfade when
+the order changes; one shared modulation source (per-note envelope or LFO in
+cycles) that every module can read.
+
+### Braze — tempo-locked beating (problem 20)
+
+Brazing joins two metals with a filler. Braze adds a detuned copy of the bass
+whose beating is in time with the track on every note. With the tracked f0, it
+sets the detune ratio for each note so that a chosen harmonic beats at a
+tempo-synced rate: r = 1 + B/(k·f0), for example an eighth at 140 BPM is
+B = 4.67 Hz. A second mode adds a frequency-shifted copy, so every harmonic
+beats at the same rate. Controls: rate (synced), target harmonic, depth,
+spread across harmonics, mode. It reuses the tracker, and Weld should not
+"fix" this beating: put Weld before Braze.
+
+Built (released 0.1.0, see [Braze](braze/README.md)). The detune is a delay
+line whose delay falls one period per beat cycle and jumps back one period,
+which is seamless on a periodic note, and the delay follows the host's beat
+position, so the peaks land on the grid. Harmonic n then beats at n/k · B: every
+harmonic is on the grid, so the planned spread control was not needed. A Low
+cut (LR4 on the copy, the bass split by the same crossover) keeps the sub out.
+Open: the frequency-shift mode. Mixed with the dry bass, a plain single-sideband
+shift gives every harmonic the same envelope at the same moment, which is
+tremolo; it needs a dispersive allpass on the copy to stagger the harmonics
+before it sounds like movement. Also open: a listening check on a real reese,
+and how Weld reads a layer after Braze.
+
+### Arc — self-FM growl (research spike)
+
+An arc welds with a sustained spark. Arc runs loopback FM (Smyth, DAFx 2026)
+on the tracked note: a time-varying delay line modulated by its own output.
+The closed-form sounding frequency lets Arc retune the carrier, so the growl
+stays in key while feedback sweeps from clean to torn. Needs listening and an
+aliasing check before it becomes a plugin.
+
+### Quench — sub-safe clipper (problem 17)
+
+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
+outputs MIDI notes and a `.mid` file. A resample from Crucible then gets its
+notes back, so the other plugins can use MIDI as their source.
+
+### Bevel — mono-safe harmonic widener (problem 5)
+
+Pans harmonics of the note alternately (for example odd left, even right) with
+complementary filters, so the mono sum stays flat. Pairs with Assay.
+
+### Peen — note-start transient shaper
+
+Peening hardens a surface with hammer blows. Attack and sustain shaping on
+every note start, with times counted in cycles, so each switch-up gets the same
+punch on every note. Could become part of Ballast.
+
+### Ballast — switch-up loudness leveller (problem 2)
+
+Measures short-term perceived loudness per note or per switch-up against a
+target or a reference patch and adjusts gain only, so each switch-up lands at
+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,
+distortion or drums into pitched metallic tone that is in key on every note.
+Damping, harmonic spread, single or multiple combs.
+
+### Gauge — low-end mono check (problem 5)
+
+Shows phase correlation and mono-sum loss per band and per note in the bass
+range, and marks the notes where widening breaks the mono sum. Optional fixes:
+mono below a chosen frequency and phase rotation on the mids. Display-first, so
+it is a small build. Earlier working name: Bass Mono Check.
+
+### Wobble sequencer (problem 4)
+
+Step patterns for volume, filter, formant and pitch with triplet and dotted
+grids built in. Each MIDI note selects a different pattern, so a switch-up is a
+different note in the piano roll. ShaperBox overlaps, but it has no note-keyed
+patterns. No name yet.
+
+### Fatness lane (problems 2, 8)
+
+Momentary fatness per 50 ms from Schmedeke's model (see Research findings),
+drawn as one lane next to sub/mid energy, for a patch and a reference. It
+explains why two drops at the same LUFS feel different in weight: a quieter or
+noisier low band lowers the value. Prototype: `scripts/fatness.py` (offline,
+on rendered files). The first piece of Assay. Open: the dB(C) offset, and how
+the lane reads on a single bass patch rather than a full mix.
+
+### Drop compare (problem 8)
+
+Loudness-matched A/B of a drop against a reference, with sub, low-mid, mid and
+high energy over time: for example "your sub is 3 dB under the reference in
+bars 2–4". No name yet.
+
+## Texture ideas
+
+These ideas target problems 11–15; Knurl, the first of them, is released above.
+Most of them reuse the note tracker in
+`common-dsp`, so a texture setting means the same thing on every note, the same
+way Lathe and Temper work.
+
+### Anneal — tone and grit split (problem 12)
+
+Annealing changes how a metal behaves without changing its shape. Anneal
+splits the signal into three parts: the harmonic part (energy on the harmonics
+of the tracked note), the residual noise and grit between the harmonics, and
+the transients. Each part has a level fader, a drive and a tilt.
+
+- Turn the grit up 6 dB and keep the body and the sub unchanged.
+- Take all the grit out of a layer and leave a clean tone for further design.
+- Listen to each part solo, or send the grit to a second output for its own
+  chain.
+
+DSP: an STFT with the note tracker; harmonic masks at k·f0, with a width that
+follows the pitch; a transient mask from spectral flux. Latency is one FFT
+frame. The display shows the three parts in different colours on Lathe's
+harmonic strip.
+
+### Swarf — in-key granular shavings (problems 11, 13)
+
+Swarf is the shavings that machining leaves. Swarf records the bass itself and
+sprays short grains of it back as a layer. Grain lengths are whole pitch
+periods, and every grain is retuned to the note playing now, so the shredded
+layer stays in key across a riddim line. Controls are density, spray (position
+spread back in time), grain size in cycles, reverse probability, and a
+harmonic-only filter for the layer. It is useful for the "shredded metal" top
+layer, and works on a resample from Crucible as well.
+
+### Etch — texture imprint (problem 11)
+
+Etching transfers a pattern onto metal with acid. Etch takes a texture source
+through the sidechain or from a loaded sample (a metal scrape, a vocal, a field
+recording) and imprints its fine structure on the bass. The bass keeps its
+pitch and its harmonic levels; between and on the harmonics, the source's
+noise, roughness and movement come through. A "harmonic lock" mode samples the
+source's spectral envelope only at the bass harmonics, so the imprint is always
+in key. It differs from a vocoder: a vocoder transfers the envelope, and Etch
+transfers the surface.
+
+### Chase — talking formants that hit harmonics (problems 11, 14)
+
+Chasing shapes metal by hammering it from the front. Chase is a formant filter
+with a 2D vowel pad (a, e, i, o, u, plus "yoi" and "wub" shapes). You draw a
+path over the pad and sync it to the tempo, or let each MIDI note select a path.
+The formants stay in Hz, so a vowel stays a vowel on every note. A **snap**
+control moves each resonant peak onto the nearest harmonic of the tracked
+note, so a narrow formant never falls into the gap between two harmonics and
+vanishes on some notes. Gain-matched, so a vowel change does not change the
+level.
+
+### Damascus — texture step sequencer (problem 14)
+
+Damascus steel is folded from layers into a visible pattern. Damascus holds up
+to four texture slots (for example a formant, a comb, a sample-rate reducer and
+a Knurl-type rattle) and a tempo-synced step grid that chooses a slot, or a mix
+of two, per step. Steps have their own crossfade time, so changes can be hard
+cuts or smears. Each slot is gain-matched, so the steps change texture and not
+level. Each MIDI note can select its own pattern, which is a texture switch-up
+inside one held note. This overlaps with the wobble sequencer above; both could
+become one plugin.
+
+### Loupe — texture meter (problem 15)
+
+A loupe is the lens used to inspect engraving. Loupe measures texture per note
+over time:
+
+- roughness and fluctuation strength (psychoacoustic models);
+- harmonic-to-noise ratio, which shows how gritty a sound is;
+- inharmonicity, which shows how metallic a sound is;
+- brightness relative to the note (harmonic centroid, not centroid in Hz).
+
+Roughness, inharmonicity and flatness are also the three timbre measures that
+raise judged tension (Farbood and Price 2017), so the same lanes show a build-up
+getting tenser without a note change.
+
+It places every switch-up of a drop as a point on a texture map. Two patches
+that sit on the same point are why a drop sounds repetitive. A reference track
+can be loaded for comparison. Display only, so it is a small build, and it fits
+with Gauge and Drop compare.
+
+### Further leads
+
+- **Creative extrema stretch** for Crucible: Nielsen (DAFx 2026) drives an
+  overlap-add stretch by the spacing of local extrema, a free measure of
+  detail. Cheap and gritty, not transparent; a bass has few extrema per cycle,
+  so the stretch stays close to cycle-synchronous.
+- **Reference to preset:** an offline search over a bounded set of Lathe and
+  Temper parameters that matches a reference switch-up (ST-ITO, TAPE). Large;
+  needs learned audio features.
@@ -0,0 +1,25 @@
+# Knurl changelog
+
+## Unreleased
+
+- The engine is now a module that also runs inside Forge. The sound is
+  unchanged; the latency is one sample longer.
+
+## 0.2.0
+
+- Change the CLAP ID to `io.narl.bass-foundry.knurl`. Hosts see this as a new
+  plugin: delete the old `.clap` file, rescan, and add the plugin again in
+  existing projects.
+
+## 0.1.0
+
+- Introduce Knurl, texture per cycle of the played note.
+- Step patterns over 1–16 cycles make subharmonics in tune with every note:
+  Off, Double, Triple, Fry, Gallop, Stutter, or a drawn pattern.
+- Random level and timing per cycle, and a noise burst per cycle tuned to the
+  note (Tone, Position, Length), switchable per step.
+- Same every note or Free random sequences.
+- Detect pitch and note starts from the audio with about 71 ms of latency, or
+  follow MIDI notes sent to the effect.
+- Editor shows the last eight cycles overlaid and the pattern with the playing
+  step.
@@ -0,0 +1,91 @@
+# Knurl
+
+Knurl gives every cycle of the note its own level, timing and grit. Current
+version **0.2.0**.
+
+Knurling presses a ridged pattern into metal. Riddim and dubstep basses get their
+character the same way, from surface texture: rattle, growl, fry, grit. Usually
+that texture comes from long chains of distortion, comb filters, formants and
+resampling, and it changes from note to note. Knurl works on single cycles of the
+wave instead. It follows the played note and treats each cycle on its own, and
+every amount is counted in cycles, not in Hz or tempo. So the texture has the
+same grain on F1 and on C2.
+
+![Knurl](assets/editor.png)
+
+## Install on Windows
+
+Copy `Knurl.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 Knurl in a mixer slot of the bass. Keep the font license with
+redistributed packages.
+
+## Work with it
+
+1. Play the bass. The note readout shows what Knurl tracks; the scope overlays
+   the last eight cycles of the output, so the texture is visible cycle by cycle.
+2. Choose a **Pattern**. The pattern sets the level of each cycle and repeats:
+   - **Double** (0, −9 dB): every second cycle quieter. This makes a sub-octave
+     growl, exactly in tune, about 8 dB under the fundamental.
+   - **Triple** (0, −12, −12 dB): a growl an octave and a fifth down.
+   - **Fry** (0, −14, −5, −14 dB, the default): an uneven vocal-fry rattle.
+   - **Gallop** and **Stutter**: rhythmic patterns over six and eight cycles.
+   - **Off**: every cycle at full level.
+3. Draw your own pattern on the bars: drag a bar to set the level of that cycle,
+   double-click to reset it. **Steps** sets the length (1–16 cycles).
+4. Add surface:
+   - **Level** gives every cycle a random level (standard deviation in dB).
+   - **Time** moves every cycle a little in time (percent of a period): rattle
+     and scrape.
+   - **Grit** adds a short noise burst inside every cycle. **Tone** sets its
+     lowest frequency in harmonics of the note, **Position** where in the cycle
+     it sits, and **Length** how long it is. The squares under the pattern bars
+     switch the burst per step.
+5. **Edge** sets how soft each step change is. Low values are sharper and
+   buzzier; high values smoother.
+
+**Random**: **Same every note** (default) restarts every random sequence at each
+note, so identical notes sound identical, which keeps a riddim line tight.
+**Free** lets the sequences run on, so every note differs.
+
+**Mix** blends with the delayed dry signal; **Output** trims the level.
+
+### Pitch from MIDI
+
+For basses whose fundamental is unclear (heavy FM, formant or noise patches),
+select **MIDI** and route the bass's MIDI notes to Knurl. In FL Studio, set the
+bass channel's MIDI output port and Knurl's input port to the same number.
+**Gate** sets the input level that counts as a note in AUDIO mode; **Snap to
+semitone** rounds the detected pitch (turn it off for slides).
+
+## Timing and limits
+
+Knurl delays the audio by about 71 ms: 67 ms of pitch-detection lookahead plus
+4 ms of room for the timing jitter. The delay is reported to the host for delay
+compensation, so the cycle clock knows every note before its attack leaves the
+plugin. The cycle clock restarts at every note start, so the pattern always
+begins with step 1 on the attack. Pitch range is 30–500 Hz, one note at a time.
+Between notes the effects fade out over 20 ms, so tails stay clean.
+
+Knurl works per cycle of the tracked pitch; it does not look for cycle borders in
+the waveform. With a stable pitch that is the same thing. With heavy pitch
+modulation inside a note the pattern follows the tracked pitch, which can lag a
+fast bend. Both channels get the same treatment, so the effect is mono-safe.
+
+Knurl's patterns put a real sub-octave into the signal. A pitch detector after
+Knurl (Anvil, Lathe or Temper in Audio mode) then reads notes from C2 upwards
+an octave too low. Put Knurl after the other tracked plugins, or use MIDI as
+their source. See [Signal chain](../chain.md).
+
+## How it works
+
+A note tracker (shared with Anvil, Lathe and Temper) detects pitch and note
+starts ahead of the delayed audio. A cycle clock starts at 0 on every note and
+advances by f0 / sample rate. Each cycle gets its step gain and its random level
+and time offset from a hash of the cycle number, so the result is deterministic.
+Step changes are raised-cosine crossfades over the last **Edge** of a cycle;
+level jitter crossfades over half a cycle and time jitter over the whole cycle,
+read from the delay line with cubic interpolation. The grit is white noise
+through a state-variable highpass at **Tone** × f0, shaped by a sin² window and
+scaled to the input level. There is no nonlinearity, so no oversampling is
+needed.
@@ -0,0 +1,19 @@
+# Lathe changelog
+
+## 0.2.0
+
+- Change the CLAP ID to `io.narl.bass-foundry.lathe`. Hosts see this as a new
+  plugin: delete the old `.clap` file, rescan, and add the plugin again in
+  existing projects.
+
+## 0.1.0
+
+- Introduce Lathe, a harmonic EQ for bass sound design.
+- Bands sit on harmonics 1–32 of the played note instead of fixed frequencies,
+  so a cut on harmonic 3 stays on harmonic 3 on every note.
+- Draw a gain per harmonic; Tilt, Odd/Even and Between shape the whole series.
+- Detect pitch and note starts from the audio with 67 ms lookahead, or follow
+  MIDI notes sent to the effect. Filters retune at each note's attack.
+- Controls: Tilt, Odd/Even, Between, Width, Harmonics, Smooth, Gate, Mix,
+  Output, Snap to semitone, Bypass. Shapes: Flat, Odd only, Even only, Hollow.
+- Harmonic editor shows the measured level of each harmonic before and after.
@@ -0,0 +1,66 @@
+# Lathe
+
+Lathe is an EQ whose bands sit on the harmonics of the note being played.
+Current version **0.2.0**.
+
+A normal EQ works in fixed frequencies. A cut at 130 Hz takes out the 3rd
+harmonic of an F1 bass, the 2nd of a C2, and the fundamental of a C3, so the
+same bass sounds different on every note of a riddim line. Lathe follows the
+pitch and places one band on each harmonic: "−12 dB on harmonic 3" stays on
+harmonic 3 whatever note plays.
+
+![Lathe](assets/editor.png)
+
+## Install on Windows
+
+Copy `Lathe.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 Lathe in a mixer slot of the bass, after the synth and before bus
+processing. Keep the font license with redistributed packages.
+
+## Work with it
+
+1. Play the bass. The note readout shows what Lathe tracks; the lower strip of the
+   editor shows each harmonic's level going in (grey) and coming out (pink).
+2. Draw gains on the harmonic bars. Drag across bars to paint a shape;
+   Shift-drag for fine steps; double-click a bar to reset it.
+3. Use the macros for the whole series:
+   - **Tilt** brightens or darkens in dB per octave of harmonic number. The
+     fundamental is the pivot.
+   - **Odd/Even** lifts odd harmonics and lowers even ones (positive, more
+     square-like) or the reverse (negative, more octave-like).
+   - **Between** sets the gain halfway between harmonics. Cut it to clean up noise,
+     beating and inharmonic grit; lift it for dirt.
+4. **Width** sets every band's bandwidth as a share of the harmonic spacing. Narrow
+   bands touch only the harmonic; wide bands also move its surroundings.
+
+Other controls:
+
+- **Harmonics** is how many harmonics are shaped (8–32). Higher harmonics pass
+  unchanged.
+- **Smooth** is the retune time for slides and pitch bends. A new note always
+  retunes at once, on its attack.
+- **Gate** is the input level that counts as a note. Raise it if tails or reverb
+  start new notes.
+- **Mix** blends with the delayed dry signal; **Output** trims the level.
+- **Snap to semitone** rounds the detected pitch. Turn it off for slides.
+- **Shapes** set the drawn gains: Flat, Odd only, Even only, or Hollow (harmonics
+  2–4 cut).
+
+The drawn gains are saved with the project but are not automation parameters;
+the macros are.
+
+### Pitch from MIDI
+
+For basses whose fundamental is unclear (heavy FM, formant or noise patches),
+select **MIDI** and route the bass's MIDI notes to Lathe. In FL Studio, set the
+bass channel's MIDI output port and Lathe's input port to the same number.
+
+## Timing and limits
+
+Detection uses about 67 ms of lookahead, reported to the host for delay
+compensation, so the bands are tuned before each note's attack leaves the
+plugin. Pitch range is 30–500 Hz, one note at a time; chords are not separated.
+Before the first note Lathe passes audio unchanged; between notes it holds the
+last tuning so tails keep their shape. Bands above 0.45 × the sample rate are
+skipped.
@@ -1,5 +1,38 @@
 # Patina changelog

+## 0.5.0
+
+- Each band now works like a small compressor. Add **Ratio** (1:1 to ∞:1,
+  default ∞:1): low ratios leave small bumps nearly alone and still cut big ones
+  hard. ∞:1 is the old behaviour.
+- Replace Selectivity (%) with **Threshold** (0–18 dB above the local floor,
+  default 3 dB, which equals the old default of 50 %).
+- Add a **Soft/Hard knee** switch. Soft widens the knee from 3 dB to 6 dB;
+  Hard uses a 1 dB knee and half the Attack time.
+- Show the gain curve (bump height in, cut out) under the knobs.
+- Mix and Output move to the slider panel under the plot.
+- Retune the Vocal harshness, Snare ring, Bright synth and Bass line presets
+  with Ratio and more Depth.
+- Breaking: FL Studio projects saved earlier load Threshold, Ratio and Knee at
+  their defaults. Settings files for `patina-render` with `selectivity` still
+  load and convert.
+
+## 0.4.0
+
+- Add **Tone guard** (0–100 %, default 0 %). Patina follows the played note and
+  remembers, over about four seconds, which bumps stay in Hz and which follow the
+  note. Bumps that follow the note (a harmonic the bass is built on) are cut
+  less; resonances fixed in Hz (formant, comb and filter rings) are still cut.
+  At 0 % Patina works exactly as before. The display shows the note and marks
+  the held-back region with a blue strip.
+- Add the **Bass line** preset (Tone guard 80 %, Low 150 Hz).
+
+## 0.3.0
+
+- Change the CLAP ID to `io.narl.bass-foundry.patina`. Hosts see this as a new
+  plugin: delete the old `.clap` file, rescan, and add the plugin again in
+  existing projects.
+
 ## 0.2.0

 - Rebuild the detector so it finds resonant bumps instead of cutting individual
@@ -1,7 +1,7 @@
 # Patina

 Patina smooths a sound’s rough surface without erasing its character. Formerly
-**Resonance Compressor**; current version **0.2.0**.
+**Resonance Compressor**; current version **0.5.0**.

 A mixing effect that finds harsh, ringing regions as they happen and pulls them
 down, while plain harmonic tone passes. Independently designed in Rust; no claim
@@ -20,18 +20,51 @@ redistributed packages.

 ## Work with it

-Three controls decide what happens:
+Each band works like a small compressor. It compares its level with the local floor
+around it and cuts only the part that sticks out:

- **Depth** is the largest cut, in dB. 0 dB does nothing.
+- **Depth** is the largest cut per band, in dB. 0 dB does nothing.
 - **Sharpness** sets what counts as a resonance. Low values follow broad,
  smooth bumps (honk, boxiness). High values target narrow rings and whistles.
- **Selectivity** sets how far a bump must stand out before it is cut. Low
-  values treat any bump; high values treat only the worst.
+- **Threshold** is how far (dB) a band must rise above its neighbours before it
+  is cut. Low values treat any bump; high values treat only the worst.
+- **Ratio** is how hard a bump above the threshold is cut. At n:1 a bump ends
+  1/n as far above the threshold as it started. Low ratios leave small bumps
+  nearly alone and still cut big ones; ∞:1 flattens every bump to the
+  threshold (this is how Patina worked before 0.5).
+- **Knee**: Soft fades cuts in around the threshold. Hard starts them right at
+  the threshold and uses half the Attack time.

-Start with Depth around 6 dB. Raise Selectivity until only the harsh parts show
-cuts, then use Delta to hear what is removed. Restrict Low/High frequency to keep
-the source’s body out of reach. Attack and Release set how quickly cuts grow and
-recover; Transient guard briefly relaxes cuts on attacks to keep punch.
+The small graph under the knobs shows the result: bump height above the floor
+in, cut out, with the threshold and the Depth limit.
+
+Start with Depth around 6 dB. Raise Threshold until only the harsh parts show
+cuts, then use Delta to hear what is removed. To hit big resonances hard and
+leave small ones alone, raise Depth to 12–20 dB and set Ratio to 2:1–4:1.
+Restrict Low/High frequency to keep the source’s body out of reach. Attack and
+Release set how quickly cuts grow and recover; Transient guard briefly relaxes
+cuts on attacks to keep punch.
+
+### Tone guard for bass lines
+
+On a bass line, a bump can mean two things. A resonance fixed in Hz (a formant,
+a comb or filter ring) stays at the same frequency on every note: that is what
+Patina should cut. A bump that follows the note (a harmonic the patch is built
+on, or a Lathe boost) moves with every note: cutting it changes the patch
+differently on each note.
+
+**Tone guard** tells them apart. Patina detects the played note (30–500 Hz)
+and remembers, over about four seconds, how high each bump was in Hz and how
+high it was relative to the note. A bump that has stayed with the note more
+than in Hz gets less cut; at 100 % none. A resonance fixed in Hz is cut as
+before. It needs a few different notes before it can decide: on one held note
+both look the same and Patina cuts as normal. The **NOTE** readout shows what
+Patina follows, and a blue strip on top of the plot shows where cuts are held
+back. Start from the **Bass line** preset. At 0 % Tone guard is off.
+
+Measured on a saw line F1–F2 with Low at 150 Hz: a +12 dB boost on harmonic 6
+is cut by 5.8 dB without Tone guard and by 0.4 dB at 100 %; a formant at 1.5 kHz
+is cut by 5.8 dB either way.

 Double-click the plot to add one of four focus points. Drag a point up to cut
 more in that region, down to protect it. Wheel changes its width. Range handles
@@ -40,7 +73,7 @@ on the plot drag the processing limits.
 On the plot, the grey fill is the measured input. The bright line is what the
 detector hears (its smoothed spectral envelope); the dim line is what it expects
 there. Accent-coloured cuts appear where the bright line rises above the dim one
-by more than Selectivity allows. The blue curve is the focus/protect shape.
+by more than Threshold allows. The blue curve is the focus/protect shape.

 Delta plays delayed dry minus wet before output trim. Use it to inspect changes,
 then return to normal monitoring to decide whether the music improved.
@@ -62,8 +95,9 @@ window size persist; Delta does not.
 4. The reference is a robust local straight-line fit over 2–3 octaves: spectral
   tilt is expected, bumps cannot raise their own reference, and empty regions
   (below a fundamental, beyond a filter cutoff) are ignored.
-5. Envelope minus reference, above the Selectivity threshold, becomes the cut,
-   limited by Depth, smoothed with Attack/Release, and linked across stereo.
+5. Envelope minus reference is the band's height above its floor. Above
+   Threshold it becomes a cut through the Knee and Ratio curve, limited by
+   Depth, smoothed with Attack/Release, and linked across stereo.

 ## Timing and limits

@@ -76,7 +110,8 @@ The engine uses complex RustFFT with supplied scratch buffers, WOLA reconstructi
 the envelope/reference detector above, bounded soft-knee cuts, and temporal
 smoothing. Original bin phases are retained. This is not a minimum-phase filter
 bank, a live monitoring effect, a limiter, or an automatic separation of tone and
-unwanted resonance. No external sidechain, Learn, M/S, or pitch detector in v0.1.
+unwanted resonance. No external sidechain, Learn or M/S. The pitch detector
+serves Tone guard only.

 ## Build and offline evaluation

@@ -116,12 +151,14 @@ not a worst-case multi-instance guarantee.

 ## Existing projects and source layout

-The CLAP ID `io.storyboard.resonance-compressor` is unchanged. Version 0.2
-replaces Amount, Sensitivity, Max cut, Neighborhood, Cut width, and Knee with
-Depth, Sharpness, and Selectivity, so projects saved with 0.1 load those
-controls at their defaults. Replace the former plugin file with `Patina.clap` and
-rescan; avoid two scanned copies with the same ID. Host project recall still
-needs verification in FL Studio.
+The CLAP ID is now `io.narl.bass-foundry.patina` (earlier builds used
+`io.storyboard.resonance-compressor`). Hosts treat Patina as a new plugin, so
+add it again in projects saved with an earlier build. Version 0.2 replaced
+Amount, Sensitivity, Max cut, Neighborhood, Cut width, and Knee with Depth,
+Sharpness, and Selectivity; version 0.5 replaced Selectivity with Threshold
+(dB), Ratio and Knee, so projects saved earlier load Threshold at its default.
+Delete the old plugin file, place `Patina.clap`, and
+rescan FL Studio.

 Source is grouped into `plugins/patina/{core,ui,render,plugin}`. See
 [research](research.md), [development](../development.md), and the
@@ -0,0 +1,14 @@
+# Planish changelog
+
+## 0.1.0
+
+- Introduce Planish, upward and downward compression in four bands whose edges
+  are harmonic numbers of the played note.
+- Band edges set by harmonic (Low 1–8, Mid 2–16, High 3–48), with splits
+  Classic, Sub + body, Tight and Wide top, or dragged on the harmonic ruler.
+- Depth, Drive, Upward, Downward, Time and a gain per band.
+- Band level measured over one period of the note, so heavy compression does
+  not ripple at the fundamental.
+- Detect pitch and note starts from the audio with about 67 ms of latency, or
+  follow MIDI notes sent to the effect.
+- Editor shows the bands on a harmonic ruler and each band's level and gain.
@@ -0,0 +1,97 @@
+# Planish
+
+Planish is upward and downward compression (OTT) in four bands whose edges are
+harmonic numbers of the played note. Current version **0.1.0**.
+
+Planishing hammers a metal surface smooth and even. OTT does the same to a bass:
+it pushes loud bands down and lifts quiet ones, and it is on almost every riddim
+patch. A normal OTT splits the bands at fixed frequencies, though. A split at
+88 Hz and 2.5 kHz puts harmonic 2 of F1 in the low band but harmonic 2 of C2 in
+the mid band, so the same setting squashes different harmonics on every note.
+Planish moves its band edges with the note: with the default split, band 1 is
+the fundamental, band 2 harmonics 2–4, band 3 harmonics 5–16 and band 4
+everything above, on F1 as on G2.
+
+![Planish](assets/editor.png)
+
+## Install on Windows
+
+Copy `Planish.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 Planish in a mixer slot of the bass. Keep the font
+license with redistributed packages.
+
+## Work with it
+
+1. Play the bass. The note readout shows what Planish tracks. The ruler at the
+   top shows harmonics 1–64 and the four bands; the columns below show each
+   band's level (steel) and gain (pink for a cut, blue for a lift).
+2. Choose a split, or drag an edge on the ruler:
+   - **Classic** (1, 2–4, 5–16, 17+, the default): fundamental on its own.
+   - **Sub + body** (1–2, 3–6, 7–24, 25+): the octave stays with the sub.
+   - **Tight** (1, 2, 3–8, 9+): close control of the first harmonics.
+   - **Wide top** (1, 2–3, 4–32, 33+): one big mid band, the top is fizz only.
+3. Set the amount:
+   - **Depth** blends each band with its compressed copy. 0 % is a clean sum
+     of the bands; the default is 50 %.
+   - **Drive** moves the band levels against the thresholds: more drive, more
+     squash. It does not change the level by itself.
+   - **Upward** and **Downward** scale the two directions. Downward pushes a
+     band above −30 dB down at about 20:1; Upward lifts a band below −42 dB at
+     about 4:1, by at most 24 dB.
+   - **Time** scales every attack and release. Lower bands are slower: at
+     100 %, attack is 30, 15, 8 and 4 ms and release 200, 160, 120 and 90 ms
+     from band 1 to band 4.
+4. **Band 1–4** set each band's gain after its compressor. Like the
+   compression, they are scaled by Depth.
+
+**Output** trims the level. **Bypass** crossfades to the delayed dry signal.
+
+### Pitch from MIDI
+
+For basses whose fundamental is unclear (heavy FM, formant or noise patches),
+and when Planish comes after Knurl, select **MIDI** and route the bass's MIDI
+notes to Planish. In FL Studio, set the bass channel's MIDI output port and
+Planish's input port to the same number. **Gate** sets the input level that
+counts as a note in AUDIO mode. **Snap to semitone** rounds the detected pitch;
+it is off by default, because the level is measured over one period of the
+pitch in use, and a detuned patch fits its real period better.
+
+## Measured
+
+- At Depth 0 the bands sum flat: sines from 35 Hz to 12 kHz come out within
+  0.05 dB.
+- The same setting changes the same harmonics on every note. At Depth 100 %
+  on a saw bass, harmonic 1 is cut by 13.6 dB on F1, C2 and G2; harmonics 1–12
+  differ by less than 0.2 dB between the three notes.
+- No ripple at the fundamental. A 40 Hz sine at Drive +12 dB and Time 10 % gets
+  no harmonics above −110 dB.
+
+## Timing and limits
+
+Planish delays the audio by about 67 ms of pitch-detection lookahead and
+reports it to the host for delay compensation, so the edges are on the new note
+when its attack leaves the plugin. Pitch range is 30–500 Hz, one note at a time.
+Before the first note the edges sit on 55 Hz; between notes they hold the last
+note.
+
+An edge is a slope, not a wall. The crossovers are 24 dB per octave, so the
+harmonics next to an edge partly reach the next band, by the same amount on
+every note. Both channels get the same gain per band, so the stereo image does
+not move. Quiet signals below about −84 dB are not lifted, so noise floors and
+tails stay down.
+
+Planish detects the pitch like Lathe and Temper. Put it before Knurl, or use
+MIDI: see [Signal chain](../chain.md).
+
+## How it works
+
+A note tracker (shared with Anvil, Lathe, Temper and Knurl) detects pitch and
+note starts ahead of the delayed audio. Three Linkwitz–Riley crossovers split
+the signal at √(k(k+1)) × f0, halfway in log frequency between harmonic k and
+k+1, and allpasses keep the lower bands in phase with the upper ones, so the
+bands sum to an allpass. The crossovers retune every 16 samples and glide with
+**Smooth** on bends. Each band's level is the RMS over exactly one period of
+the note, so a steady note gives a steady level and the gain does not wobble
+at f0. The level goes through attack and release smoothing, then a static
+curve with an upward and a downward threshold sets the gain.
@@ -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.
@@ -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.
@@ -1,49 +1,56 @@
 # Independent plugin releases on Gitea

-Rivet and Patina have independent versions and releases. Workflows live under
-`.gitea/workflows/`.
+Every Bass Foundry plugin has its own version and its own release. The
+workflows are in `.gitea/workflows/`. A plugin's version is the `version` in
+`plugins/<plugin>/plugin/Cargo.toml`, and its release tag is
+`<plugin>-v<version>`.

-| Tag | Gitea release | Windows download |
+| Plugin | Latest tag | Windows download |
 | --- | --- | --- |
-| `rivet-v0.3.0` | Rivet 0.3.0 | `rivet-windows-x86_64-0.3.0.zip` |
-| `patina-v0.1.0` | Patina 0.1.0 | `patina-windows-x86_64-0.1.0.zip` |
+| Rivet | `rivet-v0.5.0` | `rivet-windows-x86_64-0.5.0.zip` |
+| Patina | `patina-v0.5.0` | `patina-windows-x86_64-0.5.0.zip` |
+| Anvil | `anvil-v0.3.0` | `anvil-windows-x86_64-0.3.0.zip` |
+| Crucible | `crucible-v0.3.0` | `crucible-windows-x86_64-0.3.0.zip` |
+| Lathe | `lathe-v0.2.0` | `lathe-windows-x86_64-0.2.0.zip` |
+| Temper | `temper-v0.2.0` | `temper-windows-x86_64-0.2.0.zip` |
+| Weld | `weld-v0.3.0` | `weld-windows-x86_64-0.3.0.zip` |
+| 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` |
+| Forge | `forge-v0.1.0` | `forge-windows-x86_64-0.1.0.zip` |

 ## Make a release

-1. Update the selected wrapper's `Cargo.toml` version and its
-   `docs/<product>/CHANGELOG.md`. The wrapper version determines the release
-   version; internal crate versions can evolve separately.
-2. Refresh affected lockfiles, run the product check, and commit/push the change.
-3. Tag the intended commit and push that product's tag.
+1. Set the new version in the plugin's wrapper `Cargo.toml` and add a section
+   with that version to `docs/<plugin>/CHANGELOG.md`. Internal crate versions
+   can change independently.
+2. Refresh the affected lockfiles, run the plugin's check, then commit and push.
+3. Tag the commit and push only that plugin's tag.

-For Rivet:
+For example, Temper 0.2.0:

 ```sh
-python scripts/check-plugin.py --plugin rivet
-git tag -a rivet-v0.3.0 -m "Rivet 0.3.0"
-git push origin rivet-v0.3.0
+python3 scripts/check-plugin.py --plugin temper
+git tag -a temper-v0.2.0 -m "Temper 0.2.0"
+git push origin temper-v0.2.0
 ```

-For Patina:
-
-```sh
-python scripts/check-plugin.py --plugin patina
-git tag -a patina-v0.1.0 -m "Patina 0.1.0"
-git push origin patina-v0.1.0
-```
-
-These are instructions; this change does not create tags or publish a release.
-Tags must exactly match the selected wrapper version and a changelog section.
-Wrong product/version tags fail before building or publishing. Cargo prerelease
-versions such as `patina-v0.2.0-rc.1` are supported and marked as prereleases.
+The tag must match the wrapper version and a changelog section exactly. A wrong
+plugin name or version fails in the `plan` job, before anything is built or
+published. Cargo prerelease versions such as `temper-v0.2.0-rc.1` are supported
+and published as prereleases.

 ## Workflows

 **Check and Windows preview** runs on branch pushes, pull requests, and manual
-dispatch. It checks both products, renders editor previews, and provides a combined
-Windows ZIP as an Actions artifact. It never publishes a release.
+dispatch. It checks every product in a matrix, renders all editor previews, and
+provides the combined `bass-foundry-windows-x86_64.zip` as an Actions artifact.
+It never publishes a release.

-**Independent plugin release** runs on `rivet-v*` or `patina-v*` tag pushes:
+**Independent plugin release** runs when a `<plugin>-v*` tag is pushed, for any
+plugin in the catalog:

 1. `plan` validates the product/version/changelog and exposes the selected plugin.
 2. `build` checks and cross-compiles only that plugin, then packages its Windows
@@ -106,7 +113,7 @@ The release tag must already exist in Gitea; the publisher does not create tags.
 The ZIP must contain exactly the selected plugin. Its sidecar and internal file
 checksums are verified before any release write.

-Choose a plugin's named release/tag rather than assuming the repository's global
-latest release refers to both products. Package and API behavior are tested with
-fake transports; an actual runner/tag release on this Gitea instance remains to
-be verified.
+Link to a plugin's own release or tag. The repository's "latest release" is
+only the most recent release of any plugin. Packaging and API behaviour are tested with
+fake transports. Every tag in the table above was published by this workflow on
+the project's Gitea instance.
@@ -1,5 +1,11 @@
 # Rivet changelog

+## 0.5.0
+
+- Change the CLAP ID to `io.narl.bass-foundry.rivet`. Hosts see this as a new
+  plugin: delete the old `.clap` file, rescan, and add the plugin again in
+  existing projects.
+
 ## 0.4.0

 - Storyboard: a timeline of blocks with roles (statement, answer, departure,
@@ -1,7 +1,7 @@
 # Rivet

 Rivet joins short motifs into connected musical phrases, like a fastener joining
-individual pieces. Formerly **Motif Storyboard**; current version **0.4.0**.
+individual pieces. Formerly **Motif Storyboard**; current version **0.5.0**.


 A Rust composition companion for a producer developing their own melodic ideas.
@@ -145,8 +145,8 @@ and silent startup at several sample rates and buffer sizes.

 ## Existing projects

-The name, Cargo packages, source paths, and output filename have changed.
-The CLAP ID `io.storyboard.motif`, `story-session-v1` host field, and session
-JSON format are preserved. Rescan FL Studio after replacing the old plugin file
-with `Rivet.clap`; remove the old copy from scanned folders to avoid duplicate
-instances with the same ID. Project recall still needs a check in the target host.
+The CLAP ID is now `io.narl.bass-foundry.rivet` (earlier builds used
+`io.storyboard.motif`). Hosts treat Rivet as a new plugin, so add it again in
+projects saved with an earlier build. The `story-session-v1` host field and the
+session JSON format are preserved, so saved sessions still open. Delete the old
+plugin file, place `Rivet.clap`, and rescan FL Studio.
@@ -0,0 +1,20 @@
+# Temper changelog
+
+## 0.2.0
+
+- Change the CLAP ID to `io.narl.bass-foundry.temper`. Hosts see this as a new
+  plugin: delete the old `.clap` file, rescan, and add the plugin again in
+  existing projects.
+
+## 0.1.0
+
+- Introduce Temper, a note-tracked distortion for bass sound design.
+- Normalises each note's level before the shaper, so quiet and loud patches are
+  driven the same.
+- Floor (highpass), Push (one harmonic boosted or cut) and Bright (lowpass) sit
+  at multiples of the played note, so every note keeps the same character.
+- Curves: Soft, Hard, Fold and Tube, with Bias for even harmonics. The shaper runs
+  at 4× oversampling.
+- Auto gain keeps the output at the input loudness while Drive changes.
+- Detect pitch and note starts from the audio with 67 ms lookahead, or follow
+  MIDI notes sent to the effect.
@@ -0,0 +1,66 @@
+# Temper
+
+Temper is a distortion that drives every note the same. Current version **0.2.0**.
+
+A distortion with a fixed tone filter acts differently on each note: a lowpass
+at 2 kHz lets through 45 harmonics of an F1 but only 22 of an F2, and
+a patch that is 6 dB quieter is driven 6 dB less. Across a riddim line that makes
+some notes fizzy and others dull. Temper evens out each note's level before the
+shaper and moves its tone filters with the pitch, so the character stays the same
+on every note.
+
+![Temper](assets/editor.png)
+
+## Install on Windows
+
+Copy `Temper.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 Temper in a mixer slot of the bass. Keep the font license
+with redistributed packages.
+
+## Work with it
+
+1. Choose a **Curve**:
+   - **Soft**: tanh, smooth and rounded.
+   - **Hard**: clipping with a narrow knee, dense and square-like.
+   - **Fold**: the wave folds back on itself; Drive moves the upper harmonics.
+   - **Tube**: the negative half clips earlier, adding even harmonics.
+2. Set **Drive**. The transfer plot shows the curve over the range a normalised
+   note covers; the **Into shaper** meter shows how far past the knee it goes.
+3. Add **Bias** for asymmetry and even harmonics.
+4. Shape the tone around the shaper, all in multiples of the note:
+   - **Floor** is a highpass before the shaper (0.25–2 × the fundamental; 0 is
+     off). It keeps sub mud out of the distortion. Put Anvil after Temper to add a
+     clean sub back.
+   - **Push** boosts or cuts one harmonic (**Push at**, 1–16) before the shaper,
+     so the distortion bites in the same place on every note.
+   - **Bright** is a lowpass after the shaper at a harmonic number (4–64; 0 is
+     off), so the top end stops at the same harmonic on every note.
+
+Other controls:
+
+- **Normalize** is how far each note's level is evened out before Drive. At 100 %
+  a quiet and a loud patch distort the same; at 0 % Temper acts like a normal
+  distortion.
+- **Auto gain** keeps the output at the input's loudness, so turning up Drive
+  changes the character, not the level.
+- **Gate** is the input level that counts as a note.
+- **Mix** blends with the delayed dry signal; **Output** trims the level.
+
+### Pitch from MIDI
+
+Select **MIDI** and route the bass's MIDI notes to Temper when detection
+struggles. In FL Studio, set the bass channel's MIDI output port and Temper's
+input port to the same number.
+
+## Timing and limits
+
+Detection uses about 67 ms of lookahead; the 4× oversampling filters add under
+1 ms. Both are reported to the host for delay compensation. Pitch range is
+30–500 Hz, one note at a time. Before the first note the tracked filters are off;
+between notes they hold the last tuning.
+
+Aliasing stays below −60 dB for bass material (tested with a 2 kHz tone at 24 dB
+drive and a 440 Hz tone at full drive, on every curve). High-pitched content at
+full drive aliases more: a 5 kHz tone at 36 dB on the Hard curve reaches about
+−31 dB.
@@ -0,0 +1,28 @@
+# Weld changelog
+
+## 0.3.0
+
+- Show the **delay spread**: how much the alignment's group delay changes
+  between 500 Hz and 4 kHz, where listeners hear it best. Above 0.64 ms (the
+  threshold Liski et al. 2021 measured on clicks) a note suggests comparing
+  attacks in SUM and SUM DRY. Display only; the sound does not change.
+
+## 0.2.0
+
+- Change the CLAP ID to `io.narl.bass-foundry.weld`. Hosts see this as a new
+  plugin: delete the old `.clap` file, rescan, and add the plugin again in
+  existing projects.
+
+## 0.1.0
+
+- Introduce Weld, a phase aligner for layered bass.
+- Hears the other layer through the sidechain input and fits polarity plus up to
+  four allpass sections, so the layers sum instead of cancelling. No latency;
+  the layer on its own keeps its sound.
+- Modes: Follow (refits only when clearly better), Learn (measure one take,
+  apply on exit), Hold. The alignment is saved with the project.
+- Display: level per band against a perfect alignment (lost and won back),
+  phase before and after, recovered dB, cancellation cost, time offset, and
+  warnings for a late layer, unrelated layers and a missing sidechain.
+- Controls: Mode, Sections, Response, Low, High, Gate, Listen (Layer, Sum,
+  Sum dry), Output, Bypass.
@@ -0,0 +1,115 @@
+# Weld
+
+Weld fuses two bass layers so they add up instead of cancelling. Current version
+**0.3.0**.
+
+Bass patches are layered: a sub, one or more mid growls, a top. Where the layers
+overlap in the mids, they partly cancel. The causes are a polarity difference, a
+small time offset between the layers, and the phase shift of the filters and EQs
+in one chain. The result is a thin, hollow sum that changes with every
+switch-up. Anvil fixes this for the sub band; Weld fixes it for the mids.
+
+Weld sits on one layer and hears the other one through the sidechain input. It
+measures how the two layers line up, then turns the phase of its own layer with
+a polarity flip and up to four allpass filters. An allpass changes only phase,
+so the layer on its own sounds the same; only the sum changes. Weld adds no
+latency.
+
+![Weld](assets/editor.png)
+
+## Install on Windows
+
+Copy `Weld.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. Keep the font license with redistributed packages.
+
+## Set up in FL Studio
+
+1. Put each layer on its own mixer track. Load Weld on the track of one layer,
+   the main layer.
+2. Select the other layer's track. Right-click the route arrow under the main
+   layer's track and choose **Sidechain to this track**. The other layer still
+   goes to the master on its own; the sidechain only lets Weld hear it.
+3. In Weld's plugin wrapper, open the settings (gear icon) and set Weld's
+   sidechain input to that track.
+4. Play both layers. The SIDECHAIN meter must move. If the display says "No
+   sidechain signal", check step 3.
+
+## Work with it
+
+1. Leave **Mode** on **FOLLOW** and play the part where both layers sound. After
+   a second or two, Weld shows its alignment: polarity, and the allpass sections
+   with their frequency and Q.
+2. Read the display:
+   - **Recovered** is how much level the sum gains, as an average per band
+     between Low and High. **Cancellation cost** is how much a perfect alignment
+     would gain. When the two numbers are close, Weld got nearly everything.
+   - The upper plot shows each band against a perfectly aligned sum (0 dB). Red
+     is what the unprocessed sum loses to cancellation; pink is the part Weld
+     wins back. The white line is the level with Weld.
+   - The lower plot shows the phase of this layer against the other one, before
+     (grey) and after (pink), and Weld's own phase curve (blue). After alignment
+     the pink line sits near 0°.
+   - **Delay spread** under the sections is how much Weld's delay changes
+     between 500 Hz and 4 kHz. On clicks, listeners hear about 0.6 ms of change
+     there (Liski et al. 2021); sustained bass hides much more, and common fits
+     reach 0.8–1 ms. Above that threshold Weld adds a note: on a plucky layer,
+     compare the attacks in SUM and SUM DRY. Fewer sections usually spread less.
+3. Compare by ear: mute the other layer's own route to the master, set
+   **Listen** to **SUM**, then to **SUM DRY**. Set Listen back to **LAYER** and
+   unmute the route for the mix.
+4. When the alignment is right, switch to **HOLD**. It is saved with the project
+   and comes back when the project opens.
+
+For one drop or switch-up, use **LEARN**: press it, play the part, then press
+**HOLD** (or LEARN again). Weld measures the whole take with equal weight and
+applies the result when Learn ends.
+
+## Controls
+
+- **Mode**:
+  - **Follow** keeps measuring and refits only when a new alignment is clearly
+    better (at least 0.3 dB on average), so the filter does not wander.
+  - **Learn** starts a fresh measurement and applies its result when Learn ends.
+  - **Hold** keeps the current alignment. The display keeps measuring.
+- **Sections** (1–4) is the largest number of allpass sections the fit may use.
+  Weld uses fewer when fewer are enough.
+- **Response** (0.3–5 s) is the averaging time in Follow. Longer is steadier.
+- **Low** and **High** set the range the fit listens to. Low defaults to 60 Hz,
+  leaving the sub to Anvil. The allpass still acts below Low, and the display
+  shows that honestly.
+- **Gate** (−70 to −30 dB): moments where either layer is quieter are not
+  measured, so tails and silence do not pull the fit.
+- **Listen**: **Layer** outputs this layer, aligned, for the mix. **Sum** outputs
+  this layer aligned plus the sidechain layer. **Sum dry** outputs both
+  unprocessed.
+- **Output** trims the level; **Bypass** passes this layer unchanged.
+
+## Limits
+
+- **A late layer cannot be moved earlier.** An allpass only delays. If the layer
+  Weld sits on is the later one, the display shows "This layer is late" and the
+  offset in ms. Put Weld on the other layer instead.
+- **Free-running layers cannot be aligned.** Without oscillator retrigger, or
+  with detuned unison, the phase between the layers drifts all the time. Weld
+  marks those bands as *loose* (hatched) and does not fit them. Enable retrigger
+  in the synth if you want Weld to align the layers.
+- **Delays leave a comb.** A time offset between the layers cancels at regular
+  frequencies. A few allpass sections cannot follow a delay all the way up, so
+  Weld aligns the lower range and moves the higher notches rather than removing
+  them. For a large offset, move the layer in time first.
+- **One alignment for the whole patch.** Weld does not change the alignment per
+  note. If switch-ups need different alignments, use Follow, or automate Mode.
+- **The sidechain must arrive.** With no sidechain signal Weld changes nothing.
+
+## How it works
+
+Every 256 samples the audio thread hands mono copies of both layers to a worker
+thread through a lock-free queue. The worker estimates their cross-spectrum
+(Welch, Hann window, about 11.7 Hz per bin, 50 % overlap) and their coherence.
+It fits polarity plus up to four second-order allpass sections so that
+Σ w(f)·Re(S(f)·H(f)) is largest, with w = 1/f so every octave counts, ignoring
+bins where the layers are not coherent, and with a penalty for any band that
+would lose more than 1 dB. A new fit fades in over 40 ms after its filters have
+settled for 40 ms, so there are no clicks. One fit takes about 15 ms on one
+core, twice per second in Follow.
@@ -0,0 +1,12 @@
+[package]
+name = "anvil-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 }
@@ -0,0 +1,777 @@
+//! Sub anchor: replaces the band below the split with a clean mono sine that follows the
+//! bass pitch, holds one level for every note and restarts at the same phase on each note.
+//!
+//! The audio path is delayed by a fixed lookahead. Detection runs on the undelayed input, so
+//! a note's pitch is known before its delayed attack leaves the plugin, and the sine starts
+//! exactly on that attack.
+//!
+//! Ghost harmonics add the sub's own harmonics above a chosen frequency, so the note
+//! reads on speakers without sub. The band above the split is measured per harmonic and
+//! only the harmonics the patch lacks are filled: a harmonic the patch already has would
+//! meet the added one at an unrelated phase and could cancel.
+//!
+//! Kick lock reads the kick from the sidechain. Hits are found on the undelayed sidechain,
+//! so with the lookahead each hit ducks the sub exactly when the delayed kick plays, and
+//! restarts the sub's phase at the kick plus an offset, also before the kick. The audition
+//! plays each offset of a sweep for a few kicks and measures how kick and sub sum in the
+//! low band for each one; what sums loudest is not always what sounds like one hit.
+mod settings;
+use common_dsp::meter::HarmonicMeter;
+use common_dsp::svf::{Svf, SvfCoef};
+use common_dsp::tracker::{NoteEvent, Tracker, TrackerConfig};
+use common_dsp::{coefficient, db_to_gain, hz_to_midi, midi_to_hz, Biquad, Crossover};
+pub use settings::{Settings, Source, KICK_OFFSET_MAX};
+use std::f32::consts::TAU;
+
+/// Detectable fundamental range. The lowest sets the lookahead (two periods).
+pub const MIN_HZ: f32 = TrackerConfig::SUB.min_hz;
+pub const MAX_HZ: f32 = TrackerConfig::SUB.max_hz;
+pub const SCOPE: usize = 256;
+const ATTACK_MS: f32 = 2.;
+const RELEASE_MS: f32 = 15.;
+const CROSSFADE_MS: f32 = 3.;
+/// Highest Ghost harmonic. Harmonic 10 of a 30 Hz sub is 300 Hz.
+pub const GHOST_TOP: usize = 10;
+/// Ghost harmonics shown and generated: 2..=GHOST_TOP.
+pub const GHOST_COUNT: usize = GHOST_TOP - 1;
+/// Measurement window per note. Resolves harmonics of fundamentals down to about 35 Hz.
+const GHOST_WINDOW_MS: f32 = 60.;
+/// Harmonics fade in over this many octaves above the Ghost edge, so a gliding note
+/// does not switch them on with a step.
+const GHOST_RAMP_OCT: f32 = 0.5;
+/// Offsets the audition steps through, in ms.
+pub const AUDITION: [f32; 13] = [
+    -30., -25., -20., -15., -10., -5., 0., 5., 10., 15., 20., 25., 30.,
+];
+/// Kicks each audition offset plays for.
+pub const AUDITION_HITS: u32 = 4;
+/// A kick is a rise of the fast sidechain envelope this far above the slow one...
+const KICK_RISE: f32 = 2.8;
+/// ...above this level (−45 dBFS)...
+const KICK_FLOOR: f32 = 0.0056;
+/// ...at least this long after the previous kick.
+const KICK_HOLD_MS: f32 = 60.;
+/// Kick and sub are compared below this frequency, over this long after each hit.
+const KICK_LOW_HZ: f32 = 150.;
+const SUM_MS: f32 = 60.;
+const DUCK_ATTACK_MS: f32 = 1.;
+const PENDING: usize = 16;
+/// Small speaker listen: a phone-like band, summed to mono.
+pub const PHONE_LOW: f32 = 400.;
+pub const PHONE_HIGH: f32 = 7000.;
+
+#[derive(Clone, Copy, Debug, Default)]
+pub struct Monitor {
+    /// Hear only the generated sub and Ghost harmonics.
+    pub solo: bool,
+    /// Hear the output through a phone-like speaker band, in mono.
+    pub phone: bool,
+    /// Step the kick offset through `AUDITION`, `AUDITION_HITS` kicks each.
+    pub audition: bool,
+}
+
+#[derive(Clone, Copy, Debug)]
+pub struct AnalyzerFrame {
+    /// Current sub frequency in Hz, 0 when silent.
+    pub hz: f32,
+    /// MIDI note of the current sub, rounded.
+    pub note: Option<u8>,
+    pub low_db: f32,
+    pub sub_db: f32,
+    /// Harmonics 2..=GHOST_TOP of the current note, peak dB relative to the sub: what the
+    /// patch carries above the split, and what Ghost adds. −120 when absent.
+    pub patch_harmonics: [f32; GHOST_COUNT],
+    pub ghost_harmonics: [f32; GHOST_COUNT],
+    /// Lowest frequency Ghost fills, after the split.
+    pub ghost_edge: f32,
+    /// Kicks found in the sidechain since the plugin started.
+    pub kick_hits: u32,
+    /// Kick plus sub against kick and sub apart, low band, dB, after the last hit. +3 is a
+    /// full sum of equal levels, 0 unrelated, below 0 they cancel. NaN before a hit.
+    pub kick_sum_db: f32,
+    /// Offset the sub restarted with on the latest kick, in ms.
+    pub kick_offset: f32,
+    /// Measured sum per audition offset, dB; NaN where not measured yet.
+    pub audition_sums: [f32; AUDITION.len()],
+    /// Original low band and new sub, triggered on a rising zero crossing of the sub.
+    pub scope_low: [f32; SCOPE],
+    pub scope_sub: [f32; SCOPE],
+    /// Duration of the scope window in milliseconds.
+    pub scope_ms: f32,
+    pub latency: u32,
+    pub sample_rate: f32,
+}
+impl Default for AnalyzerFrame {
+    fn default() -> Self {
+        Self {
+            hz: 0.,
+            note: None,
+            low_db: -120.,
+            sub_db: -120.,
+            patch_harmonics: [-120.; GHOST_COUNT],
+            ghost_harmonics: [-120.; GHOST_COUNT],
+            ghost_edge: 300.,
+            kick_hits: 0,
+            kick_sum_db: f32::NAN,
+            kick_offset: 0.,
+            audition_sums: [f32::NAN; AUDITION.len()],
+            scope_low: [0.; SCOPE],
+            scope_sub: [0.; SCOPE],
+            scope_ms: 60.,
+            latency: 0,
+            sample_rate: 48000.,
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, Default)]
+struct Voice {
+    phase: f32,
+    hz: f32,
+    target: f32,
+    amp: f32,
+    releasing: bool,
+}
+
+/// Sine voices and per-note state, driven by tracker events at output time.
+#[derive(Clone, Copy, Debug, Default)]
+struct Synth {
+    voice: Voice,
+    old: Voice,
+    old_gain: f32,
+    note_peak: f32,
+    /// Set when a note starts or changes pitch; the Ghost measurement starts over.
+    fresh: bool,
+}
+impl Synth {
+    fn event(&mut self, s: &Settings, e: NoteEvent) {
+        match e {
+            NoteEvent::Start { pitch, glide } => self.start(s, pitch, glide),
+            NoteEvent::Move { pitch } => {
+                if !s.snap {
+                    self.voice.target = midi_to_hz(pitch + 12. * s.octave as f32);
+                }
+            }
+            NoteEvent::Stop => self.voice.releasing = true,
+        }
+    }
+    fn start(&mut self, s: &Settings, pitch: f32, glide: bool) {
+        let note = if s.snap { pitch.round() } else { pitch };
+        let hz = midi_to_hz(note + 12. * s.octave as f32);
+        let audible = self.voice.amp > 1e-4 && !self.voice.releasing;
+        if glide && audible {
+            self.voice.target = hz;
+            return;
+        }
+        if s.retrigger || !audible {
+            if self.voice.amp > 1e-4 {
+                // Restarting the phase mid-cycle would click; the old cycle fades out instead.
+                self.old = self.voice;
+                self.old_gain = 1.;
+            }
+            self.voice = Voice {
+                phase: s.phase / 360.,
+                hz,
+                target: hz,
+                amp: 0.,
+                releasing: false,
+            };
+        } else {
+            self.voice.target = hz;
+            self.voice.hz = hz;
+        }
+        self.note_peak = 0.;
+        self.fresh = true;
+    }
+    /// Restarts a sounding sub at the start phase, keeping its pitch.
+    fn kick(&mut self, s: &Settings) {
+        let v = self.voice;
+        if v.amp <= 1e-4 || v.releasing {
+            return;
+        }
+        self.old = v;
+        self.old_gain = 1.;
+        self.voice = Voice {
+            phase: s.phase / 360.,
+            amp: 0.,
+            ..v
+        };
+    }
+}
+
+#[derive(Clone, Copy, Debug, Default)]
+struct Pending {
+    /// Output-time sample.
+    at: u64,
+    /// Restart the sub (true) or duck it and start measuring (false).
+    restart: bool,
+    offset: f32,
+    /// Audition offset index this hit belongs to.
+    slot: Option<usize>,
+}
+
+/// Kick detection, scheduling, ducking and the sum measurement.
+struct Kick {
+    clock: u64,
+    fast: f32,
+    slow: f32,
+    fast_coef: f32,
+    slow_coef: f32,
+    hold: usize,
+    pending: [Option<Pending>; PENDING],
+    delay: Vec<f32>,
+    delay_at: usize,
+    low: Biquad,
+    duck: f32,
+    rising: bool,
+    attack: f32,
+    measure: usize,
+    measure_slot: Option<usize>,
+    energy: [f32; 3],
+    hits: u32,
+    sum_db: f32,
+    offset: f32,
+    auditioning: bool,
+    slot: usize,
+    slot_hits: u32,
+    sums: [f32; AUDITION.len()],
+    counts: [u32; AUDITION.len()],
+}
+impl Kick {
+    fn new(rate: f32, latency: usize) -> Self {
+        Self {
+            clock: 0,
+            fast: 0.,
+            slow: 0.,
+            fast_coef: coefficient(rate, 0.5),
+            slow_coef: coefficient(rate, 30.),
+            hold: 0,
+            pending: [None; PENDING],
+            delay: vec![0.; latency + 1],
+            delay_at: 0,
+            low: Biquad::lowpass(rate, KICK_LOW_HZ, std::f32::consts::FRAC_1_SQRT_2),
+            duck: 0.,
+            rising: false,
+            attack: coefficient(rate, DUCK_ATTACK_MS / 3.),
+            measure: 0,
+            measure_slot: None,
+            energy: [0.; 3],
+            hits: 0,
+            sum_db: f32::NAN,
+            offset: 0.,
+            auditioning: false,
+            slot: 0,
+            slot_hits: 0,
+            sums: [f32::NAN; AUDITION.len()],
+            counts: [0; AUDITION.len()],
+        }
+    }
+    fn reset(&mut self) {
+        self.fast = 0.;
+        self.slow = 0.;
+        self.hold = 0;
+        self.pending = [None; PENDING];
+        self.delay.fill(0.);
+        self.low.reset();
+        self.duck = 0.;
+        self.rising = false;
+        self.measure = 0;
+        self.measure_slot = None;
+        self.sum_db = f32::NAN;
+        self.slot = 0;
+        self.slot_hits = 0;
+        self.sums = [f32::NAN; AUDITION.len()];
+        self.counts = [0; AUDITION.len()];
+    }
+    fn schedule(&mut self, p: Pending) {
+        if let Some(free) = self.pending.iter_mut().find(|p| p.is_none()) {
+            *free = Some(p);
+        }
+    }
+}
+
+pub struct Engine {
+    rate: f32,
+    channels: usize,
+    settings: Settings,
+    latency: usize,
+    delay: Vec<[f32; 2]>,
+    delay_at: usize,
+    crossover: [Crossover; 2],
+    tracker: Tracker,
+    synth: Synth,
+    glide: f32,
+    low_env: f32,
+    env_coef: f32,
+    smooth: f32,
+    level: f32,
+    keep: f32,
+    output: f32,
+    bypass: f32,
+    meter_coef: f32,
+    low_power: f32,
+    sub_power: f32,
+    scope_low: [f32; 2 * SCOPE],
+    scope_sub: [f32; 2 * SCOPE],
+    scope_at: usize,
+    scope_stride: usize,
+    scope_count: usize,
+    meter: HarmonicMeter,
+    /// Linear peak of the patch's harmonic k (index k − 2) above the split, this note.
+    patch: [f32; GHOST_COUNT],
+    /// Smoothed Ghost gain per harmonic, relative to the sub's peak.
+    fill: [f32; GHOST_COUNT],
+    phone_coefs: [SvfCoef; 3],
+    phone: [Svf; 3],
+    kick: Kick,
+}
+
+impl Engine {
+    pub fn new(rate: f32, channels: usize) -> Result<Self, &'static str> {
+        if !(8000.0..=768000.).contains(&rate) {
+            return Err("unsupported sample rate");
+        }
+        if !(1..=2).contains(&channels) {
+            return Err("unsupported channel count");
+        }
+        let tracker = Tracker::new(rate, TrackerConfig::SUB);
+        let latency = tracker.latency();
+        let settings = Settings::default();
+        let mut e = Self {
+            rate,
+            channels,
+            settings,
+            latency,
+            delay: vec![[0.; 2]; latency + 1],
+            delay_at: 0,
+            crossover: [Crossover::new(rate, settings.split); 2],
+            tracker,
+            synth: Synth::default(),
+            glide: 1.,
+            low_env: 0.,
+            env_coef: coefficient(rate, 10.),
+            smooth: coefficient(rate, 10.),
+            level: db_to_gain(settings.level),
+            keep: 0.,
+            output: 1.,
+            bypass: 0.,
+            meter_coef: coefficient(rate, 150.),
+            low_power: 0.,
+            sub_power: 0.,
+            scope_low: [0.; 2 * SCOPE],
+            scope_sub: [0.; 2 * SCOPE],
+            scope_at: 0,
+            scope_stride: ((rate * 0.06) / SCOPE as f32).round().max(1.) as usize,
+            scope_count: 0,
+            meter: HarmonicMeter::new(rate, GHOST_WINDOW_MS),
+            patch: [0.; GHOST_COUNT],
+            fill: [0.; GHOST_COUNT],
+            phone_coefs: [
+                // Fourth-order Butterworth high-pass, second-order low-pass.
+                SvfCoef::highpass(rate, PHONE_LOW, 0.541),
+                SvfCoef::highpass(rate, PHONE_LOW, 1.307),
+                SvfCoef::lowpass(rate, PHONE_HIGH.min(0.45 * rate), 0.707),
+            ],
+            phone: [Svf::default(); 3],
+            kick: Kick::new(rate, latency),
+        };
+        e.set_settings(settings)?;
+        Ok(e)
+    }
+    pub fn latency_samples(&self) -> u32 {
+        self.latency 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()?;
+        let old = self.settings;
+        if (s.split - old.split).abs() > 1e-3 {
+            for x in &mut self.crossover {
+                x.retune(self.rate, s.split);
+            }
+        }
+        if self
+            .tracker
+            .set(s.source == Source::Midi, s.gate, s.glide > 0.)
+        {
+            self.synth.voice.releasing = true;
+        }
+        self.glide = if s.glide <= 0. {
+            1.
+        } else {
+            coefficient(self.rate, s.glide / 3.)
+        };
+        self.settings = s;
+        Ok(())
+    }
+    pub fn reset(&mut self) {
+        self.delay.fill([0.; 2]);
+        for x in &mut self.crossover {
+            x.reset();
+        }
+        self.tracker.reset();
+        self.synth = Synth::default();
+        self.low_env = 0.;
+        self.low_power = 0.;
+        self.sub_power = 0.;
+        self.scope_low = [0.; 2 * SCOPE];
+        self.scope_sub = [0.; 2 * SCOPE];
+        self.meter.reset();
+        self.patch = [0.; GHOST_COUNT];
+        self.fill = [0.; GHOST_COUNT];
+        for f in &mut self.phone {
+            f.reset();
+        }
+        self.kick.reset();
+    }
+    /// Lowest frequency Ghost fills.
+    fn ghost_edge(&self) -> f32 {
+        self.settings.ghost_from.max(self.settings.split)
+    }
+    /// Moves each Ghost gain toward what the patch lacks at the current note.
+    fn update_fill(&mut self) {
+        let s = &self.settings;
+        let v = self.synth.voice;
+        let amount = s.ghost * 0.01;
+        let edge = self.ghost_edge();
+        let sub = self.level.max(1e-6);
+        for (i, fill) in self.fill.iter_mut().enumerate() {
+            let k = (i + 2) as f32;
+            let f = k * v.hz;
+            let target = if amount > 0. && v.hz > 0. && f < 0.45 * self.rate {
+                let ramp = ((f / edge).log2() / GHOST_RAMP_OCT).clamp(0., 1.);
+                // A 1/k slope, like a saw; at 100 % harmonic k sits at 2/k of the sub.
+                let want = amount * 2. / k * ramp;
+                (want - self.patch[i] / sub).max(0.)
+            } else {
+                0.
+            };
+            *fill += (target - *fill) * self.smooth;
+        }
+    }
+    /// Ghost harmonics for a voice at `phase`, without the voice's amplitude.
+    #[inline]
+    fn ghost(&self, phase: f32) -> f32 {
+        let mut out = 0.;
+        for (i, &g) in self.fill.iter().enumerate() {
+            if g > 1e-5 {
+                out += g * (TAU * ((i + 2) as f32 * phase).fract()).sin();
+            }
+        }
+        out
+    }
+    /// MIDI note start at the current input sample. Used when the source is MIDI.
+    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);
+    }
+    #[inline]
+    fn shape(&self, x: f32) -> f32 {
+        let drive = self.settings.drive * 0.01;
+        if drive <= 0. {
+            return x;
+        }
+        let k = 1. + 6. * drive;
+        (k * x).tanh() / k.tanh()
+    }
+    /// The shaped sub and the Ghost harmonics, before level and dynamics.
+    fn oscillator(&mut self) -> (f32, f32) {
+        let attack = 1. / (self.rate * ATTACK_MS * 0.001);
+        let release = 1. / (self.rate * RELEASE_MS * 0.001);
+        let v = &mut self.synth.voice;
+        v.amp = if v.releasing {
+            (v.amp - release).max(0.)
+        } else {
+            (v.amp + attack).min(1.)
+        };
+        v.hz += (v.target - v.hz) * self.glide;
+        let (mut out, mut ghost) = (0., 0.);
+        let v = self.synth.voice;
+        if v.amp > 0. {
+            out += (TAU * v.phase).sin() * v.amp;
+            ghost += self.ghost(v.phase) * v.amp;
+            self.synth.voice.phase = (v.phase + v.hz / self.rate).fract();
+        }
+        let s = self.synth;
+        if s.old_gain > 0. {
+            let o = s.old;
+            out += (TAU * o.phase).sin() * o.amp * s.old_gain;
+            ghost += self.ghost(o.phase) * o.amp * s.old_gain;
+            let s = &mut self.synth;
+            s.old.phase = (o.phase + o.hz / self.rate).fract();
+            s.old_gain = (s.old_gain - 1. / (self.rate * CROSSFADE_MS * 0.001)).max(0.);
+        }
+        (self.shape(out), ghost)
+    }
+    /// One sample without a sidechain.
+    pub fn process_sample(&mut self, x: [f32; 2], monitor: Monitor) -> [f32; 2] {
+        self.process_with_kick(x, 0., monitor)
+    }
+    /// Finds kicks in the undelayed sidechain and schedules their duck and restart.
+    fn detect_kick(&mut self, side: f32, audition: bool) {
+        let rate = self.rate;
+        let s = self.settings;
+        let k = &mut self.kick;
+        if audition != k.auditioning {
+            k.auditioning = audition;
+            k.slot = 0;
+            k.slot_hits = 0;
+            k.sums = [f32::NAN; AUDITION.len()];
+            k.counts = [0; AUDITION.len()];
+        }
+        let level = side.abs();
+        k.fast += (level - k.fast) * k.fast_coef;
+        k.slow += (level - k.slow) * k.slow_coef;
+        k.hold = k.hold.saturating_sub(1);
+        if !s.kick_lock || k.hold > 0 || k.fast < KICK_FLOOR || k.fast < KICK_RISE * k.slow {
+            return;
+        }
+        k.hold = (rate * KICK_HOLD_MS * 0.001) as usize;
+        let (offset, slot) = if audition {
+            let slot = k.slot;
+            k.slot_hits += 1;
+            if k.slot_hits >= AUDITION_HITS {
+                k.slot_hits = 0;
+                k.slot = (k.slot + 1) % AUDITION.len();
+            }
+            (AUDITION[slot], Some(slot))
+        } else {
+            (s.kick_offset, None)
+        };
+        // The delayed kick leaves the plugin `latency` samples from now.
+        let at = k.clock + self.latency as u64;
+        let shift = (offset * 0.001 * rate).round() as i64;
+        let duck = Pending {
+            at,
+            restart: false,
+            offset,
+            slot,
+        };
+        k.schedule(duck);
+        k.schedule(Pending {
+            at: (at as i64 + shift).max(0) as u64,
+            restart: true,
+            ..duck
+        });
+    }
+    /// Runs the kick events due at this output sample. Returns the duck gain for the sub.
+    fn kick_events(&mut self) -> f32 {
+        let s = self.settings;
+        let clock = self.kick.clock;
+        for i in 0..PENDING {
+            let Some(p) = self.kick.pending[i] else {
+                continue;
+            };
+            if p.at > clock {
+                continue;
+            }
+            self.kick.pending[i] = None;
+            if p.restart {
+                self.synth.kick(&s);
+                self.kick.offset = p.offset;
+            } else {
+                let k = &mut self.kick;
+                k.hits += 1;
+                k.rising = true;
+                k.measure = (self.rate * SUM_MS * 0.001) as usize;
+                k.measure_slot = p.slot;
+                k.energy = [0.; 3];
+            }
+        }
+        let k = &mut self.kick;
+        if k.rising {
+            k.duck += (1. - k.duck) * k.attack;
+            if k.duck > 0.98 {
+                k.rising = false;
+            }
+        } else {
+            k.duck -= k.duck * coefficient(self.rate, s.kick_release / 3.);
+        }
+        if !s.kick_lock {
+            k.duck = 0.;
+        }
+        1. - (1. - db_to_gain(-s.kick_duck)) * k.duck
+    }
+    /// Adds one sample of the delayed kick's and the sub's low band to the sum measurement.
+    fn measure_kick(&mut self, kick: f32, sub: f32) {
+        let k = &mut self.kick;
+        if k.measure == 0 {
+            return;
+        }
+        k.energy[0] += (kick + sub) * (kick + sub);
+        k.energy[1] += kick * kick;
+        k.energy[2] += sub * sub;
+        k.measure -= 1;
+        if k.measure > 0 {
+            return;
+        }
+        let apart = k.energy[1] + k.energy[2];
+        if apart < 1e-9 {
+            return;
+        }
+        k.sum_db = 10. * (k.energy[0] / apart).max(1e-6).log10();
+        if let Some(slot) = k.measure_slot {
+            let n = k.counts[slot] as f32;
+            let old = if n > 0. { k.sums[slot] } else { 0. };
+            k.sums[slot] = (old * n + k.sum_db) / (n + 1.);
+            k.counts[slot] += 1;
+        }
+    }
+    /// One sample with the kick's sidechain (mono) for Kick lock.
+    pub fn process_with_kick(&mut self, x: [f32; 2], kick: f32, monitor: Monitor) -> [f32; 2] {
+        self.detect_kick(kick, monitor.audition);
+        let len = self.kick.delay.len();
+        self.kick.delay[self.kick.delay_at] = kick;
+        self.kick.delay_at = (self.kick.delay_at + 1) % len;
+        let kick_late = self.kick.delay[self.kick.delay_at];
+        let mono = if self.channels == 2 {
+            0.5 * (x[0] + x[1])
+        } else {
+            x[0]
+        };
+        let (synth, settings) = (&mut self.synth, &self.settings);
+        self.tracker.process(mono, |e| synth.event(settings, e));
+        let len = self.delay.len();
+        self.delay[self.delay_at] = x;
+        self.delay_at = (self.delay_at + 1) % len;
+        // The slot after the newest write is the oldest: exactly `latency` samples ago.
+        let y = self.delay[self.delay_at];
+        let s = self.settings;
+        let (l0, h0) = self.crossover[0].process(y[0]);
+        let (l1, h1) = if self.channels == 2 {
+            self.crossover[1].process(y[1])
+        } else {
+            (l0, h0)
+        };
+        let low = 0.5 * (l0 + l1);
+        if std::mem::take(&mut self.synth.fresh) {
+            // A new note: measure its harmonics from its first sample. Until the first
+            // window completes they count as missing.
+            self.meter.reset();
+            self.patch = [0.; GHOST_COUNT];
+        }
+        let v = self.synth.voice;
+        let hz = if v.amp > 0. && !v.releasing { v.hz } else { 0. };
+        if self.meter.push(0.5 * (h0 + h1), hz) && self.meter.hz() > 0. {
+            for (p, db) in self.patch.iter_mut().zip(&self.meter.levels()[1..]) {
+                *p = if *db > -119. { db_to_gain(*db) } else { 0. };
+            }
+        }
+        self.low_env += (low * low - self.low_env) * self.env_coef;
+        let env = self.low_env.sqrt();
+        if !self.synth.voice.releasing {
+            self.synth.note_peak = self.synth.note_peak.max(env);
+        }
+        let follow = if self.synth.note_peak > 1e-6 {
+            (env / self.synth.note_peak).min(1.)
+        } else {
+            1.
+        };
+        let dynamics = s.dynamics * 0.01;
+        let shape = 1. - dynamics + dynamics * follow;
+        self.level += (db_to_gain(s.level) - self.level) * self.smooth;
+        self.keep += (s.keep * 0.01 - self.keep) * self.smooth;
+        self.output += (db_to_gain(s.output) - self.output) * self.smooth;
+        self.bypass += (f32::from(s.bypass) - self.bypass) * self.smooth;
+        let duck = self.kick_events();
+        self.update_fill();
+        let (sub, ghost) = self.oscillator();
+        let sub = sub * self.level * shape * duck;
+        let generated = sub + ghost * self.level * shape * duck;
+        if self.settings.kick_lock {
+            let kick_low = self.kick.low.process(kick_late);
+            self.measure_kick(kick_low, sub);
+        }
+        self.kick.clock += 1;
+        self.low_power += (low * low - self.low_power) * self.meter_coef;
+        self.sub_power += (sub * sub - self.sub_power) * self.meter_coef;
+        self.scope_count += 1;
+        if self.scope_count >= self.scope_stride {
+            self.scope_count = 0;
+            self.scope_low[self.scope_at] = low;
+            self.scope_sub[self.scope_at] = generated;
+            self.scope_at = (self.scope_at + 1) % (2 * SCOPE);
+        }
+        let wet = |l: f32, h: f32| {
+            if monitor.solo {
+                generated
+            } else {
+                h + self.keep * l + generated
+            }
+        };
+        let w = [wet(l0, h0), wet(l1, h1)];
+        let mut out = [0.; 2];
+        for c in 0..self.channels {
+            out[c] = (w[c] * self.output) * (1. - self.bypass) + y[c] * self.bypass;
+        }
+        if monitor.phone {
+            let mut m = if self.channels == 2 {
+                0.5 * (out[0] + out[1])
+            } else {
+                out[0]
+            };
+            for (f, c) in self.phone.iter_mut().zip(&self.phone_coefs) {
+                m = f.process(c, m);
+            }
+            out = [m, if self.channels == 2 { m } else { 0. }];
+        }
+        out
+    }
+    pub fn take_analyzer(&self) -> AnalyzerFrame {
+        let mut f = AnalyzerFrame {
+            latency: self.latency as u32,
+            sample_rate: self.rate,
+            low_db: 10. * self.low_power.max(1e-12).log10() + 3.01,
+            sub_db: 10. * self.sub_power.max(1e-12).log10() + 3.01,
+            scope_ms: (self.scope_stride * SCOPE) as f32 / self.rate * 1000.,
+            ghost_edge: self.ghost_edge(),
+            kick_hits: self.kick.hits,
+            kick_sum_db: self.kick.sum_db,
+            kick_offset: self.kick.offset,
+            audition_sums: self.kick.sums,
+            ..AnalyzerFrame::default()
+        };
+        let sub = self.level.max(1e-6);
+        let rel = |g: f32| {
+            if g > 1e-6 {
+                20. * (g / sub).log10()
+            } else {
+                -120.
+            }
+        };
+        for i in 0..GHOST_COUNT {
+            f.patch_harmonics[i] = rel(self.patch[i]);
+            f.ghost_harmonics[i] = rel(self.fill[i] * sub);
+        }
+        let v = self.synth.voice;
+        if v.amp > 0. && !v.releasing {
+            f.hz = v.hz;
+            f.note = Some(hz_to_midi(v.hz).round().clamp(0., 127.) as u8);
+        }
+        // Trigger on the latest rising zero crossing that still leaves a full window behind it.
+        let n = 2 * SCOPE;
+        let oldest = self.scope_at;
+        let mut start = oldest;
+        for back in 0..SCOPE {
+            let i = (oldest + SCOPE - back) % n;
+            let prev = (i + n - 1) % n;
+            if self.scope_sub[prev] < 0. && self.scope_sub[i] >= 0. {
+                start = i;
+                break;
+            }
+        }
+        for k in 0..SCOPE {
+            let i = (start + k) % n;
+            f.scope_low[k] = self.scope_low[i];
+            f.scope_sub[k] = self.scope_sub[i];
+        }
+        f
+    }
+}
@@ -0,0 +1,144 @@
+//! Host-independent controls. Levels in dB, times in milliseconds, frequencies in Hz.
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
+pub enum Source {
+    /// Pitch and note starts are detected from the incoming bass.
+    #[default]
+    Audio,
+    /// Notes come from MIDI note input; the audio only supplies the band above the split.
+    Midi,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq)]
+#[serde(deny_unknown_fields)]
+pub struct Settings {
+    pub source: Source,
+    /// Peak level of the new sub in dBFS, the same for every note.
+    pub level: f32,
+    /// Crossover frequency: below it the original sub is replaced.
+    pub split: f32,
+    /// 0 % holds a constant level per note; 100 % follows the original low band's shape.
+    pub dynamics: f32,
+    /// Soft saturation of the sine, adding upper harmonics for small speakers.
+    pub drive: f32,
+    /// Ghost harmonics: adds the sub's harmonics 2–10 above `ghost_from`, so small
+    /// speakers hear the note. Only harmonics the patch lacks are filled. 0 is off.
+    #[serde(default)]
+    pub ghost: f32,
+    /// Lowest frequency Ghost harmonics reach down to, in Hz (never below `split`).
+    #[serde(default = "default_ghost_from")]
+    pub ghost_from: f32,
+    pub octave: i32,
+    /// Pitch slide time between overlapping notes.
+    pub glide: f32,
+    /// Start phase in degrees on every note start.
+    pub phase: f32,
+    /// Detection threshold in dBFS for note starts (Audio source).
+    pub gate: f32,
+    /// Amount of the original low band that is kept under the new sub.
+    pub keep: f32,
+    pub output: f32,
+    /// Restart the sine at `phase` on every note, so each note and kick hit lines up the same.
+    pub retrigger: bool,
+    /// Round detected pitch to the nearest semitone.
+    pub snap: bool,
+    pub bypass: bool,
+    /// Kick lock: on each kick in the sidechain, duck the sub and restart its phase.
+    #[serde(default)]
+    pub kick_lock: bool,
+    /// How far the sub dips on each kick, in dB.
+    #[serde(default = "default_kick_duck")]
+    pub kick_duck: f32,
+    /// Time for the sub to come back after a kick, in ms.
+    #[serde(default = "default_kick_release")]
+    pub kick_release: f32,
+    /// When the sub restarts against the kick's start, in ms. Negative: before the kick.
+    #[serde(default)]
+    pub kick_offset: f32,
+}
+const GHOST_FROM: f32 = 300.;
+const KICK_DUCK: f32 = 6.;
+const KICK_RELEASE: f32 = 80.;
+/// Range of the kick offset, in ms either side of the kick.
+pub const KICK_OFFSET_MAX: f32 = 30.;
+fn default_kick_duck() -> f32 {
+    KICK_DUCK
+}
+fn default_kick_release() -> f32 {
+    KICK_RELEASE
+}
+fn default_ghost_from() -> f32 {
+    GHOST_FROM
+}
+impl Default for Settings {
+    fn default() -> Self {
+        Self {
+            source: Source::Audio,
+            level: -9.,
+            split: 90.,
+            dynamics: 0.,
+            drive: 0.,
+            ghost: 0.,
+            ghost_from: GHOST_FROM,
+            octave: 0,
+            glide: 0.,
+            phase: 0.,
+            gate: -42.,
+            keep: 0.,
+            output: 0.,
+            retrigger: true,
+            snap: true,
+            bypass: false,
+            kick_lock: false,
+            kick_duck: KICK_DUCK,
+            kick_release: KICK_RELEASE,
+            kick_offset: 0.,
+        }
+    }
+}
+impl Settings {
+    pub fn validate(&self) -> Result<(), &'static str> {
+        let finite = [
+            self.level,
+            self.split,
+            self.dynamics,
+            self.drive,
+            self.ghost,
+            self.ghost_from,
+            self.glide,
+            self.phase,
+            self.gate,
+            self.keep,
+            self.output,
+            self.kick_duck,
+            self.kick_release,
+            self.kick_offset,
+        ]
+        .iter()
+        .all(|v| v.is_finite());
+        if !finite {
+            return Err("non-finite setting");
+        }
+        let ok = (-30.0..=0.).contains(&self.level)
+            && (40.0..=200.).contains(&self.split)
+            && (0.0..=100.).contains(&self.dynamics)
+            && (0.0..=100.).contains(&self.drive)
+            && (0.0..=100.).contains(&self.ghost)
+            && (150.0..=600.).contains(&self.ghost_from)
+            && (-2..=1).contains(&self.octave)
+            && (0.0..=200.).contains(&self.glide)
+            && (0.0..=360.).contains(&self.phase)
+            && (-60.0..=-20.).contains(&self.gate)
+            && (0.0..=100.).contains(&self.keep)
+            && (-12.0..=12.).contains(&self.output)
+            && (0.0..=24.).contains(&self.kick_duck)
+            && (10.0..=300.).contains(&self.kick_release)
+            && (-KICK_OFFSET_MAX..=KICK_OFFSET_MAX).contains(&self.kick_offset);
+        if ok {
+            Ok(())
+        } else {
+            Err("setting out of range")
+        }
+    }
+}
@@ -0,0 +1,490 @@
+use anvil_core::{Engine, Monitor, Settings, Source};
+use common_dsp::Saw;
+
+const RATE: f32 = 48000.;
+
+/// Saw notes (start s, end s, Hz, peak) with 1 ms fades.
+fn notes(list: &[(f32, f32, f32, f32)], total: f32) -> Vec<f32> {
+    let mut x = vec![0.; (total * RATE) as usize];
+    for &(a, b, hz, amp) in list {
+        let (a, b) = ((a * RATE) as usize, (b * RATE) as usize);
+        let mut saw = Saw::new(RATE, hz);
+        let fade = (0.001 * RATE) as usize;
+        for i in a..b.min(x.len()) {
+            let edge = ((i - a).min(b - 1 - i) as f32 / fade as f32).min(1.);
+            x[i] += saw.sample() * amp * edge;
+        }
+    }
+    x
+}
+fn render(e: &mut Engine, x: &[f32], solo: bool) -> Vec<f32> {
+    x.iter()
+        .map(|&s| {
+            e.process_sample(
+                [s, s],
+                Monitor {
+                    solo,
+                    ..Monitor::default()
+                },
+            )[0]
+        })
+        .collect()
+}
+fn rms(x: &[f32]) -> f32 {
+    (x.iter().map(|v| v * v).sum::<f32>() / x.len() as f32).sqrt()
+}
+fn db(x: f32) -> f32 {
+    20. * x.max(1e-9).log10()
+}
+/// Frequency from interpolated rising zero crossings.
+fn frequency(x: &[f32]) -> f32 {
+    let mut first = None;
+    let mut last = 0.;
+    let mut count = 0;
+    for i in 1..x.len() {
+        if x[i - 1] < 0. && x[i] >= 0. {
+            let t = (i - 1) as f32 + x[i - 1] / (x[i - 1] - x[i]);
+            if first.is_none() {
+                first = Some(t);
+            } else {
+                count += 1;
+            }
+            last = t;
+        }
+    }
+    count as f32 * RATE / (last - first.unwrap())
+}
+fn seconds(t: f32) -> usize {
+    (t * RATE) as usize
+}
+fn engine(s: Settings) -> (Engine, usize) {
+    let mut e = Engine::new(RATE, 2).unwrap();
+    e.set_settings(s).unwrap();
+    let l = e.latency_samples() as usize;
+    (e, l)
+}
+
+#[test]
+fn every_note_gets_the_same_sub_level() {
+    let (mut e, l) = engine(Settings::default());
+    let x = notes(&[(0.1, 0.6, 55., 0.5), (0.8, 1.3, 55., 0.1)], 1.6);
+    let y = render(&mut e, &x, true);
+    let loud = rms(&y[seconds(0.3) + l..seconds(0.5) + l]);
+    let quiet = rms(&y[seconds(1.0) + l..seconds(1.2) + l]);
+    assert!(
+        (db(loud) - db(quiet)).abs() < 0.5,
+        "{} vs {}",
+        db(loud),
+        db(quiet)
+    );
+    // −9 dBFS peak sine.
+    assert!((db(loud * 2f32.sqrt()) + 9.).abs() < 0.5, "{}", db(loud));
+}
+
+#[test]
+fn sub_follows_the_detected_pitch_and_octave() {
+    for (octave, expect) in [(0, 43.654), (-1, 21.827)] {
+        let (mut e, l) = engine(Settings {
+            octave,
+            ..Settings::default()
+        });
+        let x = notes(&[(0.1, 1.1, 43.65, 0.5)], 1.3);
+        let y = render(&mut e, &x, true);
+        let f = frequency(&y[seconds(0.3) + l..seconds(1.0) + l]);
+        assert!((f / expect - 1.).abs() < 0.005, "octave {octave}: {f}");
+    }
+}
+
+#[test]
+fn a_pitch_change_without_a_gap_is_a_new_note() {
+    let (mut e, l) = engine(Settings::default());
+    let x = notes(&[(0.1, 0.6, 55., 0.5), (0.6, 1.1, 82.41, 0.5)], 1.3);
+    let y = render(&mut e, &x, true);
+    let f = frequency(&y[seconds(0.75) + l..seconds(1.05) + l]);
+    assert!((f / 82.41 - 1.).abs() < 0.005, "{f}");
+}
+
+#[test]
+fn every_note_restarts_at_the_start_phase() {
+    let (mut e, l) = engine(Settings {
+        phase: 90.,
+        ..Settings::default()
+    });
+    let x = notes(&[(0.1, 0.4, 55., 0.5), (0.6, 0.9, 55., 0.3)], 1.1);
+    let y = render(&mut e, &x, true);
+    let period = (RATE / 55.) as usize;
+    let a = &y[seconds(0.1) + l..seconds(0.1) + l + 2 * period];
+    let b = &y[seconds(0.6) + l..seconds(0.6) + l + 2 * period];
+    let peak = y.iter().fold(0f32, |m, v| m.max(v.abs()));
+    let worst = a.iter().zip(b).fold(0f32, |m, (p, q)| m.max((p - q).abs()));
+    assert!(worst < 0.1 * peak, "{worst} of {peak}");
+    // Fit the phase over the second period, after the 2 ms attack.
+    let w = std::f32::consts::TAU * 55. / RATE;
+    let (mut s, mut c) = (0., 0.);
+    for (k, v) in a.iter().enumerate().skip(period) {
+        s += v * (w * k as f32).sin();
+        c += v * (w * k as f32).cos();
+    }
+    let phase = c.atan2(s).to_degrees();
+    assert!((phase - 90.).abs() < 20., "{phase}");
+}
+
+#[test]
+fn midi_notes_set_pitch_and_are_delayed_by_the_latency() {
+    let (mut e, l) = engine(Settings {
+        source: Source::Midi,
+        ..Settings::default()
+    });
+    let mut y = Vec::new();
+    for i in 0..seconds(0.8) {
+        if i == 1000 {
+            e.note_on(33);
+        }
+        if i == seconds(0.6) {
+            e.note_off(33);
+        }
+        y.push(
+            e.process_sample(
+                [0.; 2],
+                Monitor {
+                    solo: true,
+                    ..Monitor::default()
+                },
+            )[0],
+        );
+    }
+    assert!(y[..1000 + l].iter().all(|v| *v == 0.));
+    assert!(y[1000 + l + 50].abs() > 0.);
+    let f = frequency(&y[seconds(0.2) + l..seconds(0.5)]);
+    assert!((f / 55. - 1.).abs() < 0.001, "{f}");
+    assert!(y[seconds(0.6) + l + seconds(0.05)..]
+        .iter()
+        .all(|v| v.abs() < 1e-6));
+}
+
+#[test]
+fn note_changes_do_not_click() {
+    let (mut e, _) = engine(Settings::default());
+    let x = notes(
+        &[
+            (0.1, 0.4, 55., 0.5),
+            (0.4, 0.7, 73.42, 0.5),
+            (0.7, 1.0, 41.2, 0.5),
+        ],
+        1.3,
+    );
+    let y = render(&mut e, &x, true);
+    let step = y.windows(2).fold(0f32, |m, w| m.max((w[1] - w[0]).abs()));
+    // A −9 dBFS sine at 73 Hz moves at most 0.0034 per sample.
+    assert!(step < 0.012, "{step}");
+}
+
+#[test]
+fn keep_without_notes_is_an_allpass() {
+    let (mut e, _) = engine(Settings {
+        source: Source::Midi,
+        keep: 100.,
+        ..Settings::default()
+    });
+    for hz in [40., 90., 300., 3000.] {
+        e.reset();
+        let x: Vec<f32> = (0..seconds(1.))
+            .map(|i| 0.3 * (std::f32::consts::TAU * hz * i as f32 / RATE).sin())
+            .collect();
+        let y = render(&mut e, &x, false);
+        let d = db(rms(&y[seconds(0.5)..])) - db(rms(&x[seconds(0.5)..]));
+        assert!(d.abs() < 0.1, "{hz}: {d}");
+    }
+}
+
+#[test]
+fn split_removes_original_sub_and_keeps_mids() {
+    let (mut e, l) = engine(Settings {
+        source: Source::Midi,
+        ..Settings::default()
+    });
+    let x: Vec<f32> = (0..seconds(1.))
+        .map(|i| 0.3 * (std::f32::consts::TAU * 40. * i as f32 / RATE).sin())
+        .collect();
+    let y = render(&mut e, &x, false);
+    assert!(db(rms(&y[seconds(0.5) + l..])) < db(0.3) - 18.);
+}
+
+#[test]
+fn settings_are_validated_and_serialise() {
+    let mut e = Engine::new(RATE, 1).unwrap();
+    assert!(e
+        .set_settings(Settings {
+            level: 3.,
+            ..Settings::default()
+        })
+        .is_err());
+    let json = serde_json::to_string(&Settings::default()).unwrap();
+    assert_eq!(
+        serde_json::from_str::<Settings>(&json).unwrap(),
+        Settings::default()
+    );
+    assert!(Engine::new(1000., 2).is_err());
+    assert!(Engine::new(48000., 3).is_err());
+}
+
+/// Peak amplitude of the component at `hz`, over a window of whole cycles.
+fn amplitude(x: &[f32], hz: f32) -> f32 {
+    let w = std::f32::consts::TAU * hz / RATE;
+    let (re, im) = x.iter().enumerate().fold((0., 0.), |(re, im), (n, v)| {
+        (re + v * (w * n as f32).cos(), im - v * (w * n as f32).sin())
+    });
+    2. * (re * re + im * im).sqrt() / x.len() as f32
+}
+/// Sines (Hz, peak) from 0.1 s to `total` − 0.1 s, with 1 ms fades.
+fn tones(list: &[(f32, f32)], total: f32) -> Vec<f32> {
+    let n = (total * RATE) as usize;
+    let (a, b, fade) = (seconds(0.1), n - seconds(0.1), seconds(0.001));
+    (0..n)
+        .map(|i| {
+            if i < a || i >= b {
+                return 0.;
+            }
+            let edge = ((i - a).min(b - 1 - i) as f32 / fade as f32).min(1.);
+            let t = (i - a) as f32 / RATE;
+            edge * list
+                .iter()
+                .map(|&(hz, amp)| amp * (std::f32::consts::TAU * hz * t).sin())
+                .sum::<f32>()
+        })
+        .collect()
+}
+fn ghost(amount: f32) -> Settings {
+    Settings {
+        ghost: amount,
+        ghost_from: 300.,
+        ..Settings::default()
+    }
+}
+
+#[test]
+fn ghost_fills_the_harmonics_a_clean_sub_lacks() {
+    let (mut e, l) = engine(ghost(100.));
+    let x = tones(&[(55., 0.5)], 1.);
+    let y = render(&mut e, &x, true);
+    // 0.2 s holds exactly 11 cycles of 55 Hz.
+    let w = &y[seconds(0.5) + l..seconds(0.7) + l];
+    let sub = amplitude(w, 55.);
+    assert!((db(sub) + 9.).abs() < 0.5, "{}", db(sub));
+    for k in 2..=5 {
+        // Below Ghost from: nothing added, so the sub stays a clean sine there.
+        let a = amplitude(w, 55. * k as f32);
+        assert!(db(a / sub) < -60., "harmonic {k}: {}", db(a / sub));
+    }
+    for k in 8..=10 {
+        let a = amplitude(w, 55. * k as f32);
+        let expect = 20. * (2. / k as f32).log10();
+        assert!(
+            (db(a / sub) - expect).abs() < 1.,
+            "harmonic {k}: {}",
+            db(a / sub)
+        );
+    }
+    // Harmonic 6 (330 Hz) sits in the fade above 300 Hz: present, but quieter.
+    let six = db(amplitude(w, 330.) / sub);
+    assert!(six < 20. * (2f32 / 6.).log10() - 3. && six > -40., "{six}");
+}
+
+#[test]
+fn ghost_leaves_harmonics_the_patch_already_has() {
+    let (mut e, l) = engine(ghost(100.));
+    // The patch carries its 8th harmonic (440 Hz) louder than Ghost would add it.
+    let x = tones(&[(55., 0.5), (440., 0.2)], 1.);
+    let y = render(&mut e, &x, false);
+    let w = &y[seconds(0.5) + l..seconds(0.7) + l];
+    let eighth = amplitude(w, 440.);
+    assert!((db(eighth) - db(0.2)).abs() < 0.5, "{}", db(eighth));
+    // The 9th is missing from the patch, so Ghost fills it.
+    let ninth = amplitude(w, 495.) / amplitude(w, 55.);
+    assert!(
+        (db(ninth) - 20. * (2f32 / 9.).log10()).abs() < 1.,
+        "{}",
+        db(ninth)
+    );
+}
+
+#[test]
+fn ghost_off_adds_nothing_and_phone_listen_drops_the_sub() {
+    let x = tones(&[(55., 0.5)], 1.);
+    let (mut e, l) = engine(ghost(0.));
+    let y = render(&mut e, &x, true);
+    let w = &y[seconds(0.5) + l..seconds(0.7) + l];
+    for k in 2..=10 {
+        assert!(amplitude(w, 55. * k as f32) < 1e-4, "harmonic {k}");
+    }
+    let phone = |amount: f32| {
+        let (mut e, l) = engine(ghost(amount));
+        let y: Vec<f32> = x
+            .iter()
+            .map(|&s| {
+                e.process_sample(
+                    [s, s],
+                    Monitor {
+                        solo: true,
+                        phone: true,
+                        audition: false,
+                    },
+                )[0]
+            })
+            .collect();
+        rms(&y[seconds(0.5) + l..seconds(0.7) + l])
+    };
+    // A clean 55 Hz sub all but vanishes on a phone; Ghost makes the note heard.
+    let (plain, ghosted) = (phone(0.), phone(100.));
+    assert!(db(plain) < -50., "{}", db(plain));
+    assert!(
+        db(ghosted) - db(plain) > 25.,
+        "{} vs {}",
+        db(ghosted),
+        db(plain)
+    );
+}
+
+/// A kick-like burst: a 55 Hz sine starting at phase 0 with a 60 ms decay, at each time.
+fn kicks(times: &[f32], total: f32) -> Vec<f32> {
+    let mut k = vec![0.; seconds(total)];
+    for &t in times {
+        for i in 0..seconds(0.2) {
+            let n = seconds(t) + i;
+            if n < k.len() {
+                let t = i as f32 / RATE;
+                k[n] += 0.8 * (std::f32::consts::TAU * 55. * t).sin() * (-t / 0.06).exp();
+            }
+        }
+    }
+    k
+}
+fn render_kick(e: &mut Engine, x: &[f32], k: &[f32], monitor: Monitor) -> Vec<f32> {
+    x.iter()
+        .zip(k)
+        .map(|(&s, &k)| e.process_with_kick([s, s], k, monitor)[0])
+        .collect()
+}
+/// Normalised correlation of `y[a..b]` with a sine of `hz` at phase 0 at sample `zero`.
+fn sine_match(y: &[f32], a: usize, b: usize, hz: f32, zero: f32) -> f32 {
+    let w = std::f32::consts::TAU * hz / RATE;
+    let (mut xy, mut xx, mut yy) = (0., 0., 0.);
+    for (i, &v) in y.iter().enumerate().take(b).skip(a) {
+        let r = (w * (i as f32 - zero)).sin();
+        xy += v * r;
+        xx += r * r;
+        yy += v * v;
+    }
+    xy / (xx * yy).sqrt()
+}
+const SOLO: Monitor = Monitor {
+    solo: true,
+    phone: false,
+    audition: false,
+};
+fn kick_lock(offset: f32) -> Settings {
+    Settings {
+        kick_lock: true,
+        kick_offset: offset,
+        ..Settings::default()
+    }
+}
+
+#[test]
+fn a_kick_restarts_the_sub_at_the_start_phase_and_ducks_it() {
+    // A bass note that started off the kick: before the hit, the sub runs at its own phase.
+    let x = tones(&[(55., 0.5)], 1.4);
+    let k = kicks(&[0.613], 1.4);
+    let (mut e, l) = engine(kick_lock(0.));
+    let y = render_kick(&mut e, &x, &k, SOLO);
+    let hit = seconds(0.613) + l;
+    let after = sine_match(
+        &y,
+        hit + seconds(0.004),
+        hit + seconds(0.04),
+        55.,
+        hit as f32,
+    );
+    assert!(after > 0.99, "{after}");
+    let before = rms(&y[hit - seconds(0.1)..hit - seconds(0.01)]);
+    let ducked = rms(&y[hit + seconds(0.004)..hit + seconds(0.022)]);
+    let back = rms(&y[hit + seconds(0.4)..hit + seconds(0.5)]);
+    assert!(
+        db(before) - db(ducked) > 2.,
+        "{} vs {}",
+        db(before),
+        db(ducked)
+    );
+    assert!(
+        (db(back) - db(before)).abs() < 0.3,
+        "{} vs {}",
+        db(back),
+        db(before)
+    );
+    assert_eq!(e.take_analyzer().kick_hits, 1);
+}
+
+#[test]
+fn the_offset_restarts_the_sub_before_or_after_the_kick() {
+    let x = tones(&[(55., 0.5)], 1.2);
+    let k = kicks(&[0.613], 1.2);
+    for offset in [-10., 7.] {
+        // No duck: only the phase is checked here.
+        let (mut e, l) = engine(Settings {
+            kick_duck: 0.,
+            ..kick_lock(offset)
+        });
+        let y = render_kick(&mut e, &x, &k, SOLO);
+        let start = (seconds(0.613) + l) as f32 + offset * 0.001 * RATE;
+        let a = start as usize + seconds(0.004);
+        let m = sine_match(&y, a, a + seconds(0.03), 55., start);
+        assert!(m > 0.99, "{offset}: {m}");
+    }
+}
+
+#[test]
+fn without_kick_lock_the_sidechain_changes_nothing() {
+    let x = tones(&[(55., 0.5)], 1.);
+    let k = kicks(&[0.3, 0.6], 1.);
+    let (mut a, _) = engine(Settings::default());
+    let (mut b, _) = engine(Settings::default());
+    let with = render_kick(&mut a, &x, &k, SOLO);
+    let without = render(&mut b, &x, true);
+    assert_eq!(with, without);
+}
+
+#[test]
+fn the_audition_finds_where_kick_and_sub_sum() {
+    use anvil_core::{AUDITION, AUDITION_HITS};
+    let hits = AUDITION.len() * AUDITION_HITS as usize;
+    let total = 0.5 + hits as f32 * 0.2 + 0.4;
+    let x = tones(&[(55., 0.5)], total);
+    let times: Vec<f32> = (0..hits).map(|i| 0.5 + i as f32 * 0.2).collect();
+    let k = kicks(&times, total);
+    let (mut e, _) = engine(kick_lock(0.));
+    let monitor = Monitor {
+        audition: true,
+        ..SOLO
+    };
+    render_kick(&mut e, &x, &k, monitor);
+    let f = e.take_analyzer();
+    assert_eq!(f.kick_hits as usize, hits);
+    let sums = f.audition_sums;
+    assert!(sums.iter().all(|v| v.is_finite()), "{sums:?}");
+    // The kick is a 55 Hz burst at phase 0, like the sub: they sum fully at 0 ms and
+    // cancel half a period (9 ms) away.
+    let best = (0..sums.len())
+        .max_by(|&a, &b| sums[a].total_cmp(&sums[b]))
+        .unwrap();
+    assert_eq!(AUDITION[best], 0., "{sums:?}");
+    let zero = sums[6];
+    assert!(zero > 2., "{zero}");
+    for i in [4, 8] {
+        assert!(
+            zero - sums[i] > 4.,
+            "{} ms: {} vs {zero}",
+            AUDITION[i],
+            sums[i]
+        );
+    }
+}
@@ -0,0 +1,83 @@
+use anvil_core::{Engine, Monitor, 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_and_analysis_do_not_allocate_or_free() {
+    let mut engine = Engine::new(48000., 2).unwrap();
+    let mut settings = Settings {
+        ghost: 80.,
+        kick_lock: true,
+        kick_offset: -12.,
+        ..Settings::default()
+    };
+    engine.set_settings(settings).unwrap();
+    CHECK.with(|v| v.set(true));
+    for i in 0..96000 {
+        if i % 4800 == 0 {
+            settings.split = 60. + (i % 100) as f32;
+            settings.source = if i > 48000 {
+                Source::Midi
+            } else {
+                Source::Audio
+            };
+            settings.octave = -((i / 4800) % 2);
+            engine.set_settings(settings).unwrap();
+            engine.note_on(30 + (i / 4800 % 12) as u8);
+        }
+        if i % 4800 == 2400 {
+            engine.note_off(30 + (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.
+        };
+        let kick = if i % 12000 < 400 { 0.8 } else { 0. };
+        std::hint::black_box(engine.process_with_kick(
+            [x, x],
+            kick,
+            Monitor {
+                solo: i % 3 == 0,
+                phone: i % 5 == 0,
+                audition: i > 30000,
+            },
+        ));
+        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);
+}
@@ -0,0 +1,25 @@
+[package]
+name = "anvil"
+version = "0.3.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" }
+anvil-core = { path = "../core" }
+anvil-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"
@@ -0,0 +1,236 @@
+//! CLAP audio effect. All DSP state is owned by the processing thread.
+mod params;
+use anvil_core::{AnalyzerFrame, Engine, Monitor};
+use crossbeam_queue::ArrayQueue;
+use nih_plug::prelude::*;
+use nih_plug_egui::{create_egui_editor, egui};
+use params::AnvilParams;
+use std::sync::{
+    atomic::{AtomicBool, Ordering},
+    Arc,
+};
+
+struct Shared {
+    analyzer: ArrayQueue<AnalyzerFrame>,
+    solo: AtomicBool,
+    phone: AtomicBool,
+    audition: AtomicBool,
+}
+struct EditorData {
+    ui: anvil_ui::State,
+    gestures: [bool; 14],
+}
+pub struct Anvil {
+    params: Arc<AnvilParams>,
+    shared: Arc<Shared>,
+    engine: Option<Engine>,
+    publish_count: usize,
+    publish_interval: usize,
+}
+impl Default for Anvil {
+    fn default() -> Self {
+        Self {
+            params: Arc::new(AnvilParams::default()),
+            shared: Arc::new(Shared {
+                analyzer: ArrayQueue::new(2),
+                solo: AtomicBool::new(false),
+                phone: AtomicBool::new(false),
+                audition: AtomicBool::new(false),
+            }),
+            engine: None,
+            publish_count: 0,
+            publish_interval: 1600,
+        }
+    }
+}
+impl Plugin for Anvil {
+    const NAME: &'static str = "Anvil";
+    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),
+            aux_input_ports: &[new_nonzero_u32(2)],
+            names: PortNames {
+                aux_inputs: &["Kick"],
+                ..PortNames::const_default()
+            },
+            ..AudioIOLayout::const_default()
+        },
+        AudioIOLayout {
+            main_input_channels: NonZeroU32::new(1),
+            main_output_channels: NonZeroU32::new(1),
+            aux_input_ports: &[new_nonzero_u32(1)],
+            names: PortNames {
+                aux_inputs: &["Kick"],
+                ..PortNames::const_default()
+            },
+            ..AudioIOLayout::const_default()
+        },
+    ];
+    const MIDI_INPUT: MidiConfig = MidiConfig::Basic;
+    const SAMPLE_ACCURATE_AUTOMATION: bool = true;
+    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: anvil_ui::State::default(),
+                gestures: [false; 14],
+            },
+            |ctx, data| {
+                data.ui.solo = false;
+                data.ui.phone = false;
+                data.ui.audition = false;
+                anvil_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("anvil-editor")
+                    .min_size(egui::vec2(
+                        anvil_ui::WIDTH as f32 - 80.,
+                        anvil_ui::HEIGHT as f32 - 40.,
+                    ))
+                    .show(ctx, &params.editor, |ui| {
+                        anvil_ui::show(ui, &mut edited, &mut data.ui)
+                    });
+                params.apply(
+                    setter,
+                    &before,
+                    &edited,
+                    data.ui.gesture_active,
+                    &mut data.gestures,
+                );
+                // Solo and phone listen are monitors only: never saved and never left on
+                // after the editor closes.
+                shared.solo.store(data.ui.solo, Ordering::Release);
+                shared.phone.store(data.ui.phone, Ordering::Release);
+                shared.audition.store(data.ui.audition, Ordering::Release);
+                if data.ui.analyzer.note.is_some() {
+                    ctx.request_repaint();
+                }
+            },
+        )
+    }
+    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.publish_interval = (config.sample_rate / 30.) as usize;
+        self.engine = Some(engine);
+        self.shared.solo.store(false, Ordering::Release);
+        self.shared.phone.store(false, Ordering::Release);
+        self.shared.audition.store(false, Ordering::Release);
+        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,
+        aux: &mut AuxiliaryBuffers,
+        context: &mut impl ProcessContext<Self>,
+    ) -> ProcessStatus {
+        let Some(engine) = self.engine.as_mut() else {
+            return ProcessStatus::Normal;
+        };
+        let _ = engine.set_settings(self.params.settings());
+        let open = self.params.editor.is_open();
+        let monitor = Monitor {
+            solo: self.shared.solo.load(Ordering::Acquire) && open,
+            phone: self.shared.phone.load(Ordering::Acquire) && open,
+            audition: self.shared.audition.load(Ordering::Acquire) && open,
+        };
+        // A host that does not connect the sidechain still passes a buffer; treat a
+        // missing one as silence.
+        let side = aux.inputs.first().map(|b| b.as_slice_immutable());
+        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 kick = side.map_or(0., |side| {
+                let n = side.len().min(2);
+                side[..n]
+                    .iter()
+                    .map(|c| c.get(index).copied().unwrap_or(0.))
+                    .sum::<f32>()
+                    / n.max(1) as f32
+            });
+            let out = engine.process_with_kick(x, kick, monitor);
+            for (c, value) in sample.into_iter().enumerate() {
+                *value = out[c];
+            }
+            self.publish_count += 1;
+            if self.publish_count >= self.publish_interval {
+                self.shared.analyzer.force_push(engine.take_analyzer());
+                self.publish_count = 0;
+            }
+        }
+        // The lookahead delay and the sub release must drain after input stops.
+        ProcessStatus::KeepAlive
+    }
+}
+impl ClapPlugin for Anvil {
+    const CLAP_ID: &'static str = "io.narl.bass-foundry.anvil";
+    const CLAP_DESCRIPTION: Option<&'static str> =
+        Some("Replace the sub with a clean sine at one level and phase for every note");
+    const CLAP_MANUAL_URL: Option<&'static str> = None;
+    const CLAP_SUPPORT_URL: Option<&'static str> = None;
+    const CLAP_FEATURES: &'static [ClapFeature] = &[
+        ClapFeature::AudioEffect,
+        ClapFeature::Stereo,
+        ClapFeature::Mono,
+    ];
+}
+nih_export_clap!(Anvil);
@@ -0,0 +1,242 @@
+use anvil_core::{Settings, Source, KICK_OFFSET_MAX};
+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,
+}
+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)
+}
+#[derive(Params)]
+pub struct AnvilParams {
+    #[persist = "editor"]
+    pub editor: Arc<EguiState>,
+    #[id = "source"]
+    pub source: EnumParam<SourceParam>,
+    #[id = "level"]
+    pub level: FloatParam,
+    #[id = "split"]
+    pub split: FloatParam,
+    #[id = "dynamics"]
+    pub dynamics: FloatParam,
+    #[id = "drive"]
+    pub drive: FloatParam,
+    #[id = "ghost"]
+    pub ghost: FloatParam,
+    #[id = "ghost_from"]
+    pub ghost_from: FloatParam,
+    #[id = "octave"]
+    pub octave: IntParam,
+    #[id = "glide"]
+    pub glide: FloatParam,
+    #[id = "phase"]
+    pub phase: FloatParam,
+    #[id = "gate"]
+    pub gate: FloatParam,
+    #[id = "keep"]
+    pub keep: FloatParam,
+    #[id = "output"]
+    pub output: FloatParam,
+    #[id = "retrigger"]
+    pub retrigger: BoolParam,
+    #[id = "snap"]
+    pub snap: BoolParam,
+    #[id = "bypass"]
+    pub bypass: BoolParam,
+    #[id = "kick_lock"]
+    pub kick_lock: BoolParam,
+    #[id = "kick_duck"]
+    pub kick_duck: FloatParam,
+    #[id = "kick_release"]
+    pub kick_release: FloatParam,
+    #[id = "kick_offset"]
+    pub kick_offset: FloatParam,
+}
+impl Default for AnvilParams {
+    fn default() -> Self {
+        let d = Settings::default();
+        Self {
+            editor: EguiState::from_size(anvil_ui::WIDTH, anvil_ui::HEIGHT),
+            source: EnumParam::new("Pitch source", SourceParam::Audio),
+            level: linear("Sub level", d.level, -30., 0., " dBFS"),
+            split: FloatParam::new(
+                "Split",
+                d.split,
+                FloatRange::Skewed {
+                    min: 40.,
+                    max: 200.,
+                    factor: FloatRange::skew_factor(-1.),
+                },
+            )
+            .with_unit(" Hz"),
+            dynamics: linear("Dynamics", d.dynamics, 0., 100., " %"),
+            drive: linear("Drive", d.drive, 0., 100., " %"),
+            ghost: linear("Ghost", d.ghost, 0., 100., " %"),
+            ghost_from: FloatParam::new(
+                "Ghost from",
+                d.ghost_from,
+                FloatRange::Skewed {
+                    min: 150.,
+                    max: 600.,
+                    factor: FloatRange::skew_factor(-1.),
+                },
+            )
+            .with_unit(" Hz"),
+            octave: IntParam::new("Octave", d.octave, IntRange::Linear { min: -2, max: 1 }),
+            glide: linear("Glide", d.glide, 0., 200., " ms"),
+            phase: linear("Phase", d.phase, 0., 360., "°"),
+            gate: linear("Gate", d.gate, -60., -20., " dB"),
+            keep: linear("Keep", d.keep, 0., 100., " %"),
+            output: linear("Output", d.output, -12., 12., " dB"),
+            retrigger: BoolParam::new("Retrigger", d.retrigger),
+            snap: BoolParam::new("Snap to semitone", d.snap),
+            bypass: BoolParam::new("Bypass", false).make_bypass(),
+            kick_lock: BoolParam::new("Kick lock", d.kick_lock),
+            kick_duck: linear("Kick duck", d.kick_duck, 0., 24., " dB"),
+            kick_release: linear("Kick release", d.kick_release, 10., 300., " ms"),
+            kick_offset: linear(
+                "Kick offset",
+                d.kick_offset,
+                -KICK_OFFSET_MAX,
+                KICK_OFFSET_MAX,
+                " ms",
+            ),
+        }
+    }
+}
+impl AnvilParams {
+    pub fn settings(&self) -> Settings {
+        Settings {
+            source: match self.source.value() {
+                SourceParam::Audio => Source::Audio,
+                SourceParam::Midi => Source::Midi,
+            },
+            level: self.level.value(),
+            split: self.split.value(),
+            dynamics: self.dynamics.value(),
+            drive: self.drive.value(),
+            ghost: self.ghost.value(),
+            ghost_from: self.ghost_from.value(),
+            octave: self.octave.value(),
+            glide: self.glide.value(),
+            phase: self.phase.value(),
+            gate: self.gate.value(),
+            keep: self.keep.value(),
+            output: self.output.value(),
+            retrigger: self.retrigger.value(),
+            snap: self.snap.value(),
+            bypass: self.bypass.value(),
+            kick_lock: self.kick_lock.value(),
+            kick_duck: self.kick_duck.value(),
+            kick_release: self.kick_release.value(),
+            kick_offset: self.kick_offset.value(),
+        }
+    }
+    /// 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; 14],
+    ) {
+        let floats: [(&FloatParam, f32, f32); 13] = [
+            (&self.level, old.level, new.level),
+            (&self.split, old.split, new.split),
+            (&self.dynamics, old.dynamics, new.dynamics),
+            (&self.drive, old.drive, new.drive),
+            (&self.glide, old.glide, new.glide),
+            (&self.phase, old.phase, new.phase),
+            (&self.gate, old.gate, new.gate),
+            (&self.keep, old.keep, new.keep),
+            (&self.ghost, old.ghost, new.ghost),
+            (&self.ghost_from, old.ghost_from, new.ghost_from),
+            (&self.kick_duck, old.kick_duck, new.kick_duck),
+            (&self.kick_release, old.kick_release, new.kick_release),
+            (&self.kick_offset, old.kick_offset, new.kick_offset),
+        ];
+        let mut continuous = |i: usize, changed: bool, set: &dyn Fn()| {
+            if changed {
+                if !open[i] {
+                    open[i] = true;
+                    set_begin(setter, self, i);
+                }
+                set();
+            }
+            if !dragging && open[i] {
+                set_end(setter, self, i);
+                open[i] = false;
+            }
+        };
+        for (i, (p, a, b)) in floats.into_iter().enumerate() {
+            continuous(i, a != b, &|| setter.set_parameter(p, b));
+        }
+        continuous(13, old.output != new.output, &|| {
+            setter.set_parameter(&self.output, new.output)
+        });
+        let once = |changed: bool, f: &dyn Fn()| {
+            if changed {
+                f();
+            }
+        };
+        once(new.octave != old.octave, &|| {
+            setter.begin_set_parameter(&self.octave);
+            setter.set_parameter(&self.octave, new.octave);
+            setter.end_set_parameter(&self.octave);
+        });
+        for (p, a, b) in [
+            (&self.retrigger, old.retrigger, new.retrigger),
+            (&self.snap, old.snap, new.snap),
+            (&self.bypass, old.bypass, new.bypass),
+            (&self.kick_lock, old.kick_lock, new.kick_lock),
+        ] {
+            once(a != b, &|| {
+                setter.begin_set_parameter(p);
+                setter.set_parameter(p, b);
+                setter.end_set_parameter(p);
+            });
+        }
+        once(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);
+        });
+    }
+    fn continuous(&self, i: usize) -> &FloatParam {
+        [
+            &self.level,
+            &self.split,
+            &self.dynamics,
+            &self.drive,
+            &self.glide,
+            &self.phase,
+            &self.gate,
+            &self.keep,
+            &self.ghost,
+            &self.ghost_from,
+            &self.kick_duck,
+            &self.kick_release,
+            &self.kick_offset,
+            &self.output,
+        ][i]
+    }
+}
+fn set_begin(setter: &ParamSetter, p: &AnvilParams, i: usize) {
+    setter.begin_set_parameter(p.continuous(i));
+}
+fn set_end(setter: &ParamSetter, p: &AnvilParams, i: usize) {
+    setter.end_set_parameter(p.continuous(i));
+}
@@ -0,0 +1,232 @@
+//! 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 = &anvil::clap_entry;
+        assert!(entry.init.unwrap()(c"anvil.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"Anvil");
+        assert_eq!(
+            CStr::from_ptr((*descriptor).id),
+            c"io.narl.bass-foundry.anvil"
+        );
+        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());
+        // Main input plus the kick sidechain; one output.
+        assert_eq!((*ports).count.unwrap()(plugin, true), 2);
+        assert_eq!((*ports).count.unwrap()(plugin, false), 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("level".into(), ParamValue::F32(-14.));
+        envelope.params.insert("octave".into(), ParamValue::I32(-1));
+        envelope.params.insert("ghost".into(), ParamValue::F32(40.));
+        envelope
+            .params
+            .insert("kick_lock".into(), ParamValue::Bool(true));
+        envelope
+            .params
+            .insert("kick_offset".into(), ParamValue::F32(-7.));
+        envelope
+            .params
+            .insert("snap".into(), ParamValue::Bool(false));
+        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()
+        );
+        assert!(!restored.fields.contains_key("solo"));
+        for rate in [44100., 48000., 96000.] {
+            assert!(p.activate.unwrap()(plugin, rate, 1, 512));
+            let delay = (*latency).get.unwrap()(plugin) as usize;
+            // About 80 ms of lookahead: two periods of the lowest detected note.
+            assert!((delay as f64 / rate - 0.08).abs() < 0.01, "{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 sits above the split and passes through 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()];
+                // A connected but silent kick sidechain.
+                let (mut kick_left, mut kick_right) = ([0f32; 512], [0f32; 512]);
+                let mut kick_channels = [kick_left.as_mut_ptr(), kick_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,
+                    },
+                    clap_audio_buffer {
+                        data32: kick_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.as_ptr(),
+                    audio_outputs: &mut outgoing_audio,
+                    audio_inputs_count: 2,
+                    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()();
+    }
+}
@@ -0,0 +1,11 @@
+[package]
+name = "anvil-ui"
+version = "0.1.0"
+edition.workspace = true
+license.workspace = true
+
+[dependencies]
+egui = "0.31.1"
+anvil-core = { path = "../core" }
+common-ui = { path = "../../common/ui" }
+common-dsp = { path = "../../common/dsp" }
@@ -0,0 +1,601 @@
+//! Anvil editor, shared by the CLAP wrapper and the headless renderer.
+use anvil_core::{
+    AnalyzerFrame, Settings, Source, AUDITION, AUDITION_HITS, GHOST_COUNT, KICK_OFFSET_MAX,
+    PHONE_LOW, SCOPE,
+};
+use common_ui::*;
+use egui::{self, Color32, FontId, Pos2, RichText, Sense, Stroke, Vec2};
+
+pub use common_ui::style;
+pub const WIDTH: u32 = 980;
+pub const HEIGHT: u32 = 872;
+
+pub struct State {
+    pub solo: bool,
+    /// Phone-like listen. A monitor, never saved.
+    pub phone: bool,
+    /// Kick offset audition. A monitor, never saved.
+    pub audition: bool,
+    pub analyzer: AnalyzerFrame,
+    /// 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 {
+            solo: false,
+            phone: false,
+            audition: false,
+            analyzer: AnalyzerFrame::default(),
+            gesture_active: false,
+            help: DEFAULT_HELP.into(),
+        }
+    }
+}
+const DEFAULT_HELP: &str =
+    "Put Anvil on the bass, set Split just above the sub, then set Sub level once for every patch.";
+impl State {
+    pub fn accept_frame(&mut self, frame: AnalyzerFrame) {
+        let old = self.analyzer;
+        self.analyzer = frame;
+        // Meters fall smoothly; the readout and scope stay exact.
+        self.analyzer.low_db = frame.low_db.max(old.low_db - 1.5);
+        self.analyzer.sub_db = frame.sub_db.max(old.sub_db - 1.5);
+    }
+}
+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,
+    size: f32,
+    help: &str,
+) {
+    ui.vertical_centered(|ui| {
+        let r = rotary(ui, name, value, range, default, unit, size, ACCENT);
+        hint(&r, state, help);
+    });
+}
+fn toggle(ui: &mut egui::Ui, state: &mut State, on: &mut bool, label: &str, help: &str) {
+    let r = ui.selectable_label(*on, RichText::new(label).size(13.));
+    if r.clicked() {
+        *on = !*on;
+    }
+    hint(&r, state, help);
+}
+/// Harmonics 2–10 of the current note: what the patch carries above the split (steel)
+/// and what Ghost adds (accent), from −48 dB to 0 dB against the sub.
+fn harmonics(p: &egui::Painter, rect: egui::Rect, frame: &AnalyzerFrame) {
+    p.rect_filled(rect, 2., Color32::from_rgba_unmultiplied(12, 13, 16, 230));
+    p.rect_stroke(
+        rect,
+        2.,
+        Stroke::new(1.0_f32, EDGE),
+        egui::StrokeKind::Inside,
+    );
+    p.text(
+        rect.left_top() + Vec2::new(8., 6.),
+        egui::Align2::LEFT_TOP,
+        "GHOST",
+        FontId::proportional(10.),
+        ACCENT,
+    );
+    p.text(
+        rect.right_top() + Vec2::new(-8., 6.),
+        egui::Align2::RIGHT_TOP,
+        format!("from {:.0} Hz", frame.ghost_edge),
+        FontId::proportional(10.),
+        MUTED,
+    );
+    let area = egui::Rect::from_min_max(
+        rect.left_top() + Vec2::new(8., 22.),
+        rect.right_bottom() - Vec2::new(8., 16.),
+    );
+    let slot = area.width() / GHOST_COUNT as f32;
+    let height = |db: f32| ((db + 48.) / 48.).clamp(0., 1.) * area.height();
+    for i in 0..GHOST_COUNT {
+        let x = area.left() + slot * i as f32;
+        let bar = |left: f32, db: f32, color: Color32| {
+            let h = height(db);
+            if h > 0.5 {
+                p.rect_filled(
+                    egui::Rect::from_min_max(
+                        Pos2::new(left, area.bottom() - h),
+                        Pos2::new(left + slot * 0.36, area.bottom()),
+                    ),
+                    1.,
+                    color,
+                );
+            }
+        };
+        bar(x + slot * 0.12, frame.patch_harmonics[i], STEEL);
+        bar(x + slot * 0.52, frame.ghost_harmonics[i], ACCENT);
+        p.text(
+            Pos2::new(x + slot * 0.5, area.bottom() + 2.),
+            egui::Align2::CENTER_TOP,
+            format!("{}", i + 2),
+            FontId::proportional(9.),
+            DIM,
+        );
+    }
+}
+fn scope(ui: &mut egui::Ui, frame: &AnalyzerFrame, height: f32, ghost: bool) {
+    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);
+    let mid = rect.center().y;
+    for k in 1..6 {
+        let x = rect.left() + rect.width() * k as f32 / 6.;
+        p.line_segment(
+            [Pos2::new(x, rect.top()), Pos2::new(x, rect.bottom())],
+            Stroke::new(1.0_f32, Color32::from_rgb(24, 26, 30)),
+        );
+    }
+    p.line_segment(
+        [Pos2::new(rect.left(), mid), Pos2::new(rect.right(), mid)],
+        Stroke::new(1.0_f32, EDGE),
+    );
+    let peak = frame
+        .scope_low
+        .iter()
+        .chain(frame.scope_sub.iter())
+        .fold(0.05f32, |m, v| m.max(v.abs()));
+    let scale = rect.height() * 0.42 / peak;
+    for (data, color, width) in [
+        (&frame.scope_low, STEEL, 1.5_f32),
+        (&frame.scope_sub, ACCENT, 2.0_f32),
+    ] {
+        let points: Vec<Pos2> = data
+            .iter()
+            .enumerate()
+            .map(|(i, v)| {
+                Pos2::new(
+                    rect.left() + rect.width() * i as f32 / (SCOPE - 1) as f32,
+                    mid - v * scale,
+                )
+            })
+            .collect();
+        p.add(egui::Shape::line(points, Stroke::new(width, color)));
+    }
+    p.text(
+        rect.left_top() + Vec2::new(10., 8.),
+        egui::Align2::LEFT_TOP,
+        "ORIGINAL LOW BAND",
+        FontId::proportional(11.),
+        STEEL,
+    );
+    p.text(
+        rect.left_top() + Vec2::new(130., 8.),
+        egui::Align2::LEFT_TOP,
+        "NEW SUB",
+        FontId::proportional(11.),
+        ACCENT,
+    );
+    p.text(
+        rect.right_top() + Vec2::new(-10., 8.),
+        egui::Align2::RIGHT_TOP,
+        format!("{:.0} ms", frame.scope_ms),
+        FontId::proportional(11.),
+        MUTED,
+    );
+    if ghost {
+        let size = Vec2::new(200., 92.);
+        let corner = rect.right_bottom() - Vec2::new(8., 8.);
+        harmonics(&p, egui::Rect::from_min_max(corner - size, corner), frame);
+    }
+    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, "ANVIL", "SUB ANCHOR", |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;
+        }
+        let r = ui
+            .selectable_label(state.solo, RichText::new("SOLO SUB").size(13.))
+            .on_hover_text("Hear only the generated sub and Ghost harmonics.");
+        if r.clicked() {
+            state.solo = !state.solo;
+        }
+        let r = ui
+            .selectable_label(state.phone, RichText::new("PHONE").size(13.))
+            .on_hover_text(format!(
+                "Listen as on a phone: mono, nothing below {PHONE_LOW:.0} Hz. Not saved."
+            ));
+        if r.clicked() {
+            state.phone = !state.phone;
+        }
+        ui.separator();
+        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, "PITCH FROM");
+    });
+    ui.add_space(6.);
+    let frame = state.analyzer;
+    ui.horizontal_top(|ui| {
+        panel(ui, |ui| {
+            ui.set_width(260.);
+            ui.set_min_height(TOP);
+            ui.vertical(|ui| note_panel(ui, settings, &frame));
+        });
+        ui.add_space(4.);
+        panel(ui, |ui| {
+            ui.set_width(ui.available_width());
+            scope(ui, &frame, TOP, settings.ghost > 0.);
+        });
+    });
+    ui.add_space(6.);
+    panel(ui, |ui| {
+        ui.set_width(ui.available_width());
+        ui.vertical(|ui| controls(ui, settings, state));
+    });
+    ui.add_space(6.);
+    panel(ui, |ui| {
+        ui.set_width(ui.available_width());
+        kick_panel(ui, settings, state);
+    });
+    ui.separator();
+    ui.label(RichText::new(&state.help).color(MUTED));
+}
+const TOP: f32 = 196.;
+fn note_panel(ui: &mut egui::Ui, settings: &Settings, frame: &AnalyzerFrame) {
+    caption(ui, "NOTE");
+    let (name, hz) = match frame.note {
+        Some(n) if frame.hz > 0. => (common_dsp::note_name(n), format!("{:.1} Hz", frame.hz)),
+        _ => ("—".into(), "no note".into()),
+    };
+    ui.label(
+        RichText::new(name)
+            .font(FontId::new(54., egui::FontFamily::Name("medium".into())))
+            .color(if frame.note.is_some() { TEXT } else { DIM }),
+    );
+    ui.label(RichText::new(hz).monospace().size(14.).color(MUTED));
+    ui.add_space(10.);
+    meter(ui, "ORIGINAL", frame.low_db, STEEL, 100.);
+    meter(ui, "NEW SUB", frame.sub_db, ACCENT, 100.);
+    ui.add_space(10.);
+    ui.label(
+        RichText::new(format!(
+            "{:.0} ms lookahead · {}",
+            frame.latency as f32 / frame.sample_rate * 1000.,
+            match settings.source {
+                Source::Audio => "detecting pitch",
+                Source::Midi => "following MIDI notes",
+            }
+        ))
+        .size(12.)
+        .color(MUTED),
+    );
+}
+fn controls(ui: &mut egui::Ui, settings: &mut Settings, state: &mut State) {
+    let defaults = Settings::default();
+    ui.columns(6, |c| {
+        knob(
+            &mut c[0],
+            state,
+            "Sub level",
+            &mut settings.level,
+            -30. ..=0.,
+            defaults.level,
+            " dBFS",
+            88.,
+            "Peak level of the new sub. Every note gets exactly this level.",
+        );
+        knob(
+            &mut c[1],
+            state,
+            "Split",
+            &mut settings.split,
+            40. ..=200.,
+            defaults.split,
+            " Hz",
+            88.,
+            "Below this frequency the original sub is replaced.",
+        );
+        knob(
+            &mut c[2],
+            state,
+            "Dynamics",
+            &mut settings.dynamics,
+            0. ..=100.,
+            defaults.dynamics,
+            " %",
+            88.,
+            "0 %: constant level per note. Higher: follow the original's wobble shape.",
+        );
+        knob(
+            &mut c[3],
+            state,
+            "Drive",
+            &mut settings.drive,
+            0. ..=100.,
+            defaults.drive,
+            " %",
+            88.,
+            "Saturates the sine: odd harmonics, thicker sub. Changes the sub itself.",
+        );
+        knob(
+            &mut c[4],
+            state,
+            "Ghost",
+            &mut settings.ghost,
+            0. ..=100.,
+            defaults.ghost,
+            " %",
+            88.,
+            "Adds the sub's harmonics 2–10 above Ghost from, so phones hear the note. \
+             Only harmonics the patch lacks are added. The sub itself stays the same.",
+        );
+        knob(
+            &mut c[5],
+            state,
+            "Ghost from",
+            &mut settings.ghost_from,
+            150. ..=600.,
+            defaults.ghost_from,
+            " Hz",
+            88.,
+            "Lowest frequency Ghost adds. Phones cut off around 300–500 Hz. Never below Split.",
+        );
+    });
+    ui.add_space(6.);
+    ui.separator();
+    ui.columns(6, |c| {
+        let mut octave = settings.octave as f32;
+        knob(
+            &mut c[0],
+            state,
+            "Octave",
+            &mut octave,
+            -2. ..=1.,
+            0.,
+            "",
+            54.,
+            "Shift the sub against the detected note. −1 for basses played high.",
+        );
+        settings.octave = octave.round() as i32;
+        knob(
+            &mut c[1],
+            state,
+            "Glide",
+            &mut settings.glide,
+            0. ..=200.,
+            defaults.glide,
+            " ms",
+            54.,
+            "Slide time when notes overlap. 0 jumps.",
+        );
+        knob(
+            &mut c[2],
+            state,
+            "Phase",
+            &mut settings.phase,
+            0. ..=360.,
+            defaults.phase,
+            "°",
+            54.,
+            "Start phase of every note. Line it up with your kick.",
+        );
+        knob(
+            &mut c[3],
+            state,
+            "Gate",
+            &mut settings.gate,
+            -60. ..=-20.,
+            defaults.gate,
+            " dB",
+            54.,
+            "Input level that counts as a note. Raise it if tails retrigger.",
+        );
+        knob(
+            &mut c[4],
+            state,
+            "Keep",
+            &mut settings.keep,
+            0. ..=100.,
+            defaults.keep,
+            " %",
+            54.,
+            "Blend some original low band back under the new sub.",
+        );
+        knob(
+            &mut c[5],
+            state,
+            "Output",
+            &mut settings.output,
+            -12. ..=12.,
+            defaults.output,
+            " dB",
+            54.,
+            "Output trim.",
+        );
+    });
+    ui.add_space(4.);
+    ui.horizontal(|ui| {
+        toggle(
+            ui,
+            state,
+            &mut settings.retrigger,
+            "RETRIGGER",
+            "Restart the sine at Phase on every note, so each note and kick hit lines up.",
+        );
+        toggle(
+            ui,
+            state,
+            &mut settings.snap,
+            "SNAP TO SEMITONE",
+            "Round the detected pitch. Turn off for slides and pitch bends.",
+        );
+    });
+}
+fn kick_panel(ui: &mut egui::Ui, settings: &mut Settings, state: &mut State) {
+    let defaults = Settings::default();
+    let frame = state.analyzer;
+    ui.horizontal_top(|ui| {
+        ui.vertical(|ui| {
+            ui.set_width(150.);
+            caption(ui, "KICK LOCK");
+            toggle(
+                ui,
+                state,
+                &mut settings.kick_lock,
+                "KICK LOCK",
+                "Route the kick into Anvil's sidechain. On each kick the sub dips and \
+                 restarts at Phase, so kick and sub hit together.",
+            );
+            ui.add_space(6.);
+            let status = if !settings.kick_lock {
+                "off".to_string()
+            } else if frame.kick_hits == 0 {
+                "no kick in the sidechain".to_string()
+            } else if frame.kick_sum_db.is_finite() {
+                format!("{} kicks · sum {:+.1} dB", frame.kick_hits, frame.kick_sum_db)
+            } else {
+                format!("{} kicks", frame.kick_hits)
+            };
+            ui.label(RichText::new(status).size(12.).color(MUTED));
+        });
+        ui.columns(4, |c| {
+            knob(
+                &mut c[0],
+                state,
+                "Duck",
+                &mut settings.kick_duck,
+                0. ..=24.,
+                defaults.kick_duck,
+                " dB",
+                54.,
+                "How far the sub dips on each kick.",
+            );
+            knob(
+                &mut c[1],
+                state,
+                "Release",
+                &mut settings.kick_release,
+                10. ..=300.,
+                defaults.kick_release,
+                " ms",
+                54.,
+                "Time for the sub to come back after a kick.",
+            );
+            knob(
+                &mut c[2],
+                state,
+                "Offset",
+                &mut settings.kick_offset,
+                -KICK_OFFSET_MAX..=KICK_OFFSET_MAX,
+                defaults.kick_offset,
+                " ms",
+                54.,
+                "When the sub restarts against the kick. Negative: before it. Use Audition to find it by ear.",
+            );
+            c[3].vertical(|ui| audition(ui, settings, state));
+        });
+    });
+}
+/// The audition: each offset plays for a few kicks; bars show how kick and sub summed.
+fn audition(ui: &mut egui::Ui, settings: &mut Settings, state: &mut State) {
+    let frame = state.analyzer;
+    ui.horizontal(|ui| {
+        let r = ui.selectable_label(state.audition, RichText::new("AUDITION").size(12.));
+        if r.clicked() {
+            state.audition = !state.audition;
+        }
+        hint(
+            &r,
+            state,
+            &format!(
+                "Steps the offset from −30 to +30 ms, {AUDITION_HITS} kicks each. Press KEEP \
+                 when kick and sub sound like one hit. Not saved."
+            ),
+        );
+        let r = ui.add_enabled(
+            state.audition && frame.kick_hits > 0,
+            egui::Button::new(RichText::new("KEEP").size(12.)),
+        );
+        if r.clicked() {
+            settings.kick_offset = frame.kick_offset;
+            state.audition = false;
+        }
+        hint(
+            &r,
+            state,
+            "Set Offset to the one playing now and stop the audition.",
+        );
+    });
+    let (rect, _) = ui.allocate_exact_size(Vec2::new(ui.available_width(), 58.), Sense::hover());
+    let p = ui.painter_at(rect);
+    p.rect_filled(rect, 2., SCREEN);
+    let slot = rect.width() / AUDITION.len() as f32;
+    // −9 dB to +3 dB: +3 is a full sum of equal levels.
+    let height = |db: f32| ((db + 9.) / 12.).clamp(0.02, 1.) * (rect.height() - 14.);
+    for (i, &offset) in AUDITION.iter().enumerate() {
+        let x = rect.left() + slot * i as f32;
+        let db = frame.audition_sums[i];
+        let playing = state.audition && (offset - frame.kick_offset).abs() < 0.01;
+        if db.is_finite() {
+            let h = height(db);
+            p.rect_filled(
+                egui::Rect::from_min_max(
+                    Pos2::new(x + slot * 0.2, rect.bottom() - 12. - h),
+                    Pos2::new(x + slot * 0.8, rect.bottom() - 12.),
+                ),
+                1.,
+                if playing { ACCENT } else { STEEL },
+            );
+        }
+        if (offset - settings.kick_offset).abs() < 0.01 {
+            // The kept offset.
+            let (cx, base) = (x + slot * 0.5, rect.bottom() - 2.);
+            p.add(egui::Shape::convex_polygon(
+                vec![
+                    Pos2::new(cx, base - 7.),
+                    Pos2::new(cx + 4., base),
+                    Pos2::new(cx - 4., base),
+                ],
+                ACCENT,
+                Stroke::NONE,
+            ));
+        } else if i % 2 == 0 {
+            p.text(
+                Pos2::new(x + slot * 0.5, rect.bottom() - 1.),
+                egui::Align2::CENTER_BOTTOM,
+                format!("{offset:+.0}"),
+                FontId::proportional(8.),
+                DIM,
+            );
+        }
+    }
+    let line = if state.audition {
+        format!("playing {:+.0} ms", frame.kick_offset)
+    } else {
+        "sum per offset, low band".into()
+    };
+    ui.label(RichText::new(line).size(11.).color(MUTED));
+}
@@ -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 }
@@ -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
+    }
+}
@@ -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")
+        }
+    }
+}
@@ -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());
+}
@@ -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);
+}
@@ -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"
@@ -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);
@@ -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);
+        }
+    }
+}
@@ -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()();
+    }
+}
@@ -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" }
@@ -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.",
+        );
+    });
+}
@@ -0,0 +1,12 @@
+[package]
+name = "braze-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 }
@@ -0,0 +1,356 @@
+//! Tempo-locked beating: adds a detuned copy of the bass whose beating stays in time with
+//! the track on every note.
+//!
+//! Two layers detuned by a ratio r beat at k·f0·(r − 1) on harmonic k, so a fixed detune
+//! beats at a different rate on every note. Braze sets the detune per note from the tracked
+//! fundamental: harmonic `harmonic` beats once per `rate` note value, and harmonic n beats
+//! n/harmonic times as fast, so every harmonic beats on the tempo grid.
+//!
+//! The copy is the bass read from a delay line whose delay falls by one period of the note
+//! per beat cycle of the chosen harmonic. That shifts the copy up by exactly the wanted
+//! ratio. When the delay has fallen by a whole period it jumps back by one period: for a
+//! periodic note both read positions hold the same waveform, so the jump is crossfaded over
+//! a few milliseconds without a seam. The delay is set from the host's beat position, so
+//! the beat's peaks land on the grid, not just at the right rate. At a beat peak the copy
+//! lines up with the bass exactly.
+//!
+//! Low cut removes the copy below a frequency with a 4th-order Linkwitz–Riley high-pass,
+//! so the sub does not beat. The bass is split by the same crossover; its two bands are in
+//! phase with the copy's high-pass at every frequency, so the beat peaks stay on the grid,
+//! and the loudness correction for the copy applies above the cut only, so the sub keeps
+//! its level.
+mod settings;
+use common_dsp::svf::{Svf, SvfCoef};
+use common_dsp::tracker::{PitchFollower, Tracker, TrackerConfig};
+use common_dsp::{coefficient, db_to_gain, hz_to_midi};
+pub use settings::{Rate, Settings, Source, HARMONIC_MAX, LOW_CUT_MAX, LOW_CUT_OFF};
+
+pub const MIN_HZ: f32 = TrackerConfig::BASS.min_hz;
+pub const MAX_HZ: f32 = TrackerConfig::BASS.max_hz;
+/// Fundamental the copy assumes before the first note.
+pub const FALLBACK_HZ: f32 = 55.;
+/// Tempo when the host reports none.
+pub const DEFAULT_TEMPO: f64 = 120.;
+/// Crossfade between the old and the new read position.
+const FADE_MS: f32 = 6.;
+/// A beat position that moves further than this (in cycles of the chosen harmonic) from
+/// one sample to the next counts as a jump: a locate, a loop, or a changed control.
+const JUMP: f64 = 1e-3;
+/// Pitch smoothing for bends and slides.
+const PITCH_MS: f32 = 5.;
+
+#[derive(Clone, Copy, Debug)]
+pub struct AnalyzerFrame {
+    /// Fundamental the copy is tuned to, 0 before the first note.
+    pub hz: f32,
+    /// Sounding note, rounded; None between notes.
+    pub note: Option<u8>,
+    /// Beat position at the output, in quarter notes.
+    pub beats: f64,
+    pub tempo: f64,
+    /// True when the beat position comes from the host's transport.
+    pub synced: bool,
+    /// Detune of the copy as a ratio, 1 before the first note.
+    pub ratio: f32,
+    pub latency: u32,
+    pub sample_rate: f32,
+}
+impl Default for AnalyzerFrame {
+    fn default() -> Self {
+        Self {
+            hz: 0.,
+            note: None,
+            beats: 0.,
+            tempo: DEFAULT_TEMPO,
+            synced: false,
+            ratio: 1.,
+            latency: 0,
+            sample_rate: 48000.,
+        }
+    }
+}
+
+/// Beat cycles of the chosen harmonic at `beats` quarter notes, for one channel.
+pub fn cycles(s: &Settings, beats: f64, channel: usize) -> f64 {
+    beats / s.rate.quarters() + s.phase as f64 / 360. + channel as f64 * s.width as f64 * 0.005
+}
+/// Level of harmonic `n` in the sum, against the bass alone, at `cycles` of the chosen
+/// harmonic, with the copy at `depth` (0–1). Includes the output's loudness correction.
+pub fn envelope(s: &Settings, n: u32, cycles: f64, depth: f32) -> f32 {
+    let theta = std::f64::consts::TAU * n as f64 / s.harmonic as f64 * cycles;
+    let (re, im) = (1. + depth as f64 * theta.cos(), depth as f64 * theta.sin());
+    ((re * re + im * im).sqrt() / (1. + depth as f64 * depth as f64).sqrt()) as f32
+}
+
+#[derive(Clone, Copy, Debug, Default)]
+struct Tap {
+    /// Delay in samples.
+    delay: f32,
+    /// Delay change per sample, so a fading tap keeps its course.
+    slope: f32,
+}
+
+#[derive(Clone, Copy, Debug, Default)]
+struct Channel {
+    active: Tap,
+    old: Tap,
+    /// Weight of the old tap, falling to 0.
+    fade: f32,
+    /// Whole cycles the active tap's delay is counted from.
+    whole: f64,
+    /// Beat cycle position (`cycles / harmonic + 0.5`) of the previous sample.
+    last: f64,
+    started: bool,
+    copy_high: [Svf; 2],
+    high: [Svf; 2],
+    low: [Svf; 2],
+}
+
+pub struct Engine {
+    rate: f32,
+    channels: usize,
+    settings: Settings,
+    latency: usize,
+    audio: Vec<[f32; 2]>,
+    audio_at: usize,
+    tracker: Tracker,
+    pitch: PitchFollower,
+    pitch_coef: f32,
+    hz: f32,
+    beats: f64,
+    tempo: f64,
+    synced: bool,
+    state: [Channel; 2],
+    /// High-pass and low-pass of the low cut's crossover; None when off.
+    low_cut: Option<(SvfCoef, SvfCoef)>,
+    fade_step: f32,
+    smooth: f32,
+    depth: f32,
+    output: f32,
+    bypass: f32,
+    fresh: bool,
+}
+
+impl Engine {
+    pub fn new(rate: f32, channels: usize) -> Result<Self, &'static str> {
+        if !(8000.0..=768000.).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 latency = tracker.latency();
+        // The copy reads up to half a period (plus a fade) on either side of the dry path.
+        let reach = (rate / MIN_HZ).ceil() as usize + 8;
+        let mut e = Self {
+            rate,
+            channels,
+            settings: Settings::default(),
+            latency,
+            audio: vec![[0.; 2]; latency + reach],
+            audio_at: 0,
+            tracker,
+            pitch: PitchFollower::default(),
+            pitch_coef: coefficient(rate, PITCH_MS),
+            hz: 0.,
+            beats: 0.,
+            tempo: DEFAULT_TEMPO,
+            synced: false,
+            state: [Channel::default(); 2],
+            low_cut: None,
+            fade_step: 1. / (rate * FADE_MS * 0.001),
+            smooth: coefficient(rate, 10.),
+            depth: 0.,
+            output: 1.,
+            bypass: 0.,
+            fresh: true,
+        };
+        e.set_settings(Settings::default())?;
+        e.fresh = true;
+        Ok(e)
+    }
+    pub fn latency_samples(&self) -> u32 {
+        self.latency 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, true);
+        if s.low_cut != self.settings.low_cut || self.fresh {
+            let q = std::f32::consts::FRAC_1_SQRT_2;
+            let hz = s.low_cut.min(0.45 * self.rate);
+            self.low_cut = (s.low_cut >= LOW_CUT_OFF).then(|| {
+                (
+                    SvfCoef::highpass(self.rate, hz, q),
+                    SvfCoef::lowpass(self.rate, hz, q),
+                )
+            });
+        }
+        self.settings = s;
+        if std::mem::take(&mut self.fresh) {
+            self.depth = s.depth * 0.01;
+            self.output = db_to_gain(s.output);
+            self.bypass = f32::from(s.bypass);
+        }
+        Ok(())
+    }
+    /// Tempo and, while the host plays, its beat position in quarter notes at the first
+    /// input sample of the next block. Without a position the beat runs on freely.
+    pub fn set_transport(&mut self, tempo: Option<f64>, position: Option<f64>) {
+        self.tempo = tempo
+            .filter(|t| t.is_finite() && *t > 0.)
+            .unwrap_or(DEFAULT_TEMPO)
+            .clamp(20., 999.);
+        match position.filter(|p| p.is_finite()) {
+            Some(p) => {
+                // The output lags the input by the lookahead, and the host compensates it:
+                // what leaves now belongs `latency` samples earlier on the timeline.
+                self.beats = p - self.latency as f64 / self.rate as f64 * self.tempo / 60.;
+                self.synced = true;
+            }
+            None => self.synced = false,
+        }
+    }
+    pub fn reset(&mut self) {
+        self.audio.fill([0.; 2]);
+        self.tracker.reset();
+        self.pitch = PitchFollower::default();
+        self.hz = 0.;
+        self.state = [Channel::default(); 2];
+        self.fresh = true;
+    }
+    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);
+    }
+    /// The audio `back` samples (fractional) before the newest one, cubic Hermite.
+    #[inline]
+    fn read(&self, back: f32, c: usize) -> f32 {
+        let len = self.audio.len();
+        let back = back.clamp(1., (len - 3) as f32);
+        let whole = back.floor();
+        let t = back - whole;
+        let base = whole as usize;
+        let at = |back: usize| self.audio[(self.audio_at + len - back) % len][c];
+        // y0 is one sample newer than y1; y2 and y3 are older.
+        let (y0, y1, y2, y3) = (at(base - 1), at(base), at(base + 1), at(base + 2));
+        let c1 = 0.5 * (y2 - y0);
+        let c2 = y0 - 2.5 * y1 + 2. * y2 - 0.5 * y3;
+        let c3 = 0.5 * (y3 - y0) + 1.5 * (y1 - y2);
+        ((c3 * t + c2) * t + c1) * t + y1
+    }
+    // Channels index the input, the state 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 (pitch, snap) = (&mut self.pitch, self.settings.snap);
+        self.tracker.process(mono, |e| pitch.event(snap, e));
+        let (hz, jump) = self.pitch.step(self.pitch_coef);
+        self.hz = hz;
+        let len = self.audio.len();
+        self.audio_at = (self.audio_at + 1) % len;
+        self.audio[self.audio_at] = x;
+
+        let s = self.settings;
+        approach(&mut self.depth, s.depth * 0.01, self.smooth);
+        approach(&mut self.output, db_to_gain(s.output), self.smooth);
+        approach(&mut self.bypass, f32::from(s.bypass), self.smooth);
+
+        let period = self.rate / if hz > 0. { hz } else { FALLBACK_HZ };
+        let step = self.tempo / 60. / self.rate as f64 / s.rate.quarters() / s.harmonic as f64;
+        let centre = self.latency as f32;
+        let mut out = [0.; 2];
+        for c in 0..self.channels {
+            // Position in beat cycles of the chosen harmonic, shifted so a cycle starts at
+            // the delay's highest point and the beat peaks (delay = centre) at cycle 0.
+            let u = cycles(&s, self.beats, c) / s.harmonic as f64 + 0.5;
+            let ch = self.state[c];
+            let moved = (u - ch.last - step).abs() > JUMP;
+            let mut ch = ch;
+            if !ch.started || jump || moved || u.floor() != ch.whole {
+                if ch.started {
+                    ch.old = ch.active;
+                    ch.fade = 1.;
+                }
+                ch.whole = u.floor();
+                ch.started = true;
+            }
+            let delay = centre + period * (0.5 - (u - ch.whole) as f32);
+            ch.active.slope = if ch.fade == 1. {
+                0.
+            } else {
+                delay - ch.active.delay
+            };
+            ch.active.delay = delay;
+            ch.last = u;
+            let mut copy = self.read(ch.active.delay, c);
+            if ch.fade > 0. {
+                ch.old.delay += ch.old.slope;
+                let w = ch.fade * ch.fade * (3. - 2. * ch.fade);
+                copy += (self.read(ch.old.delay, c) - copy) * w;
+                ch.fade = (ch.fade - self.fade_step).max(0.);
+            }
+            let delayed = self.audio[(self.audio_at + len - self.latency) % len][c];
+            let g = self.depth;
+            let norm = 1. / (1. + g * g).sqrt();
+            let wet = match &self.low_cut {
+                Some((high, low)) => {
+                    let lr4 = |f: &mut [Svf; 2], c: &SvfCoef, x: f32| {
+                        let first = f[0].process(c, x);
+                        f[1].process(c, first)
+                    };
+                    let copy = lr4(&mut ch.copy_high, high, copy);
+                    let above = lr4(&mut ch.high, high, delayed);
+                    let below = lr4(&mut ch.low, low, delayed);
+                    below + (above + g * copy) * norm
+                }
+                None => (delayed + g * copy) * norm,
+            };
+            self.state[c] = ch;
+            out[c] = wet * self.output * (1. - self.bypass) + delayed * self.bypass;
+        }
+        self.beats += self.tempo / 60. / self.rate as f64;
+        out
+    }
+    pub fn take_analyzer(&self) -> AnalyzerFrame {
+        let s = self.settings;
+        let hz = self.hz;
+        let mut f = AnalyzerFrame {
+            hz,
+            beats: self.beats,
+            tempo: self.tempo,
+            synced: self.synced,
+            latency: self.latency as u32,
+            sample_rate: self.rate,
+            ..AnalyzerFrame::default()
+        };
+        if hz > 0. {
+            let beat_hz = self.tempo / 60. / s.rate.quarters();
+            f.ratio = 1. + (beat_hz / (s.harmonic as f64 * hz as f64)) as f32;
+        }
+        if self.tracker.sounding() && hz > 0. {
+            f.note = Some(hz_to_midi(hz).round().clamp(0., 127.) as u8);
+        }
+        f
+    }
+}
+
+/// One-pole step that lands exactly on the target, so switched states end bit-exact.
+fn approach(value: &mut f32, target: f32, coef: f32) {
+    *value += (target - *value) * coef;
+    if (target - *value).abs() < 1e-6 {
+        *value = target;
+    }
+}
@@ -0,0 +1,146 @@
+//! Host-independent controls. Levels in dB, amounts in percent, angles in degrees.
+use serde::{Deserialize, Serialize};
+
+/// Highest harmonic the beat rate can be set on.
+pub const HARMONIC_MAX: u32 = 8;
+pub const LOW_CUT_MAX: f32 = 400.;
+/// A low cut below this is off: no filter on either path.
+pub const LOW_CUT_OFF: f32 = 20.;
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
+pub enum Source {
+    /// Pitch and note starts are detected from the incoming bass.
+    #[default]
+    Audio,
+    /// Notes come from MIDI note input.
+    Midi,
+}
+
+/// One beat cycle lasts this note value.
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
+pub enum Rate {
+    Whole,
+    Half,
+    Quarter,
+    #[default]
+    Eighth,
+    Sixteenth,
+    ThirtySecond,
+    QuarterTriplet,
+    EighthTriplet,
+    SixteenthTriplet,
+}
+impl Rate {
+    pub const ALL: [Rate; 9] = [
+        Rate::Whole,
+        Rate::Half,
+        Rate::Quarter,
+        Rate::Eighth,
+        Rate::Sixteenth,
+        Rate::ThirtySecond,
+        Rate::QuarterTriplet,
+        Rate::EighthTriplet,
+        Rate::SixteenthTriplet,
+    ];
+    /// Length of one beat cycle in quarter notes.
+    pub fn quarters(self) -> f64 {
+        match self {
+            Rate::Whole => 4.,
+            Rate::Half => 2.,
+            Rate::Quarter => 1.,
+            Rate::Eighth => 0.5,
+            Rate::Sixteenth => 0.25,
+            Rate::ThirtySecond => 0.125,
+            Rate::QuarterTriplet => 2. / 3.,
+            Rate::EighthTriplet => 1. / 3.,
+            Rate::SixteenthTriplet => 1. / 6.,
+        }
+    }
+    pub fn label(self) -> &'static str {
+        match self {
+            Rate::Whole => "1/1",
+            Rate::Half => "1/2",
+            Rate::Quarter => "1/4",
+            Rate::Eighth => "1/8",
+            Rate::Sixteenth => "1/16",
+            Rate::ThirtySecond => "1/32",
+            Rate::QuarterTriplet => "1/4T",
+            Rate::EighthTriplet => "1/8T",
+            Rate::SixteenthTriplet => "1/16T",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq)]
+#[serde(deny_unknown_fields)]
+pub struct Settings {
+    pub source: Source,
+    /// How long one beat cycle of `harmonic` lasts.
+    pub rate: Rate,
+    /// The harmonic that beats exactly at `rate`. Harmonic n beats n/harmonic times as fast.
+    pub harmonic: u32,
+    /// Level of the detuned copy against the bass. 100 % gives full nulls.
+    pub depth: f32,
+    /// Below this frequency the copy is removed, so the sub stays steady and mono-safe.
+    /// Under `LOW_CUT_OFF` Hz the filter is off.
+    pub low_cut: f32,
+    /// Moves the right channel's beat against the left, up to half a cycle.
+    pub width: f32,
+    /// Where in the cycle the beat peaks, in degrees. 0 puts the peak on the beat.
+    pub phase: f32,
+    /// Detection threshold in dBFS for note starts (Audio source).
+    pub gate: f32,
+    /// Round detected pitch to the nearest semitone. Off by default: the copy jumps by one
+    /// period of the pitch in use, and a period that does not fit the note is heard.
+    pub snap: bool,
+    pub output: f32,
+    pub bypass: bool,
+}
+impl Default for Settings {
+    fn default() -> Self {
+        Self {
+            source: Source::Audio,
+            rate: Rate::Eighth,
+            // Harmonic 4 sits above the low cut on every bass note, and on F1 it asks for
+            // about 45 cents of detune, a usual reese spread.
+            harmonic: 4,
+            depth: 70.,
+            low_cut: 100.,
+            width: 0.,
+            phase: 0.,
+            gate: -48.,
+            snap: false,
+            output: 0.,
+            bypass: false,
+        }
+    }
+}
+impl Settings {
+    pub fn validate(&self) -> Result<(), &'static str> {
+        let finite = [
+            self.depth,
+            self.low_cut,
+            self.width,
+            self.phase,
+            self.gate,
+            self.output,
+        ]
+        .iter()
+        .all(|v| v.is_finite());
+        if !finite {
+            return Err("non-finite setting");
+        }
+        let ok = (1..=HARMONIC_MAX).contains(&self.harmonic)
+            && (0.0..=100.).contains(&self.depth)
+            && (0.0..=LOW_CUT_MAX).contains(&self.low_cut)
+            && (0.0..=100.).contains(&self.width)
+            && (0.0..=360.).contains(&self.phase)
+            && (-60.0..=-20.).contains(&self.gate)
+            && (-12.0..=12.).contains(&self.output);
+        if ok {
+            Ok(())
+        } else {
+            Err("setting out of range")
+        }
+    }
+}
@@ -0,0 +1,278 @@
+// Sample indices address several signals at once.
+#![allow(clippy::needless_range_loop)]
+use braze_core::{cycles, envelope, Engine, Rate, Settings};
+use common_dsp::Saw;
+use std::f32::consts::TAU;
+
+const RATE: f32 = 48000.;
+const TEMPO: f64 = 120.;
+
+fn engine(s: Settings) -> (Engine, usize) {
+    let mut e = Engine::new(RATE, 2).unwrap();
+    e.set_settings(s).unwrap();
+    e.set_transport(Some(TEMPO), Some(0.));
+    let l = e.latency_samples() as usize;
+    (e, l)
+}
+fn seconds(t: f32) -> usize {
+    (t * RATE) as usize
+}
+fn render(e: &mut Engine, x: &[f32]) -> Vec<[f32; 2]> {
+    x.iter().map(|&s| e.process_sample([s, s])).collect()
+}
+/// A saw at `hz` from 0.05 s on, with a 1 ms fade-in.
+fn saw(hz: f32, total: f32) -> Vec<f32> {
+    let mut osc = Saw::new(RATE, hz);
+    (0..seconds(total))
+        .map(|i| {
+            let start = seconds(0.05);
+            if i < start {
+                return 0.;
+            }
+            0.5 * osc.sample() * ((i - start) as f32 / seconds(0.001) as f32).min(1.)
+        })
+        .collect()
+}
+/// Amplitude of harmonic `n` of `hz` over one period centred on sample `at`.
+fn harmonic(x: &[f32], at: usize, hz: f32, n: u32) -> f32 {
+    let half = (RATE / hz / 2.).round() as usize;
+    let w = TAU * hz * n as f32 / RATE;
+    let (mut re, mut im) = (0f32, 0f32);
+    for i in at - half..at + half {
+        re += x[i] * (w * i as f32).cos();
+        im -= x[i] * (w * i as f32).sin();
+    }
+    2. * (re * re + im * im).sqrt() / (2 * half) as f32
+}
+/// Beat position (quarter notes) of output sample `i`.
+fn beats(i: usize, latency: usize) -> f64 {
+    (i as f64 - latency as f64) / RATE as f64 * TEMPO / 60.
+}
+
+/// Harmonics 1–4 of A1 at falling levels, a periodic note the tracker reads exactly.
+fn partials(t: f64) -> f64 {
+    (1..=4)
+        .map(|n| 0.4 / n as f64 * (std::f64::consts::TAU * 55. * n as f64 * t).sin())
+        .sum()
+}
+
+#[test]
+fn every_harmonic_beats_on_the_tempo_grid() {
+    for (harmonic, rate) in [(1, Rate::Eighth), (2, Rate::Sixteenth), (3, Rate::Quarter)] {
+        let s = Settings {
+            harmonic,
+            rate,
+            depth: 100.,
+            snap: true,
+            low_cut: 0.,
+            ..Settings::default()
+        };
+        let (mut e, l) = engine(s);
+        let x: Vec<f32> = (0..seconds(1.5))
+            .map(|i| partials(i as f64 / RATE as f64) as f32)
+            .collect();
+        let y = render(&mut e, &x);
+        let mut worst = 0f32;
+        for i in seconds(0.5)..seconds(1.4) {
+            // Cycles of the chosen harmonic, from the grid alone: peaks on every multiple
+            // of `rate`. The copy lags the bass by (0.5 − frac(u)) periods.
+            let u = beats(i, l) / rate.quarters() / harmonic as f64 + 0.5;
+            let t = (i - l) as f64 / RATE as f64;
+            let lag = (0.5 - u.fract()) / 55.;
+            let ideal = (partials(t) + partials(t - lag)) / 2f64.sqrt();
+            worst = worst.max((y[i][0] - ideal as f32).abs());
+        }
+        assert!(worst < 3e-3, "harmonic {harmonic}, {rate:?}: {worst}");
+    }
+}
+
+#[test]
+fn envelope_peaks_on_the_grid_and_harmonic_n_beats_n_over_k_as_fast() {
+    let s = Settings {
+        harmonic: 2,
+        ..Settings::default()
+    };
+    // At cycle 0 every harmonic peaks: twice the bass, less the loudness correction.
+    for n in 1..=8 {
+        assert!((envelope(&s, n, 0., 1.) - 2f32.sqrt()).abs() < 1e-5);
+    }
+    // Harmonic 2 nulls half a cycle later; harmonic 1, beating half as fast, a cycle later.
+    assert!(envelope(&s, 2, 0.5, 1.) < 1e-5);
+    assert!(envelope(&s, 1, 1., 1.) < 1e-5);
+    assert!(envelope(&s, 4, 0.25, 1.) < 1e-5);
+}
+
+#[test]
+fn the_copy_is_seamless_across_its_jumps() {
+    // A pure sine at exactly A1: the ideal copy is a smooth sine whose phase follows the beat.
+    let s = Settings {
+        harmonic: 1,
+        rate: Rate::Sixteenth,
+        depth: 100.,
+        snap: true,
+        low_cut: 0.,
+        ..Settings::default()
+    };
+    let (mut e, l) = engine(s);
+    let x: Vec<f32> = (0..seconds(1.5))
+        .map(|i| 0.5 * (TAU * 55. * i as f32 / RATE).sin())
+        .collect();
+    let y = render(&mut e, &x);
+    let mut worst = 0f32;
+    for i in seconds(0.5)..seconds(1.4) {
+        let u = cycles(&s, beats(i, l), 0) + 0.5;
+        let dry = x[i - l];
+        let phase = TAU as f64 * (55. * (i - l) as f64 / RATE as f64 + u.fract());
+        let copy = -0.5 * phase.sin() as f32;
+        let ideal = (dry + copy) / 2f32.sqrt();
+        worst = worst.max((y[i][0] - ideal).abs());
+    }
+    assert!(worst < 2e-3, "{worst}");
+}
+
+#[test]
+fn depth_zero_is_the_delayed_input() {
+    let (mut e, l) = engine(Settings {
+        depth: 0.,
+        low_cut: 0.,
+        ..Settings::default()
+    });
+    let x = saw(55., 0.6);
+    let y = render(&mut e, &x);
+    for i in l..x.len() {
+        assert_eq!(y[i][0], x[i - l]);
+    }
+}
+
+#[test]
+fn width_moves_the_right_channel_half_a_cycle() {
+    let s = Settings {
+        harmonic: 1,
+        width: 100.,
+        depth: 100.,
+        rate: Rate::Quarter,
+        low_cut: 0.,
+        ..Settings::default()
+    };
+    let (mut e, l) = engine(s);
+    let x = saw(55., 1.5);
+    let y = render(&mut e, &x);
+    let left: Vec<f32> = y.iter().map(|v| v[0]).collect();
+    let right: Vec<f32> = y.iter().map(|v| v[1]).collect();
+    // On the beat the left fundamental peaks and the right one nulls; half a beat later
+    // they swap.
+    for (beat, loud, quiet) in [
+        (1., &left, &right),
+        (1.5, &right, &left),
+        (2., &left, &right),
+    ] {
+        let at = l + (beat / (TEMPO / 60.) * RATE as f64) as usize;
+        let (a, b) = (harmonic(loud, at, 55., 1), harmonic(quiet, at, 55., 1));
+        assert!(20. * (a / b).log10() > 20., "beat {beat}: {a} vs {b}");
+    }
+}
+
+#[test]
+fn note_changes_and_transport_jumps_do_not_click() {
+    let s = Settings {
+        depth: 100.,
+        ..Settings::default()
+    };
+    let (mut e, _) = engine(s);
+    // Phase-continuous sine from A1 to D2, no gap.
+    let mut phase = 0f32;
+    let x: Vec<f32> = (0..seconds(1.2))
+        .map(|i| {
+            let hz = if i < seconds(0.6) { 55. } else { 73.42 };
+            phase = (phase + hz / RATE).fract();
+            0.5 * (TAU * phase).sin()
+        })
+        .collect();
+    let mut y = Vec::new();
+    for (i, &v) in x.iter().enumerate() {
+        if i == seconds(0.9) {
+            // A locate to another bar.
+            e.set_transport(Some(TEMPO), Some(37.3));
+        }
+        y.push(e.process_sample([v, v])[0]);
+    }
+    // Two sines of peak 0.5 at up to 79 Hz move at most this much per sample (after the
+    // loudness correction), plus some room for the fades.
+    let bound = 2. * 0.5 * TAU * 79. / RATE / 2f32.sqrt() * 1.5;
+    for i in seconds(0.2)..y.len() - 1 {
+        assert!(
+            (y[i + 1] - y[i]).abs() < bound,
+            "{i}: {}",
+            (y[i + 1] - y[i]).abs()
+        );
+    }
+}
+
+#[test]
+fn low_cut_keeps_the_sub_steady_and_the_beat_on_the_grid() {
+    let s = Settings {
+        harmonic: 1,
+        depth: 100.,
+        rate: Rate::Half,
+        low_cut: 150.,
+        ..Settings::default()
+    };
+    let (mut e, l) = engine(s);
+    let x = saw(55., 2.4);
+    let y: Vec<f32> = render(&mut e, &x).iter().map(|v| v[0]).collect();
+    // One cycle (a half note, 1 s at 120 BPM): the fundamental, under the cut, does not beat.
+    let sub: Vec<f32> = (0..50)
+        .map(|k| harmonic(&y, seconds(1.) + k * seconds(0.02), 55., 1))
+        .collect();
+    let (lo, hi) = sub
+        .iter()
+        .fold((f32::MAX, 0f32), |(a, b), &v| (a.min(v), b.max(v)));
+    // Without the cut it would null fully; what remains is leakage of the beating
+    // harmonics into the one-period window.
+    assert!(20. * (hi / lo).log10() < 1.5, "{lo} .. {hi}");
+    // And it keeps its level: the loudness correction for the copy applies above the cut.
+    let dry = harmonic(&x, seconds(1.) - l, 55., 1);
+    let mean = sub.iter().sum::<f32>() / sub.len() as f32;
+    assert!((20. * (mean / dry).log10()).abs() < 0.5, "{mean} vs {dry}");
+    // Harmonic 6 (330 Hz) beats 6 times per cycle: it peaks on the grid, the high-pass's
+    // phase is matched on the bass, and nulls 1/12 cycle later.
+    for beat in [2., 4.] {
+        let peak = l + (beat / (TEMPO / 60.) * RATE as f64) as usize;
+        let null = peak + (RATE / 12.) as usize;
+        let (a, b) = (harmonic(&y, peak, 55., 6), harmonic(&y, null, 55., 6));
+        assert!(20. * (a / b).log10() > 15., "beat {beat}: {a} vs {b}");
+    }
+}
+
+#[test]
+fn the_ratio_follows_the_note() {
+    let (mut e, _) = engine(Settings {
+        harmonic: 1,
+        ..Settings::default()
+    });
+    for hz in [55., 110.] {
+        let x = saw(hz, 0.5);
+        render(&mut e, &x);
+        let f = e.take_analyzer();
+        // An eighth at 120 BPM beats 4 times per second: r = 1 + 4 / f0.
+        assert!((f.ratio - (1. + 4. / hz)).abs() < 2e-3, "{hz}: {}", f.ratio);
+    }
+}
+
+#[test]
+fn settings_are_validated_and_serialise() {
+    let mut e = Engine::new(RATE, 1).unwrap();
+    assert!(e
+        .set_settings(Settings {
+            harmonic: 0,
+            ..Settings::default()
+        })
+        .is_err());
+    let json = serde_json::to_string(&Settings::default()).unwrap();
+    assert_eq!(
+        serde_json::from_str::<Settings>(&json).unwrap(),
+        Settings::default()
+    );
+    assert!(Engine::new(1000., 2).is_err());
+    assert!(Engine::new(48000., 3).is_err());
+}
@@ -0,0 +1,79 @@
+use braze_core::{Engine, Rate, 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 {
+        width: 50.,
+        ..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 {
+            settings.rate = Rate::ALL[(i / 4800) % Rate::ALL.len()];
+            settings.harmonic = 1 + (i / 4800 % 4) as u32;
+            settings.source = if i > 48000 {
+                Source::Midi
+            } else {
+                Source::Audio
+            };
+            engine.set_settings(settings).unwrap();
+            engine.note_on(30 + (i / 4800 % 12) as u8);
+        }
+        if i % 4800 == 2400 {
+            engine.note_off(30 + (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);
+}
@@ -0,0 +1,25 @@
+[package]
+name = "braze"
+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" }
+braze-core = { path = "../core" }
+braze-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"
@@ -0,0 +1,193 @@
+//! CLAP audio effect. All DSP state is owned by the processing thread.
+mod params;
+use braze_core::{AnalyzerFrame, Engine};
+use crossbeam_queue::ArrayQueue;
+use nih_plug::prelude::*;
+use nih_plug_egui::{create_egui_editor, egui};
+use params::{BrazeParams, FLOATS};
+use std::sync::Arc;
+
+struct EditorData {
+    ui: braze_ui::State,
+    gestures: [bool; FLOATS],
+}
+pub struct Braze {
+    params: Arc<BrazeParams>,
+    analyzer: Arc<ArrayQueue<AnalyzerFrame>>,
+    engine: Option<Engine>,
+    publish_count: usize,
+    publish_interval: usize,
+}
+impl Default for Braze {
+    fn default() -> Self {
+        Self {
+            params: Arc::new(BrazeParams::default()),
+            analyzer: Arc::new(ArrayQueue::new(2)),
+            engine: None,
+            publish_count: 0,
+            publish_interval: 1600,
+        }
+    }
+}
+impl Plugin for Braze {
+    const NAME: &'static str = "Braze";
+    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 analyzer = self.analyzer.clone();
+        create_egui_editor(
+            params.editor.clone(),
+            EditorData {
+                ui: braze_ui::State::default(),
+                gestures: [false; FLOATS],
+            },
+            |ctx, _| braze_ui::style(ctx),
+            move |ctx, setter, data| {
+                while let Some(frame) = analyzer.pop() {
+                    data.ui.accept_frame(frame);
+                }
+                let before = params.settings();
+                let mut edited = before;
+                nih_plug_egui::resizable_window::ResizableWindow::new("braze-editor")
+                    .min_size(egui::vec2(
+                        braze_ui::WIDTH as f32 - 80.,
+                        braze_ui::HEIGHT as f32 - 40.,
+                    ))
+                    .show(ctx, &params.editor, |ui| {
+                        braze_ui::show(ui, &mut edited, &mut data.ui)
+                    });
+                params.apply(
+                    setter,
+                    &before,
+                    &edited,
+                    data.ui.gesture_active,
+                    &mut data.gestures,
+                );
+                // The playhead follows the transport.
+                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);
+        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 {
+                self.analyzer.force_push(engine.take_analyzer());
+                self.publish_count = 0;
+            }
+        }
+        // The lookahead delay must drain after input stops.
+        ProcessStatus::KeepAlive
+    }
+}
+impl ClapPlugin for Braze {
+    const CLAP_ID: &'static str = "io.narl.bass-foundry.braze";
+    const CLAP_DESCRIPTION: Option<&'static str> =
+        Some("Adds a detuned copy whose beating stays on the tempo grid on every note");
+    const CLAP_MANUAL_URL: Option<&'static str> = None;
+    const CLAP_SUPPORT_URL: Option<&'static str> = None;
+    const CLAP_FEATURES: &'static [ClapFeature] = &[
+        ClapFeature::AudioEffect,
+        ClapFeature::Chorus,
+        ClapFeature::Stereo,
+        ClapFeature::Mono,
+    ];
+}
+nih_export_clap!(Braze);
@@ -0,0 +1,219 @@
+use braze_core::{Rate, Settings, Source, HARMONIC_MAX, LOW_CUT_MAX};
+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 RateParam {
+    #[id = "1-1"]
+    #[name = "1/1"]
+    Whole,
+    #[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,
+    #[id = "1-32"]
+    #[name = "1/32"]
+    ThirtySecond,
+    #[id = "1-4t"]
+    #[name = "1/4T"]
+    QuarterTriplet,
+    #[id = "1-8t"]
+    #[name = "1/8T"]
+    EighthTriplet,
+    #[id = "1-16t"]
+    #[name = "1/16T"]
+    SixteenthTriplet,
+}
+const RATES: [(RateParam, Rate); 9] = [
+    (RateParam::Whole, Rate::Whole),
+    (RateParam::Half, Rate::Half),
+    (RateParam::Quarter, Rate::Quarter),
+    (RateParam::Eighth, Rate::Eighth),
+    (RateParam::Sixteenth, Rate::Sixteenth),
+    (RateParam::ThirtySecond, Rate::ThirtySecond),
+    (RateParam::QuarterTriplet, Rate::QuarterTriplet),
+    (RateParam::EighthTriplet, Rate::EighthTriplet),
+    (RateParam::SixteenthTriplet, Rate::SixteenthTriplet),
+];
+fn to_param(rate: Rate) -> RateParam {
+    RATES
+        .iter()
+        .find(|(_, r)| *r == rate)
+        .map_or(RateParam::Eighth, |(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 BrazeParams {
+    #[persist = "editor"]
+    pub editor: Arc<EguiState>,
+    #[id = "source"]
+    pub source: EnumParam<SourceParam>,
+    #[id = "rate"]
+    pub rate: EnumParam<RateParam>,
+    #[id = "harmonic"]
+    pub harmonic: IntParam,
+    #[id = "depth"]
+    pub depth: FloatParam,
+    #[id = "low_cut"]
+    pub low_cut: FloatParam,
+    #[id = "width"]
+    pub width: FloatParam,
+    #[id = "phase"]
+    pub phase: FloatParam,
+    #[id = "gate"]
+    pub gate: FloatParam,
+    #[id = "snap"]
+    pub snap: BoolParam,
+    #[id = "output"]
+    pub output: FloatParam,
+    #[id = "bypass"]
+    pub bypass: BoolParam,
+}
+impl Default for BrazeParams {
+    fn default() -> Self {
+        let d = Settings::default();
+        Self {
+            editor: EguiState::from_size(braze_ui::WIDTH, braze_ui::HEIGHT),
+            source: EnumParam::new("Pitch source", SourceParam::Audio),
+            rate: EnumParam::new("Rate", to_param(d.rate)),
+            harmonic: IntParam::new(
+                "Harmonic",
+                d.harmonic as i32,
+                IntRange::Linear {
+                    min: 1,
+                    max: HARMONIC_MAX as i32,
+                },
+            ),
+            depth: linear("Depth", d.depth, 0., 100., " %"),
+            low_cut: FloatParam::new(
+                "Low cut",
+                d.low_cut,
+                FloatRange::Skewed {
+                    min: 0.,
+                    max: LOW_CUT_MAX,
+                    factor: FloatRange::skew_factor(-1.),
+                },
+            )
+            .with_unit(" Hz"),
+            width: linear("Width", d.width, 0., 100., " %"),
+            phase: linear("Phase", d.phase, 0., 360., "°"),
+            gate: linear("Gate", d.gate, -60., -20., " dB"),
+            snap: BoolParam::new("Snap to semitone", d.snap),
+            output: linear("Output", d.output, -12., 12., " dB"),
+            bypass: BoolParam::new("Bypass", false).make_bypass(),
+        }
+    }
+}
+impl BrazeParams {
+    pub fn settings(&self) -> Settings {
+        let rate = self.rate.value();
+        Settings {
+            source: match self.source.value() {
+                SourceParam::Audio => Source::Audio,
+                SourceParam::Midi => Source::Midi,
+            },
+            rate: RATES
+                .iter()
+                .find(|(p, _)| *p == rate)
+                .map_or(Rate::Eighth, |(_, r)| *r),
+            harmonic: self.harmonic.value() as u32,
+            depth: self.depth.value(),
+            low_cut: self.low_cut.value(),
+            width: self.width.value(),
+            phase: self.phase.value(),
+            gate: self.gate.value(),
+            snap: self.snap.value(),
+            output: self.output.value(),
+            bypass: self.bypass.value(),
+        }
+    }
+    fn floats(&self) -> [&FloatParam; FLOATS] {
+        [
+            &self.depth,
+            &self.low_cut,
+            &self.width,
+            &self.phase,
+            &self.gate,
+            &self.output,
+        ]
+    }
+    fn values(s: &Settings) -> [f32; FLOATS] {
+        [s.depth, s.low_cut, s.width, s.phase, 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.harmonic != old.harmonic {
+            setter.begin_set_parameter(&self.harmonic);
+            setter.set_parameter(&self.harmonic, new.harmonic as i32);
+            setter.end_set_parameter(&self.harmonic);
+        }
+        if new.rate != old.rate {
+            setter.begin_set_parameter(&self.rate);
+            setter.set_parameter(&self.rate, to_param(new.rate));
+            setter.end_set_parameter(&self.rate);
+        }
+        for (p, a, b) in [
+            (&self.snap, old.snap, new.snap),
+            (&self.bypass, old.bypass, new.bypass),
+        ] {
+            if a != b {
+                setter.begin_set_parameter(p);
+                setter.set_parameter(p, b);
+                setter.end_set_parameter(p);
+            }
+        }
+        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);
+        }
+    }
+}
@@ -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 = &braze::clap_entry;
+        assert!(entry.init.unwrap()(c"braze.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"Braze");
+        assert_eq!(
+            CStr::from_ptr((*descriptor).id),
+            c"io.narl.bass-foundry.braze"
+        );
+        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;
+        // Depth 0 passes the input through the lookahead delay unchanged.
+        envelope.params.insert("depth".into(), ParamValue::F32(0.));
+        envelope.params.insert("width".into(), ParamValue::F32(40.));
+        envelope
+            .params
+            .insert("harmonic".into(), ParamValue::I32(3));
+        envelope
+            .params
+            .insert("rate".into(), ParamValue::String("1-16t".into()));
+        envelope
+            .params
+            .insert("snap".into(), ParamValue::Bool(true));
+        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;
+            // About 67 ms lookahead: two periods of the lowest detected note (30 Hz).
+            assert!((delay as f64 / rate - 0.067).abs() < 0.01, "{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 depth 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()();
+    }
+}
@@ -0,0 +1,11 @@
+[package]
+name = "braze-ui"
+version = "0.1.0"
+edition.workspace = true
+license.workspace = true
+
+[dependencies]
+egui = "0.31.1"
+braze-core = { path = "../core" }
+common-ui = { path = "../../common/ui" }
+common-dsp = { path = "../../common/dsp" }
@@ -0,0 +1,410 @@
+//! Braze editor, shared by the CLAP wrapper and the headless renderer.
+use braze_core::{
+    cycles, envelope, AnalyzerFrame, Rate, Settings, Source, HARMONIC_MAX, LOW_CUT_MAX, LOW_CUT_OFF,
+};
+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 = 716;
+
+pub struct State {
+    pub analyzer: AnalyzerFrame,
+    /// 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(),
+            gesture_active: false,
+            help: DEFAULT_HELP.into(),
+        }
+    }
+}
+const DEFAULT_HELP: &str =
+    "Put Braze on a reese or a layered bass. Pick the note value the beating should follow.";
+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,
+    size: f32,
+    help: &str,
+) {
+    ui.vertical_centered(|ui| {
+        let r = rotary(ui, name, value, range, default, unit, size, ACCENT);
+        hint(&r, state, help);
+    });
+}
+
+/// Note value of one beat of harmonic `n`, as a label: "1/8", "1/16T", "1/8D", or "1/40".
+pub fn beat_label(s: &Settings, n: u32) -> String {
+    let quarters = s.rate.quarters() * s.harmonic as f64 / n as f64;
+    let per_whole = 4. / quarters;
+    for den in [1u32, 2, 4, 8, 16, 32, 64, 128] {
+        let d = den as f64;
+        if (per_whole - d).abs() < 1e-6 {
+            return format!("1/{den}");
+        }
+        if (per_whole - d * 1.5).abs() < 1e-6 {
+            return format!("1/{den}T");
+        }
+        if (per_whole - d / 1.5).abs() < 1e-6 {
+            return format!("1/{den}D");
+        }
+    }
+    if (per_whole - per_whole.round()).abs() < 1e-6 {
+        format!("1/{}", per_whole.round())
+    } else {
+        format!("{:.2} beats", quarters)
+    }
+}
+
+/// One bar of the beat of harmonics 1–8, with the beat grid and a playhead.
+fn beats(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);
+    let label_w = 86.;
+    let area = Rect::from_min_max(
+        rect.left_top() + Vec2::new(label_w, 26.),
+        rect.right_bottom() - Vec2::new(12., 10.),
+    );
+    p.text(
+        rect.left_top() + Vec2::new(10., 8.),
+        egui::Align2::LEFT_TOP,
+        "BEAT PER HARMONIC · ONE BAR",
+        FontId::proportional(11.),
+        MUTED,
+    );
+    p.text(
+        rect.right_top() + Vec2::new(-12., 8.),
+        egui::Align2::RIGHT_TOP,
+        if frame.synced {
+            format!("{:.1} BPM · host transport", frame.tempo)
+        } else {
+            format!("{:.1} BPM · free running", frame.tempo)
+        },
+        FontId::proportional(11.),
+        MUTED,
+    );
+    // Grid: every beat of the chosen rate, quarters brighter.
+    let step = settings.rate.quarters();
+    let mut q = 0f64;
+    while q < 4. - 1e-9 {
+        let x = area.left() + area.width() * (q / 4.) as f32;
+        let on_quarter = (q - q.round()).abs() < 1e-6;
+        let color = if on_quarter {
+            Color32::from_rgb(58, 62, 70)
+        } else {
+            Color32::from_rgb(32, 35, 40)
+        };
+        p.line_segment(
+            [Pos2::new(x, area.top()), Pos2::new(x, area.bottom())],
+            Stroke::new(1.0_f32, color),
+        );
+        q += step;
+    }
+    let rows = HARMONIC_MAX as usize;
+    let row_h = area.height() / rows as f32;
+    let depth = settings.depth * 0.01;
+    let points = 240;
+    let bar_start = (frame.beats / 4.).floor() * 4.;
+    for row in 0..rows {
+        let n = row as u32 + 1;
+        let top = area.top() + row_h * row as f32;
+        let chosen = n == settings.harmonic;
+        // Under the low cut the copy is removed: that harmonic keeps the bass's level.
+        let cut = settings.low_cut >= LOW_CUT_OFF
+            && frame.hz > 0.
+            && n as f32 * frame.hz < settings.low_cut;
+        let color = match (cut, chosen) {
+            (true, _) => DIM,
+            (false, true) => ACCENT,
+            (false, false) => STEEL,
+        };
+        p.text(
+            Pos2::new(rect.left() + 10., top + row_h * 0.5),
+            egui::Align2::LEFT_CENTER,
+            format!("H{n}"),
+            FontId::proportional(11.),
+            if chosen { ACCENT } else { MUTED },
+        );
+        p.text(
+            Pos2::new(rect.left() + 36., top + row_h * 0.5),
+            egui::Align2::LEFT_CENTER,
+            if cut {
+                "cut".to_string()
+            } else {
+                beat_label(settings, n)
+            },
+            FontId::monospace(11.),
+            if chosen { TEXT } else { DIM },
+        );
+        let line: Vec<Pos2> = (0..=points)
+            .map(|i| {
+                let t = i as f64 / points as f64;
+                let level = if cut {
+                    1.
+                } else {
+                    envelope(settings, n, cycles(settings, bar_start + 4. * t, 0), depth)
+                };
+                // 0 at the bottom of the row, twice the bass (√2 after correction) at the top.
+                let y = top + row_h * (0.92 - 0.8 * level / 2f32.sqrt());
+                Pos2::new(area.left() + area.width() * t as f32, y)
+            })
+            .collect();
+        p.add(egui::Shape::line(
+            line,
+            Stroke::new(if chosen { 2.0_f32 } else { 1.2_f32 }, color),
+        ));
+    }
+    let head = area.left() + area.width() * ((frame.beats - bar_start) / 4.) as f32;
+    p.line_segment(
+        [Pos2::new(head, area.top()), Pos2::new(head, area.bottom())],
+        Stroke::new(1.0_f32, Color32::from_rgba_unmultiplied(255, 255, 255, 90)),
+    );
+    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, "BRAZE", "TEMPO-LOCKED BEATING", |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();
+        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, "PITCH FROM");
+    });
+    ui.add_space(6.);
+    let frame = state.analyzer;
+    ui.horizontal_top(|ui| {
+        panel(ui, |ui| {
+            ui.set_width(240.);
+            ui.set_min_height(TOP);
+            ui.vertical(|ui| note_panel(ui, settings, &frame));
+        });
+        ui.add_space(4.);
+        panel(ui, |ui| {
+            ui.set_width(ui.available_width());
+            beats(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 note_panel(ui: &mut egui::Ui, settings: &Settings, frame: &AnalyzerFrame) {
+    caption(ui, "NOTE");
+    let (name, hz) = match frame.note {
+        Some(n) if frame.hz > 0. => (common_dsp::note_name(n), format!("{:.1} Hz", frame.hz)),
+        _ => ("—".into(), "no note".into()),
+    };
+    ui.label(
+        RichText::new(name)
+            .font(FontId::new(54., egui::FontFamily::Name("medium".into())))
+            .color(if frame.note.is_some() { TEXT } else { DIM }),
+    );
+    ui.label(RichText::new(hz).monospace().size(14.).color(MUTED));
+    ui.add_space(14.);
+    let beat_hz = frame.tempo / 60. / settings.rate.quarters();
+    readout(
+        ui,
+        &format!("HARMONIC {} BEATS", settings.harmonic),
+        format!("{:.2} Hz, every {}", beat_hz, settings.rate.label()),
+        ACCENT,
+    );
+    if settings.low_cut >= LOW_CUT_OFF
+        && frame.hz > 0.
+        && settings.harmonic as f32 * frame.hz < settings.low_cut
+    {
+        ui.label(
+            RichText::new("Under Low cut on this note: it does not beat. Pick a higher harmonic.")
+                .size(12.)
+                .color(ACCENT),
+        );
+        ui.add_space(6.);
+    }
+    let cents = 1200. * frame.ratio.max(1e-6).log2();
+    readout(
+        ui,
+        "COPY DETUNE ON THIS NOTE",
+        if frame.hz > 0. {
+            format!("+{cents:.1} cents")
+        } else {
+            "waiting for a note".into()
+        },
+        TEXT,
+    );
+    ui.label(
+        RichText::new(format!(
+            "{:.0} ms lookahead · {}",
+            frame.latency as f32 / frame.sample_rate * 1000.,
+            match settings.source {
+                Source::Audio => "detecting pitch",
+                Source::Midi => "following MIDI notes",
+            }
+        ))
+        .size(12.)
+        .color(MUTED),
+    );
+}
+fn controls(ui: &mut egui::Ui, settings: &mut Settings, state: &mut State) {
+    let d = Settings::default();
+    ui.horizontal(|ui| {
+        caption(ui, "RATE");
+        ui.add_space(6.);
+        for rate in Rate::ALL {
+            let r =
+                ui.selectable_label(settings.rate == rate, RichText::new(rate.label()).size(13.));
+            if r.clicked() {
+                settings.rate = rate;
+            }
+            hint(
+                &r,
+                state,
+                "One beat cycle of the chosen harmonic lasts this note value, on every note.",
+            );
+        }
+        ui.add_space(18.);
+        caption(ui, "ON HARMONIC");
+        ui.add_space(6.);
+        for n in 1..=HARMONIC_MAX {
+            let r = ui.selectable_label(
+                settings.harmonic == n,
+                RichText::new(format!("{n}")).size(13.),
+            );
+            if r.clicked() {
+                settings.harmonic = n;
+            }
+            hint(
+                &r,
+                state,
+                "This harmonic beats at Rate. Harmonic n beats n/this times as fast. \
+                 Pick the harmonic you hear the movement on.",
+            );
+        }
+    });
+    ui.add_space(8.);
+    ui.separator();
+    ui.columns(6, |c| {
+        knob(
+            &mut c[0],
+            state,
+            "Depth",
+            &mut settings.depth,
+            0. ..=100.,
+            d.depth,
+            " %",
+            72.,
+            "Level of the detuned copy. 100 % beats down to full nulls; 0 % is the dry bass.",
+        );
+        knob(
+            &mut c[1],
+            state,
+            "Low cut",
+            &mut settings.low_cut,
+            0. ..=LOW_CUT_MAX,
+            d.low_cut,
+            " Hz",
+            72.,
+            "No copy below this frequency: the sub does not beat and keeps its level. \
+             Under 20 Hz the cut is off.",
+        );
+        knob(
+            &mut c[2],
+            state,
+            "Width",
+            &mut settings.width,
+            0. ..=100.,
+            d.width,
+            " %",
+            72.,
+            "Moves the right channel's beat against the left. 100 %: one side peaks while \
+             the other nulls. Check the mono sum.",
+        );
+        knob(
+            &mut c[3],
+            state,
+            "Phase",
+            &mut settings.phase,
+            0. ..=360.,
+            d.phase,
+            "°",
+            72.,
+            "Where the beat peaks. 0° puts the peak of the chosen harmonic on the beat.",
+        );
+        knob(
+            &mut c[4],
+            state,
+            "Gate",
+            &mut settings.gate,
+            -60. ..=-20.,
+            d.gate,
+            " dB",
+            72.,
+            "Input level that counts as a note. Raise it if tails retrigger.",
+        );
+        knob(
+            &mut c[5],
+            state,
+            "Output",
+            &mut settings.output,
+            -12. ..=12.,
+            d.output,
+            " dB",
+            72.,
+            "Output trim.",
+        );
+    });
+    ui.add_space(4.);
+    let r = ui.selectable_label(settings.snap, RichText::new("SNAP TO SEMITONE").size(13.));
+    if r.clicked() {
+        settings.snap = !settings.snap;
+    }
+    hint(
+        &r,
+        state,
+        "Round the detected pitch. Off keeps the copy's jumps on the real period, which is \
+         seamless on detuned patches.",
+    );
+}
@@ -6,7 +6,7 @@
    "library": "rivet",
    "documentation": "docs/rivet",
    "standalone": "rivet",
-    "clap_id": "io.storyboard.motif",
+    "clap_id": "io.narl.bass-foundry.rivet",
    "packages": [
      "rivet-core",
      "rivet-midi",
@@ -20,14 +20,207 @@
    "manifest": "plugins/patina/plugin/Cargo.toml",
    "library": "patina",
    "documentation": "docs/patina",
-    "clap_id": "io.storyboard.resonance-compressor",
+    "clap_id": "io.narl.bass-foundry.patina",
    "licenses": {
-      "plugins/patina/ui/assets/OFL.txt": "licenses/Roboto-OFL.txt"
+      "plugins/common/ui/assets/OFL.txt": "licenses/Roboto-OFL.txt"
    },
    "packages": [
+      "common-ui",
+      "common-dsp",
      "patina-core",
      "patina-ui",
      "patina-render"
    ]
+  },
+  "anvil": {
+    "name": "Anvil",
+    "description": "Replace the sub with a clean sine at one level and phase for every note",
+    "manifest": "plugins/anvil/plugin/Cargo.toml",
+    "library": "anvil",
+    "documentation": "docs/anvil",
+    "clap_id": "io.narl.bass-foundry.anvil",
+    "licenses": {
+      "plugins/common/ui/assets/OFL.txt": "licenses/Roboto-OFL.txt"
+    },
+    "packages": [
+      "common-ui",
+      "common-dsp",
+      "anvil-core",
+      "anvil-ui"
+    ]
+  },
+  "crucible": {
+    "name": "Crucible",
+    "description": "Capture the last bars, slice them and export clean, key-labelled samples",
+    "manifest": "plugins/crucible/plugin/Cargo.toml",
+    "library": "crucible",
+    "documentation": "docs/crucible",
+    "clap_id": "io.narl.bass-foundry.crucible",
+    "licenses": {
+      "plugins/common/ui/assets/OFL.txt": "licenses/Roboto-OFL.txt"
+    },
+    "packages": [
+      "common-ui",
+      "common-dsp",
+      "crucible-core",
+      "crucible-ui"
+    ]
+  },
+  "lathe": {
+    "name": "Lathe",
+    "description": "EQ the harmonics of the played note: a cut on harmonic 3 stays on harmonic 3",
+    "manifest": "plugins/lathe/plugin/Cargo.toml",
+    "library": "lathe",
+    "documentation": "docs/lathe",
+    "clap_id": "io.narl.bass-foundry.lathe",
+    "licenses": {
+      "plugins/common/ui/assets/OFL.txt": "licenses/Roboto-OFL.txt"
+    },
+    "packages": [
+      "common-ui",
+      "common-dsp",
+      "lathe-core",
+      "lathe-ui"
+    ]
+  },
+  "temper": {
+    "name": "Temper",
+    "description": "Distortion whose drive and tone filters follow the note, so every note distorts the same",
+    "manifest": "plugins/temper/plugin/Cargo.toml",
+    "library": "temper",
+    "documentation": "docs/temper",
+    "clap_id": "io.narl.bass-foundry.temper",
+    "licenses": {
+      "plugins/common/ui/assets/OFL.txt": "licenses/Roboto-OFL.txt"
+    },
+    "packages": [
+      "common-ui",
+      "common-dsp",
+      "temper-core",
+      "temper-ui"
+    ]
+  },
+  "weld": {
+    "name": "Weld",
+    "description": "Align the phase of a bass layer to a sidechain layer so the two sum instead of cancel",
+    "manifest": "plugins/weld/plugin/Cargo.toml",
+    "library": "weld",
+    "documentation": "docs/weld",
+    "clap_id": "io.narl.bass-foundry.weld",
+    "licenses": {
+      "plugins/common/ui/assets/OFL.txt": "licenses/Roboto-OFL.txt"
+    },
+    "packages": [
+      "common-ui",
+      "weld-core",
+      "weld-ui"
+    ]
+  },
+  "knurl": {
+    "name": "Knurl",
+    "description": "Give every cycle of the note its own level, timing and grit",
+    "manifest": "plugins/knurl/plugin/Cargo.toml",
+    "library": "knurl",
+    "documentation": "docs/knurl",
+    "clap_id": "io.narl.bass-foundry.knurl",
+    "licenses": {
+      "plugins/common/ui/assets/OFL.txt": "licenses/Roboto-OFL.txt"
+    },
+    "packages": [
+      "common-ui",
+      "knurl-core",
+      "knurl-ui"
+    ]
+  },
+  "planish": {
+    "name": "Planish",
+    "description": "Upward and downward compression in bands set by harmonic number, the same on every note",
+    "manifest": "plugins/planish/plugin/Cargo.toml",
+    "library": "planish",
+    "documentation": "docs/planish",
+    "clap_id": "io.narl.bass-foundry.planish",
+    "licenses": {
+      "plugins/common/ui/assets/OFL.txt": "licenses/Roboto-OFL.txt"
+    },
+    "packages": [
+      "common-ui",
+      "common-dsp",
+      "planish-core",
+      "planish-ui"
+    ]
+  },
+  "braze": {
+    "name": "Braze",
+    "description": "Adds a detuned copy whose beating stays on the tempo grid on every note",
+    "manifest": "plugins/braze/plugin/Cargo.toml",
+    "library": "braze",
+    "documentation": "docs/braze",
+    "clap_id": "io.narl.bass-foundry.braze",
+    "licenses": {
+      "plugins/common/ui/assets/OFL.txt": "licenses/Roboto-OFL.txt"
+    },
+    "packages": [
+      "common-ui",
+      "common-dsp",
+      "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"
+    ]
+  },
+  "forge": {
+    "name": "Forge",
+    "description": "One tracked channel strip: Lathe, Temper and Knurl behind one note tracker, in any order",
+    "manifest": "plugins/forge/plugin/Cargo.toml",
+    "library": "forge",
+    "documentation": "docs/forge",
+    "clap_id": "io.narl.bass-foundry.forge",
+    "licenses": {
+      "plugins/common/ui/assets/OFL.txt": "licenses/Roboto-OFL.txt"
+    },
+    "packages": [
+      "common-ui",
+      "common-dsp",
+      "forge-core",
+      "forge-ui",
+      "lathe-core",
+      "lathe-ui",
+      "temper-core",
+      "temper-ui",
+      "knurl-core",
+      "knurl-ui"
+    ]
  }
 }
@@ -0,0 +1,7 @@
+[package]
+name = "common-dsp"
+version = "0.1.0"
+edition.workspace = true
+license.workspace = true
+
+[dependencies]
@@ -0,0 +1,268 @@
+//! Shared allocation-free DSP building blocks: filters, pitch detection, notes, WAV files.
+pub mod loudness;
+pub mod meter;
+pub mod oversample;
+pub mod svf;
+pub mod tracker;
+pub mod wav;
+
+use std::f32::consts::TAU;
+
+/// Transposed direct form II biquad (RBJ cookbook coefficients).
+#[derive(Clone, Copy, Debug, Default)]
+pub struct Biquad {
+    b0: f32,
+    b1: f32,
+    b2: f32,
+    a1: f32,
+    a2: f32,
+    z1: f32,
+    z2: f32,
+}
+impl Biquad {
+    fn from(b: [f32; 3], a: [f32; 3]) -> Self {
+        Self {
+            b0: b[0] / a[0],
+            b1: b[1] / a[0],
+            b2: b[2] / a[0],
+            a1: a[1] / a[0],
+            a2: a[2] / a[0],
+            z1: 0.,
+            z2: 0.,
+        }
+    }
+    pub fn lowpass(rate: f32, hz: f32, q: f32) -> Self {
+        let w = TAU * (hz / rate).clamp(1e-5, 0.49);
+        let (s, c) = w.sin_cos();
+        let alpha = s / (2. * q);
+        Self::from(
+            [(1. - c) / 2., 1. - c, (1. - c) / 2.],
+            [1. + alpha, -2. * c, 1. - alpha],
+        )
+    }
+    pub fn highpass(rate: f32, hz: f32, q: f32) -> Self {
+        let w = TAU * (hz / rate).clamp(1e-5, 0.49);
+        let (s, c) = w.sin_cos();
+        let alpha = s / (2. * q);
+        Self::from(
+            [(1. + c) / 2., -(1. + c), (1. + c) / 2.],
+            [1. + alpha, -2. * c, 1. - alpha],
+        )
+    }
+    /// Peaking EQ; used by tests to model resonant material.
+    pub fn peak(rate: f32, hz: f32, q: f32, gain_db: f32) -> Self {
+        let w = TAU * (hz / rate).clamp(1e-5, 0.49);
+        let (s, c) = w.sin_cos();
+        let a = 10f32.powf(gain_db / 40.);
+        let alpha = s / (2. * q);
+        Self::from(
+            [1. + alpha * a, -2. * c, 1. - alpha * a],
+            [1. + alpha / a, -2. * c, 1. - alpha / a],
+        )
+    }
+    /// Replace the coefficients and keep the filter state, for smooth parameter changes.
+    pub fn retune(&mut self, other: Self) {
+        let (z1, z2) = (self.z1, self.z2);
+        *self = other;
+        self.z1 = z1;
+        self.z2 = z2;
+    }
+    #[inline]
+    pub fn process(&mut self, x: f32) -> f32 {
+        let y = self.b0 * x + self.z1;
+        self.z1 = self.b1 * x - self.a1 * y + self.z2;
+        self.z2 = self.b2 * x - self.a2 * y;
+        y
+    }
+    pub fn reset(&mut self) {
+        self.z1 = 0.;
+        self.z2 = 0.;
+    }
+}
+
+/// Fourth-order Linkwitz–Riley crossover. Low plus high is an allpass: flat magnitude.
+#[derive(Clone, Copy, Debug, Default)]
+pub struct Crossover {
+    low: [Biquad; 2],
+    high: [Biquad; 2],
+}
+impl Crossover {
+    pub fn new(rate: f32, hz: f32) -> Self {
+        let q = std::f32::consts::FRAC_1_SQRT_2;
+        Self {
+            low: [Biquad::lowpass(rate, hz, q); 2],
+            high: [Biquad::highpass(rate, hz, q); 2],
+        }
+    }
+    pub fn retune(&mut self, rate: f32, hz: f32) {
+        let fresh = Self::new(rate, hz);
+        for i in 0..2 {
+            self.low[i].retune(fresh.low[i]);
+            self.high[i].retune(fresh.high[i]);
+        }
+    }
+    /// Returns (low, high).
+    #[inline]
+    pub fn process(&mut self, x: f32) -> (f32, f32) {
+        let low = self.low[0].process(x);
+        let low = self.low[1].process(low);
+        let high = self.high[0].process(x);
+        let high = self.high[1].process(high);
+        // LR4 bands are in phase at the crossover point, so they sum to an allpass.
+        (low, high)
+    }
+    pub fn reset(&mut self) {
+        for f in self.low.iter_mut().chain(self.high.iter_mut()) {
+            f.reset();
+        }
+    }
+}
+
+/// YIN fundamental-frequency estimator with preallocated scratch.
+pub struct Yin {
+    diff: Vec<f32>,
+    pub threshold: f32,
+}
+impl Yin {
+    /// `max_lag` is the longest period in samples that will ever be requested.
+    pub fn new(max_lag: usize) -> Self {
+        Self {
+            diff: vec![0.; max_lag + 2],
+            threshold: 0.15,
+        }
+    }
+    pub fn max_lag(&self) -> usize {
+        self.diff.len() - 2
+    }
+    /// Estimates the fundamental of `x` in Hz with its clarity (1 = perfectly periodic).
+    /// `x` must hold at least twice the longest period. Never allocates.
+    pub fn estimate(
+        &mut self,
+        x: &[f32],
+        rate: f32,
+        min_hz: f32,
+        max_hz: f32,
+    ) -> Option<(f32, f32)> {
+        let hi = ((rate / min_hz).ceil() as usize).min(self.max_lag());
+        let lo = ((rate / max_hz).floor() as usize).max(2);
+        if hi <= lo + 2 || x.len() < hi + 2 {
+            return None;
+        }
+        let window = x.len() - hi - 1;
+        if window < hi {
+            return None;
+        }
+        let energy: f32 = x[..window].iter().map(|v| v * v).sum();
+        if energy < 1e-9 * window as f32 {
+            return None;
+        }
+        let d = &mut self.diff;
+        d[0] = 1.;
+        let mut running = 0.;
+        for tau in 1..=hi + 1 {
+            let mut s = 0.;
+            for j in 0..window {
+                let e = x[j] - x[j + tau];
+                s += e * e;
+            }
+            running += s;
+            // Cumulative-mean normalisation: suppresses the zero-lag dip.
+            d[tau] = if running > 0. {
+                s * tau as f32 / running
+            } else {
+                1.
+            };
+        }
+        let mut best = None;
+        let mut tau = lo;
+        while tau < hi {
+            if d[tau] < self.threshold {
+                while tau + 1 < hi && d[tau + 1] < d[tau] {
+                    tau += 1;
+                }
+                best = Some(tau);
+                break;
+            }
+            tau += 1;
+        }
+        let tau = match best {
+            Some(t) => t,
+            None => {
+                let (t, v) = (lo..hi)
+                    .map(|t| (t, d[t]))
+                    .min_by(|a, b| a.1.total_cmp(&b.1))?;
+                if v > 0.35 {
+                    return None;
+                }
+                t
+            }
+        };
+        let (a, b, c) = (d[tau - 1], d[tau], d[tau + 1]);
+        let denom = a - 2. * b + c;
+        let shift = if denom.abs() > 1e-12 {
+            (0.5 * (a - c) / denom).clamp(-1., 1.)
+        } else {
+            0.
+        };
+        Some((rate / (tau as f32 + shift), (1. - b).clamp(0., 1.)))
+    }
+}
+
+pub fn midi_to_hz(note: f32) -> f32 {
+    440. * 2f32.powf((note - 69.) / 12.)
+}
+pub fn hz_to_midi(hz: f32) -> f32 {
+    69. + 12. * (hz.max(1e-3) / 440.).log2()
+}
+/// Scientific note name: MIDI 60 = C4, 43.65 Hz = F1. FL Studio labels MIDI 60 as C5.
+pub fn note_name(note: u8) -> String {
+    const NAMES: [&str; 12] = [
+        "C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B",
+    ];
+    format!("{}{}", NAMES[note as usize % 12], note as i32 / 12 - 1)
+}
+pub fn db_to_gain(db: f32) -> f32 {
+    10f32.powf(db / 20.)
+}
+pub fn gain_to_db(g: f32) -> f32 {
+    20. * g.abs().max(1e-9).log10()
+}
+/// One-pole smoothing coefficient for a time constant in milliseconds.
+pub fn coefficient(rate: f32, ms: f32) -> f32 {
+    if ms <= 0. {
+        1.
+    } else {
+        1. - (-1. / (rate * ms * 0.001)).exp()
+    }
+}
+/// PolyBLEP sawtooth oscillator: cheap and close to band-limited, for tests and previews.
+pub struct Saw {
+    phase: f32,
+    inc: f32,
+}
+impl Saw {
+    pub fn new(rate: f32, hz: f32) -> Self {
+        Self {
+            phase: 0.,
+            inc: hz / rate,
+        }
+    }
+    pub fn sample(&mut self) -> f32 {
+        let t = self.phase;
+        let dt = self.inc;
+        let blep = if t < dt {
+            let x = t / dt;
+            x + x - x * x - 1.
+        } else if t > 1. - dt {
+            let x = (t - 1.) / dt;
+            x * x + x + x + 1.
+        } else {
+            0.
+        };
+        self.phase += dt;
+        if self.phase >= 1. {
+            self.phase -= 1.;
+        }
+        2. * t - 1. - blep
+    }
+}
@@ -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
+}
@@ -0,0 +1,91 @@
+//! Levels of the harmonics of a known fundamental, measured with Hann-windowed Goertzel
+//! filters. Work is spread evenly over the samples, so there is no per-window spike.
+use std::f32::consts::TAU;
+
+pub const HARMONICS: usize = 32;
+
+pub struct HarmonicMeter {
+    rate: f32,
+    window: Vec<f32>,
+    count: usize,
+    hz: f32,
+    coef: [f32; HARMONICS],
+    s1: [f32; HARMONICS],
+    s2: [f32; HARMONICS],
+    levels: [f32; HARMONICS],
+}
+impl HarmonicMeter {
+    /// Window of about `ms`; 85 ms resolves harmonics of fundamentals down to 30 Hz.
+    pub fn new(rate: f32, ms: f32) -> Self {
+        let n = ((rate * ms * 0.001) as usize).max(64);
+        Self {
+            rate,
+            window: (0..n)
+                .map(|i| 0.5 - 0.5 * (TAU * i as f32 / n as f32).cos())
+                .collect(),
+            count: 0,
+            hz: 0.,
+            coef: [0.; HARMONICS],
+            s1: [0.; HARMONICS],
+            s2: [0.; HARMONICS],
+            levels: [-120.; HARMONICS],
+        }
+    }
+    /// Peak level in dBFS of each harmonic (index 0 is the fundamental) from the last
+    /// complete window. Harmonics above 0.45 × the sample rate read −120.
+    pub fn levels(&self) -> &[f32; HARMONICS] {
+        &self.levels
+    }
+    /// Fundamental of the last complete window, 0 if none.
+    pub fn hz(&self) -> f32 {
+        self.hz
+    }
+    /// Feeds one sample. `hz` is read at the start of each window (0 = no note: skip it).
+    /// Returns true when a window completed and `levels` changed.
+    #[inline]
+    pub fn push(&mut self, x: f32, hz: f32) -> bool {
+        if self.count == 0 {
+            self.hz = hz;
+            for k in 0..HARMONICS {
+                let f = hz * (k + 1) as f32;
+                self.coef[k] = if hz > 0. && f < 0.45 * self.rate {
+                    2. * (TAU * f / self.rate).cos()
+                } else {
+                    0.
+                };
+            }
+            self.s1 = [0.; HARMONICS];
+            self.s2 = [0.; HARMONICS];
+        }
+        let w = x * self.window[self.count];
+        for k in 0..HARMONICS {
+            let s = w + self.coef[k] * self.s1[k] - self.s2[k];
+            self.s2[k] = self.s1[k];
+            self.s1[k] = s;
+        }
+        self.count += 1;
+        if self.count < self.window.len() {
+            return false;
+        }
+        self.count = 0;
+        let n = self.window.len() as f32;
+        for k in 0..HARMONICS {
+            let f = self.hz * (k + 1) as f32;
+            self.levels[k] = if self.hz > 0. && f < 0.45 * self.rate {
+                let c = self.coef[k];
+                let p =
+                    self.s1[k] * self.s1[k] + self.s2[k] * self.s2[k] - c * self.s1[k] * self.s2[k];
+                // Hann coherent gain is 0.5: a sine of peak A gives |X| = A·N/4.
+                let amp = 4. * p.max(0.).sqrt() / n;
+                20. * amp.max(1e-6).log10()
+            } else {
+                -120.
+            };
+        }
+        true
+    }
+    pub fn reset(&mut self) {
+        self.count = 0;
+        self.levels = [-120.; HARMONICS];
+    }
+}
@@ -0,0 +1,131 @@
+//! 4× oversampling with two linear-phase half-band FIR stages. The round trip (up, then
+//! down) delays the signal by a whole number of base-rate samples, `latency()`.
+const STAGE1_HALF: usize = 31; // 63 taps at 2×: steep, carries the audio band edge
+const STAGE2_HALF: usize = 11; // 23 taps at 4×: the band edge is far from its images
+const BETA: f32 = 9.;
+
+/// Kaiser-windowed half-band lowpass with gain `gain`, `2 * half + 1` taps.
+fn halfband(half: usize, gain: f32) -> Vec<f32> {
+    fn i0(x: f32) -> f32 {
+        let (mut sum, mut term) = (1f64, 1f64);
+        let y = (x as f64 / 2.).powi(2);
+        for k in 1..50 {
+            term *= y / (k * k) as f64;
+            sum += term;
+        }
+        sum as f32
+    }
+    let n = 2 * half + 1;
+    let norm = i0(BETA);
+    let mut h: Vec<f32> = (0..n)
+        .map(|i| {
+            let m = i as f32 - half as f32;
+            let sinc = if m == 0. {
+                0.5
+            } else {
+                (std::f32::consts::FRAC_PI_2 * m).sin() / (std::f32::consts::PI * m)
+            };
+            let r = m / half as f32;
+            sinc * i0(BETA * (1. - r * r).max(0.).sqrt()) / norm
+        })
+        .collect();
+    let sum: f32 = h.iter().sum();
+    for v in &mut h {
+        *v *= gain / sum;
+    }
+    h
+}
+
+/// FIR with a doubled circular buffer so every convolution reads one contiguous slice.
+struct Fir {
+    taps: Vec<f32>,
+    buf: Vec<f32>,
+    at: usize,
+}
+impl Fir {
+    fn new(taps: Vec<f32>) -> Self {
+        let n = taps.len();
+        Self {
+            taps,
+            buf: vec![0.; 2 * n],
+            at: 0,
+        }
+    }
+    #[inline]
+    fn process(&mut self, x: f32) -> f32 {
+        let n = self.taps.len();
+        self.at = if self.at == 0 { n - 1 } else { self.at - 1 };
+        self.buf[self.at] = x;
+        self.buf[self.at + n] = x;
+        let window = &self.buf[self.at..self.at + n];
+        window.iter().zip(&self.taps).map(|(a, b)| a * b).sum()
+    }
+    fn reset(&mut self) {
+        self.buf.fill(0.);
+        self.at = 0;
+    }
+}
+
+/// One channel of 4× oversampling. Allocation-free after `new`.
+pub struct Oversampler {
+    up1: Fir,
+    up2: Fir,
+    down2: Fir,
+    down1: Fir,
+    /// Two samples at 4× make the round trip a whole number of base samples.
+    pad: [f32; 2],
+}
+impl Default for Oversampler {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+impl Oversampler {
+    pub const FACTOR: usize = 4;
+    pub fn new() -> Self {
+        Self {
+            up1: Fir::new(halfband(STAGE1_HALF, 2.)),
+            up2: Fir::new(halfband(STAGE2_HALF, 2.)),
+            down2: Fir::new(halfband(STAGE2_HALF, 1.)),
+            down1: Fir::new(halfband(STAGE1_HALF, 1.)),
+            pad: [0.; 2],
+        }
+    }
+    /// Round-trip delay in base-rate samples.
+    pub const fn latency() -> usize {
+        STAGE1_HALF + STAGE2_HALF.div_ceil(2)
+    }
+    #[inline]
+    pub fn up(&mut self, x: f32) -> [f32; 4] {
+        let a = self.up1.process(x);
+        let b = self.up1.process(0.);
+        let mut out = [
+            self.up2.process(a),
+            self.up2.process(0.),
+            self.up2.process(b),
+            self.up2.process(0.),
+        ];
+        // Delay by two 4× samples.
+        let [p0, p1] = self.pad;
+        self.pad = [out[2], out[3]];
+        out = [p0, p1, out[0], out[1]];
+        out
+    }
+    #[inline]
+    pub fn down(&mut self, y: [f32; 4]) -> f32 {
+        let a = self.down2.process(y[0]);
+        self.down2.process(y[1]);
+        let b = self.down2.process(y[2]);
+        self.down2.process(y[3]);
+        let out = self.down1.process(a);
+        self.down1.process(b);
+        out
+    }
+    pub fn reset(&mut self) {
+        self.up1.reset();
+        self.up2.reset();
+        self.down2.reset();
+        self.down1.reset();
+        self.pad = [0.; 2];
+    }
+}
@@ -0,0 +1,121 @@
+//! Trapezoidal state-variable filter (Simper/Cytomic). Stable and click-free under fast
+//! retuning, so it can follow a gliding note. Coefficients are separate from state, so one
+//! set can drive both channels.
+use std::f32::consts::PI;
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct SvfCoef {
+    a1: f32,
+    a2: f32,
+    a3: f32,
+    m0: f32,
+    m1: f32,
+    m2: f32,
+}
+impl Default for SvfCoef {
+    /// Identity: passes the input unchanged.
+    fn default() -> Self {
+        Self::IDENTITY
+    }
+}
+impl SvfCoef {
+    pub const IDENTITY: Self = Self {
+        a1: 1.,
+        a2: 0.,
+        a3: 0.,
+        m0: 1.,
+        m1: 0.,
+        m2: 0.,
+    };
+    fn base(rate: f32, hz: f32, k: f32, warp: f32) -> (f32, f32, f32) {
+        let g = (PI * (hz / rate).clamp(1e-6, 0.49)).tan() * warp;
+        let a1 = 1. / (1. + g * (g + k));
+        let a2 = g * a1;
+        (a1, a2, g * a2)
+    }
+    /// Peaking filter. At 0 dB it is an exact identity.
+    pub fn bell(rate: f32, hz: f32, q: f32, gain_db: f32) -> Self {
+        let a = 10f32.powf(gain_db / 40.);
+        let k = 1. / (q.max(1e-3) * a);
+        let (a1, a2, a3) = Self::base(rate, hz, k, 1.);
+        Self {
+            a1,
+            a2,
+            a3,
+            m0: 1.,
+            m1: k * (a * a - 1.),
+            m2: 0.,
+        }
+    }
+    pub fn lowpass(rate: f32, hz: f32, q: f32) -> Self {
+        let (a1, a2, a3) = Self::base(rate, hz, 1. / q.max(1e-3), 1.);
+        Self {
+            a1,
+            a2,
+            a3,
+            m0: 0.,
+            m1: 0.,
+            m2: 1.,
+        }
+    }
+    pub fn highpass(rate: f32, hz: f32, q: f32) -> Self {
+        let k = 1. / q.max(1e-3);
+        let (a1, a2, a3) = Self::base(rate, hz, k, 1.);
+        Self {
+            a1,
+            a2,
+            a3,
+            m0: 1.,
+            m1: -k,
+            m2: -1.,
+        }
+    }
+    /// Second-order allpass. With `q` = 1/√2 it has the phase of a Linkwitz–Riley crossover
+    /// built from two lowpass and two highpass stages at the same frequency, so it keeps
+    /// the bands of a crossover tree in phase.
+    pub fn allpass(rate: f32, hz: f32, q: f32) -> Self {
+        let k = 1. / q.max(1e-3);
+        let (a1, a2, a3) = Self::base(rate, hz, k, 1.);
+        Self {
+            a1,
+            a2,
+            a3,
+            m0: 1.,
+            m1: -2. * k,
+            m2: 0.,
+        }
+    }
+    pub fn high_shelf(rate: f32, hz: f32, q: f32, gain_db: f32) -> Self {
+        let a = 10f32.powf(gain_db / 40.);
+        let k = 1. / q.max(1e-3);
+        let (a1, a2, a3) = Self::base(rate, hz, k, a.sqrt());
+        Self {
+            a1,
+            a2,
+            a3,
+            m0: a * a,
+            m1: k * (1. - a) * a,
+            m2: 1. - a * a,
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, Default)]
+pub struct Svf {
+    ic1: f32,
+    ic2: f32,
+}
+impl Svf {
+    #[inline]
+    pub fn process(&mut self, c: &SvfCoef, v0: f32) -> f32 {
+        let v3 = v0 - self.ic2;
+        let v1 = c.a1 * self.ic1 + c.a2 * v3;
+        let v2 = self.ic2 + c.a2 * self.ic1 + c.a3 * v3;
+        self.ic1 = 2. * v1 - self.ic1;
+        self.ic2 = 2. * v2 - self.ic2;
+        c.m0 * v0 + c.m1 * v1 + c.m2 * v2
+    }
+    pub fn reset(&mut self) {
+        *self = Self::default();
+    }
+}
@@ -0,0 +1,451 @@
+//! Note tracker with lookahead: pitch and note starts of a monophonic bass, from audio or MIDI.
+//!
+//! Detection runs on the undelayed input. Events are reported at *output* time, `latency()`
+//! samples later, so a host that delays its audio path by the same amount sees each note start
+//! exactly on its attack, with the pitch already known.
+use crate::{coefficient, gain_to_db, hz_to_midi, Biquad, Yin};
+
+const EVENTS: usize = 64;
+const HOP_MS: f32 = 5.;
+const GATE_HOLD_MS: f32 = 20.;
+const GATE_HYSTERESIS_DB: f32 = 6.;
+/// A pitch move this large (semitones) counts as a new note.
+const JUMP: f32 = 0.7;
+const CLARITY: f32 = 0.5;
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct TrackerConfig {
+    /// Lowest detectable fundamental. Sets the lookahead (two periods plus a margin).
+    pub min_hz: f32,
+    pub max_hz: f32,
+    /// Lowpass in front of detection, removing upper harmonics that confuse YIN.
+    pub detect_lowpass: f32,
+    /// Approximate decimated analysis rate.
+    pub detect_rate: f32,
+}
+impl TrackerConfig {
+    /// Sub range: 25–250 Hz.
+    pub const SUB: Self = Self {
+        min_hz: 25.,
+        max_hz: 250.,
+        detect_lowpass: 400.,
+        detect_rate: 3000.,
+    };
+    /// Bass range for harmonic tools: 30–500 Hz.
+    pub const BASS: Self = Self {
+        min_hz: 30.,
+        max_hz: 500.,
+        detect_lowpass: 1000.,
+        detect_rate: 6000.,
+    };
+}
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub enum NoteEvent {
+    /// A new note. `glide` asks to slide from the previous pitch instead of restarting.
+    Start {
+        pitch: f32,
+        glide: bool,
+    },
+    /// The sounding note's smoothed pitch moved within a semitone (bends, vibrato).
+    Move {
+        pitch: f32,
+    },
+    Stop,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+enum Kind {
+    Onset,
+    Release,
+    NoteOn(u8),
+    NoteOff(u8),
+}
+#[derive(Clone, Copy, Debug)]
+struct Event {
+    time: u64,
+    kind: Kind,
+}
+
+/// Allocation-free after `new`. Pitches are fractional MIDI notes.
+pub struct Tracker {
+    rate: f32,
+    cfg: TrackerConfig,
+    latency: usize,
+    midi: bool,
+    gate_db: f32,
+    glide: bool,
+    detect: [Biquad; 2],
+    decimate: usize,
+    decimate_count: usize,
+    detect_rate: f32,
+    ring: Vec<f32>,
+    ring_at: usize,
+    scratch: Vec<f32>,
+    yin: Yin,
+    hop: usize,
+    hop_count: usize,
+    gate_env: f32,
+    gate_release: f32,
+    gate_open: bool,
+    gate_hold: usize,
+    clock: u64,
+    events: [Event; EVENTS],
+    event_head: usize,
+    event_len: usize,
+    /// Output-time note state.
+    sounding: bool,
+    pending: bool,
+    tracked: f32,
+    candidate: Option<(f32, u8)>,
+    held: [u8; 16],
+    held_len: usize,
+}
+
+impl Tracker {
+    pub fn new(rate: f32, cfg: TrackerConfig) -> Self {
+        let decimate = (rate / cfg.detect_rate).round().max(1.) as usize;
+        let detect_rate = rate / decimate as f32;
+        let max_lag = (detect_rate / cfg.min_hz).ceil() as usize;
+        // YIN needs one comparison window of at least the longest period after the lags.
+        let analysis = 2 * max_lag + 3;
+        let q = std::f32::consts::FRAC_1_SQRT_2;
+        Self {
+            rate,
+            cfg,
+            latency: analysis * decimate,
+            midi: false,
+            gate_db: -42.,
+            glide: false,
+            detect: [Biquad::lowpass(rate, cfg.detect_lowpass, q); 2],
+            decimate,
+            decimate_count: 0,
+            detect_rate,
+            ring: vec![0.; analysis],
+            ring_at: 0,
+            scratch: vec![0.; analysis],
+            yin: Yin::new(max_lag + 2),
+            hop: ((detect_rate * HOP_MS * 0.001) as usize).max(1),
+            hop_count: 0,
+            gate_env: 0.,
+            gate_release: 1. - coefficient(rate, 30.),
+            gate_open: false,
+            gate_hold: 0,
+            clock: 0,
+            events: [Event {
+                time: 0,
+                kind: Kind::Release,
+            }; EVENTS],
+            event_head: 0,
+            event_len: 0,
+            sounding: false,
+            pending: false,
+            tracked: 0.,
+            candidate: None,
+            held: [0; 16],
+            held_len: 0,
+        }
+    }
+    /// Lookahead in samples. Delay the audio path by exactly this much.
+    pub fn latency(&self) -> usize {
+        self.latency
+    }
+    pub fn config(&self) -> TrackerConfig {
+        self.cfg
+    }
+    /// `midi` selects note input over detection; `gate_db` is the detection threshold;
+    /// `glide` lets legato notes slide. Returns true when the source changed, which drops
+    /// every pending and held note: the caller should release its sound.
+    pub fn set(&mut self, midi: bool, gate_db: f32, glide: bool) -> bool {
+        let changed = midi != self.midi;
+        self.midi = midi;
+        self.gate_db = gate_db;
+        self.glide = glide;
+        if changed {
+            self.release_all();
+        }
+        changed
+    }
+    fn release_all(&mut self) {
+        self.sounding = false;
+        self.pending = false;
+        self.held_len = 0;
+        self.event_len = 0;
+        self.candidate = None;
+    }
+    pub fn reset(&mut self) {
+        for f in &mut self.detect {
+            f.reset();
+        }
+        self.ring.fill(0.);
+        self.decimate_count = 0;
+        self.hop_count = 0;
+        self.gate_env = 0.;
+        self.gate_open = false;
+        self.gate_hold = 0;
+        self.release_all();
+    }
+    /// MIDI note start at the current input sample. Used when the source is MIDI.
+    pub fn note_on(&mut self, note: u8) {
+        self.push(Kind::NoteOn(note.min(127)));
+    }
+    pub fn note_off(&mut self, note: u8) {
+        self.push(Kind::NoteOff(note.min(127)));
+    }
+    /// True while a note sounds at output time.
+    pub fn sounding(&self) -> bool {
+        self.sounding
+    }
+    fn push(&mut self, kind: Kind) {
+        if self.event_len == EVENTS {
+            // Dropping the oldest keeps the newest note state; overflow only happens on floods.
+            self.event_head = (self.event_head + 1) % EVENTS;
+            self.event_len -= 1;
+        }
+        let at = (self.event_head + self.event_len) % EVENTS;
+        self.events[at] = Event {
+            time: self.clock,
+            kind,
+        };
+        self.event_len += 1;
+    }
+    /// Detected pitch of the most recent analysis window, in fractional MIDI notes.
+    fn estimate(&mut self) -> Option<f32> {
+        let n = self.ring.len();
+        for i in 0..n {
+            self.scratch[i] = self.ring[(self.ring_at + i) % n];
+        }
+        let (hz, clarity) = self.yin.estimate(
+            &self.scratch,
+            self.detect_rate,
+            self.cfg.min_hz,
+            self.cfg.max_hz,
+        )?;
+        (clarity >= CLARITY).then(|| hz_to_midi(hz))
+    }
+    fn start(&mut self, pitch: f32, glide: bool, emit: &mut impl FnMut(NoteEvent)) {
+        self.tracked = pitch;
+        self.candidate = None;
+        self.pending = false;
+        self.sounding = true;
+        emit(NoteEvent::Start { pitch, glide });
+    }
+    fn stop(&mut self, emit: &mut impl FnMut(NoteEvent)) {
+        self.sounding = false;
+        self.pending = false;
+        self.candidate = None;
+        emit(NoteEvent::Stop);
+    }
+    fn handle(&mut self, kind: Kind, emit: &mut impl FnMut(NoteEvent)) {
+        let midi = self.midi;
+        match kind {
+            Kind::Onset if !midi => match self.estimate() {
+                Some(p) => self.start(p, false, emit),
+                None => {
+                    self.pending = true;
+                    self.sounding = true;
+                }
+            },
+            Kind::Release if !midi => self.stop(emit),
+            Kind::NoteOn(n) if midi => {
+                let len = self.held_len;
+                if let Some(i) = self.held[..len].iter().position(|h| *h == n) {
+                    self.held.copy_within(i + 1..len, i);
+                    self.held_len -= 1;
+                }
+                if self.held_len == self.held.len() {
+                    self.held.copy_within(1.., 0);
+                    self.held_len -= 1;
+                }
+                let legato = self.held_len > 0;
+                self.held[self.held_len] = n;
+                self.held_len += 1;
+                self.start(n as f32, legato && self.glide, emit);
+            }
+            Kind::NoteOff(n) if midi => {
+                let len = self.held_len;
+                let Some(i) = self.held[..len].iter().position(|h| *h == n) else {
+                    return;
+                };
+                let top = i + 1 == len;
+                self.held.copy_within(i + 1..len, i);
+                self.held_len -= 1;
+                if self.held_len == 0 {
+                    self.stop(emit);
+                } else if top {
+                    let next = self.held[self.held_len - 1];
+                    self.start(next as f32, self.glide, emit);
+                }
+            }
+            _ => {}
+        }
+    }
+    /// Regular analysis; its window starts at the current output time.
+    fn hop_analysis(&mut self, emit: &mut impl FnMut(NoteEvent)) {
+        if self.midi || !self.sounding {
+            return;
+        }
+        let Some(p) = self.estimate() else {
+            return;
+        };
+        if self.pending {
+            self.start(p, false, emit);
+            return;
+        }
+        if (p - self.tracked).abs() >= JUMP {
+            match self.candidate {
+                Some((c, count)) if (c - p).abs() < 0.5 => {
+                    if count + 1 >= 2 {
+                        self.start(p, self.glide, emit);
+                    } else {
+                        self.candidate = Some((p, count + 1));
+                    }
+                }
+                _ => self.candidate = Some((p, 1)),
+            }
+        } else {
+            self.candidate = None;
+            self.tracked += 0.3 * (p - self.tracked);
+            emit(NoteEvent::Move {
+                pitch: self.tracked,
+            });
+        }
+    }
+    /// Feeds one undelayed mono input sample. Events due at output time go to `emit`, in order.
+    pub fn process(&mut self, mono: f32, mut emit: impl FnMut(NoteEvent)) {
+        let d = self.detect[0].process(mono);
+        let d = self.detect[1].process(d);
+        if !self.midi {
+            let a = d.abs();
+            self.gate_env = if a > self.gate_env {
+                a
+            } else {
+                self.gate_env * self.gate_release
+            };
+            let level = gain_to_db(self.gate_env);
+            if level > self.gate_db {
+                self.gate_hold = (self.rate * GATE_HOLD_MS * 0.001) as usize;
+                if !self.gate_open {
+                    self.gate_open = true;
+                    self.push(Kind::Onset);
+                }
+            } else if self.gate_open && level < self.gate_db - GATE_HYSTERESIS_DB {
+                if self.gate_hold == 0 {
+                    self.gate_open = false;
+                    self.push(Kind::Release);
+                } else {
+                    self.gate_hold -= 1;
+                }
+            }
+        }
+        self.decimate_count += 1;
+        if self.decimate_count >= self.decimate {
+            self.decimate_count = 0;
+            self.ring[self.ring_at] = d;
+            self.ring_at = (self.ring_at + 1) % self.ring.len();
+            self.hop_count += 1;
+            if self.hop_count >= self.hop {
+                self.hop_count = 0;
+                self.hop_analysis(&mut emit);
+            }
+        }
+        while self.event_len > 0 {
+            let e = self.events[self.event_head];
+            if e.time + self.latency as u64 > self.clock {
+                break;
+            }
+            self.event_head = (self.event_head + 1) % EVENTS;
+            self.event_len -= 1;
+            self.handle(e.kind, &mut emit);
+        }
+        self.clock += 1;
+    }
+}
+
+/// Fundamental that follows tracker events: jumps on new notes, slides on bends and legato.
+#[derive(Clone, Copy, Debug, Default)]
+pub struct PitchFollower {
+    target: f32,
+    hz: f32,
+    jump: bool,
+}
+impl PitchFollower {
+    pub fn event(&mut self, snap: bool, e: NoteEvent) {
+        match e {
+            NoteEvent::Start { pitch, glide } => {
+                let p = if snap { pitch.round() } else { pitch };
+                self.target = crate::midi_to_hz(p);
+                self.jump |= !glide;
+            }
+            NoteEvent::Move { pitch } if !snap => self.target = crate::midi_to_hz(pitch),
+            // The last pitch is held so tails keep their tuning.
+            _ => {}
+        }
+    }
+    /// Advances one sample with one-pole coefficient `coef`. Returns the frequency, 0 before the
+    /// first note, and whether it jumped this sample (a new note, or the first one).
+    pub fn step(&mut self, coef: f32) -> (f32, bool) {
+        let jump = std::mem::take(&mut self.jump) || (self.hz == 0. && self.target > 0.);
+        if jump {
+            self.hz = self.target;
+        } else {
+            self.hz += (self.target - self.hz) * coef;
+        }
+        (self.hz, jump)
+    }
+    pub fn hz(&self) -> f32 {
+        self.hz
+    }
+}
+
+/// A processor driven by note events that are aligned with its input audio. Lathe, Temper and
+/// Knurl are built from one each, so the same code runs standalone (after its own tracker) and
+/// inside a strip that shares one tracker between several of them.
+pub trait Tracked {
+    /// Delay of the output behind the input, in samples.
+    fn latency(&self) -> usize;
+    /// The undelayed input, one tracker lookahead ahead of the audio passed to `process`.
+    /// Called before the sample's events.
+    fn ahead(&mut self, _mono: f32) {}
+    /// A note event due at the next `process` sample.
+    fn event(&mut self, e: NoteEvent);
+    /// One sample of audio; `sounding` is the tracker's note state at this sample.
+    fn process(&mut self, x: [f32; 2], sounding: bool) -> [f32; 2];
+}
+
+/// A tracker and the lookahead delay in front of one [`Tracked`] module: the standalone form.
+pub struct Lookahead {
+    pub tracker: Tracker,
+    delay: Vec<[f32; 2]>,
+    at: usize,
+}
+impl Lookahead {
+    pub fn new(rate: f32, cfg: TrackerConfig) -> Self {
+        let tracker = Tracker::new(rate, cfg);
+        let len = tracker.latency() + 1;
+        Self {
+            tracker,
+            delay: vec![[0.; 2]; len],
+            at: 0,
+        }
+    }
+    /// The tracker's lookahead, in samples.
+    pub fn latency(&self) -> usize {
+        self.tracker.latency()
+    }
+    pub fn reset(&mut self) {
+        self.tracker.reset();
+        self.delay.fill([0.; 2]);
+    }
+    /// Feeds one input sample (`mono` is its channel average) and returns `module`'s output.
+    #[inline]
+    pub fn process(&mut self, x: [f32; 2], mono: f32, module: &mut impl Tracked) -> [f32; 2] {
+        module.ahead(mono);
+        self.tracker.process(mono, |e| module.event(e));
+        let len = self.delay.len();
+        self.delay[self.at] = x;
+        self.at = (self.at + 1) % len;
+        let y = self.delay[self.at];
+        module.process(y, self.tracker.sounding())
+    }
+}
@@ -0,0 +1,142 @@
+//! Minimal RIFF/WAVE writer and reader: 32-bit float data, sampler root key, Serum wavetable tag.
+use std::{io, path::Path};
+
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct Wave {
+    pub channels: u16,
+    pub rate: u32,
+    /// Interleaved samples.
+    pub samples: Vec<f32>,
+    /// MIDI root key, written as a `smpl` chunk that samplers (FL included) read.
+    pub root: Option<u8>,
+    /// Wavetable frame size, written as Serum's `clm ` chunk.
+    pub frame: Option<u32>,
+}
+
+fn chunk(out: &mut Vec<u8>, id: &[u8; 4], body: &[u8]) {
+    out.extend_from_slice(id);
+    out.extend_from_slice(&(body.len() as u32).to_le_bytes());
+    out.extend_from_slice(body);
+    if body.len() % 2 == 1 {
+        out.push(0);
+    }
+}
+
+pub fn encode(w: &Wave) -> Vec<u8> {
+    let channels = w.channels.max(1);
+    let frames = w.samples.len() / channels as usize;
+    let mut body = Vec::with_capacity(w.samples.len() * 4 + 256);
+    body.extend_from_slice(b"WAVE");
+    let mut fmt = Vec::new();
+    fmt.extend_from_slice(&3u16.to_le_bytes()); // IEEE float
+    fmt.extend_from_slice(&channels.to_le_bytes());
+    fmt.extend_from_slice(&w.rate.to_le_bytes());
+    fmt.extend_from_slice(&(w.rate * 4 * channels as u32).to_le_bytes());
+    fmt.extend_from_slice(&(4 * channels).to_le_bytes());
+    fmt.extend_from_slice(&32u16.to_le_bytes());
+    fmt.extend_from_slice(&0u16.to_le_bytes());
+    chunk(&mut body, b"fmt ", &fmt);
+    chunk(&mut body, b"fact", &(frames as u32).to_le_bytes());
+    if let Some(frame) = w.frame {
+        // Serum reads the frame size from the "<!>NNNN" prefix.
+        chunk(
+            &mut body,
+            b"clm ",
+            format!("<!>{frame} 00000000 wavetable (Crucible)").as_bytes(),
+        );
+    }
+    if let Some(root) = w.root {
+        let mut smpl = Vec::new();
+        let period = (1e9 / w.rate.max(1) as f64).round() as u32;
+        for v in [0, 0, period, root as u32, 0, 0, 0, 0, 0] {
+            smpl.extend_from_slice(&v.to_le_bytes());
+        }
+        chunk(&mut body, b"smpl", &smpl);
+    }
+    let mut data = Vec::with_capacity(w.samples.len() * 4);
+    for s in &w.samples[..frames * channels as usize] {
+        data.extend_from_slice(&s.to_le_bytes());
+    }
+    chunk(&mut body, b"data", &data);
+    let mut out = Vec::with_capacity(body.len() + 8);
+    out.extend_from_slice(b"RIFF");
+    out.extend_from_slice(&(body.len() as u32).to_le_bytes());
+    out.extend_from_slice(&body);
+    out
+}
+
+pub fn write(path: &Path, w: &Wave) -> io::Result<()> {
+    std::fs::write(path, encode(w))
+}
+
+/// Reads float32 or PCM16/24 files written by this module or common tools.
+pub fn decode(b: &[u8]) -> Result<Wave, &'static str> {
+    if b.len() < 12 || &b[..4] != b"RIFF" || &b[8..12] != b"WAVE" {
+        return Err("expected RIFF/WAVE");
+    }
+    let mut w = Wave::default();
+    let (mut format, mut bits) = (0u16, 0u16);
+    let mut at = 12;
+    let mut data = false;
+    let u16_at = |o: usize| u16::from_le_bytes([b[o], b[o + 1]]);
+    let u32_at = |o: usize| u32::from_le_bytes([b[o], b[o + 1], b[o + 2], b[o + 3]]);
+    while at + 8 <= b.len() {
+        let id = &b[at..at + 4];
+        let len = u32_at(at + 4) as usize;
+        let start = at + 8;
+        let end = start
+            .checked_add(len)
+            .filter(|e| *e <= b.len())
+            .ok_or("truncated chunk")?;
+        match id {
+            b"fmt " if len >= 16 => {
+                format = u16_at(start);
+                w.channels = u16_at(start + 2);
+                w.rate = u32_at(start + 4);
+                bits = u16_at(start + 14);
+            }
+            b"smpl" if len >= 16 => w.root = Some(u32_at(start + 12) as u8),
+            b"clm " => {
+                let text = std::str::from_utf8(&b[start..end]).map_err(|_| "bad clm chunk")?;
+                w.frame = text
+                    .strip_prefix("<!>")
+                    .and_then(|t| t.split_whitespace().next())
+                    .and_then(|n| n.parse().ok());
+            }
+            b"data" => {
+                data = true;
+                let d = &b[start..end];
+                w.samples = match (format, bits) {
+                    (3, 32) => d
+                        .as_chunks::<4>()
+                        .0
+                        .iter()
+                        .map(|c| f32::from_le_bytes(*c))
+                        .collect(),
+                    (1, 16) => d
+                        .as_chunks::<2>()
+                        .0
+                        .iter()
+                        .map(|c| i16::from_le_bytes(*c) as f32 / 32768.)
+                        .collect(),
+                    (1, 24) => d
+                        .as_chunks::<3>()
+                        .0
+                        .iter()
+                        .map(|c| (i32::from_le_bytes([0, c[0], c[1], c[2]]) >> 8) as f32 / 8388608.)
+                        .collect(),
+                    _ => return Err("unsupported sample format"),
+                };
+            }
+            _ => {}
+        }
+        at = end + (len % 2);
+    }
+    if w.channels == 0 || w.rate == 0 {
+        return Err("missing fmt chunk");
+    }
+    if !data {
+        return Err("missing data chunk");
+    }
+    Ok(w)
+}
@@ -0,0 +1,250 @@
+use common_dsp::meter::HarmonicMeter;
+use common_dsp::oversample::Oversampler;
+use common_dsp::svf::{Svf, SvfCoef};
+use common_dsp::tracker::{NoteEvent, Tracker, TrackerConfig};
+use common_dsp::{hz_to_midi, Saw};
+use std::f32::consts::TAU;
+
+const RATE: f32 = 48000.;
+
+/// Steady-state gain in dB of a sine at `hz` through `f`.
+fn sine_gain(mut f: impl FnMut(f32) -> f32, hz: f32) -> f32 {
+    let n = (RATE * 0.5) as usize;
+    let (mut pin, mut pout) = (0., 0.);
+    for i in 0..n {
+        let x = (TAU * hz * i as f32 / RATE).sin();
+        let y = f(x);
+        if i > n / 2 {
+            pin += x * x;
+            pout += y * y;
+        }
+    }
+    10. * (pout / pin).log10()
+}
+
+#[test]
+fn svf_bell_hits_its_gain_and_leaves_the_rest() {
+    for (hz, db) in [(130., -12.), (400., 6.), (2000., -24.)] {
+        let c = SvfCoef::bell(RATE, hz, 4., db);
+        let mut s = Svf::default();
+        let g = sine_gain(|x| s.process(&c, x), hz);
+        assert!((g - db).abs() < 0.1, "{hz}: {g}");
+        let mut s = Svf::default();
+        let g = sine_gain(|x| s.process(&c, x), hz * 4.);
+        assert!(g.abs() < 0.3, "{hz} away: {g}");
+    }
+}
+
+#[test]
+fn svf_bell_at_zero_db_is_an_exact_identity() {
+    let c = SvfCoef::bell(RATE, 100., 2., 0.);
+    let mut s = Svf::default();
+    let mut saw = Saw::new(RATE, 55.);
+    for _ in 0..4800 {
+        let x = saw.sample();
+        assert_eq!(s.process(&c, x), x);
+    }
+}
+
+#[test]
+fn svf_allpass_matches_a_linkwitz_riley_split() {
+    let q = std::f32::consts::FRAC_1_SQRT_2;
+    let (low, high, all) = (
+        SvfCoef::lowpass(RATE, 300., q),
+        SvfCoef::highpass(RATE, 300., q),
+        SvfCoef::allpass(RATE, 300., q),
+    );
+    let mut s = [Svf::default(); 5];
+    let mut saw = Saw::new(RATE, 55.);
+    for _ in 0..9600 {
+        let x = saw.sample();
+        let l = s[0].process(&low, x);
+        let l = s[1].process(&low, l);
+        let h = s[2].process(&high, x);
+        let h = s[3].process(&high, h);
+        let a = s[4].process(&all, x);
+        assert!((l + h - a).abs() < 1e-4, "{} vs {a}", l + h);
+    }
+    let mut s = Svf::default();
+    for hz in [30., 300., 3000.] {
+        assert!(sine_gain(|x| s.process(&all, x), hz).abs() < 0.01);
+    }
+}
+
+#[test]
+fn svf_survives_retuning_every_sample() {
+    let mut s = Svf::default();
+    let mut saw = Saw::new(RATE, 55.);
+    let mut peak: f32 = 0.;
+    for i in 0..48000 {
+        let hz = 40. + 4000. * (0.5 + 0.5 * (i as f32 * 0.003).sin());
+        let c = SvfCoef::bell(RATE, hz, 8., 12.);
+        let y = s.process(&c, saw.sample());
+        assert!(y.is_finite());
+        peak = peak.max(y.abs());
+    }
+    assert!(peak < 8., "{peak}");
+    let c = SvfCoef::lowpass(RATE, 200., 0.707);
+    let mut s = Svf::default();
+    assert!(sine_gain(|x| s.process(&c, x), 2000.) < -35.);
+    let c = SvfCoef::highpass(RATE, 200., 0.707);
+    let mut s = Svf::default();
+    assert!(sine_gain(|x| s.process(&c, x), 20.) < -35.);
+}
+
+#[test]
+fn oversampler_round_trip_is_a_whole_sample_delay() {
+    let mut o = Oversampler::new();
+    let l = Oversampler::latency();
+    let mut saw = Saw::new(RATE, 97.);
+    let x: Vec<f32> = (0..9600).map(|_| saw.sample() * 0.5).collect();
+    let y: Vec<f32> = x
+        .iter()
+        .map(|&v| {
+            let u = o.up(v);
+            o.down(u)
+        })
+        .collect();
+    // Band-limited content passes; compare after the delay, away from the start.
+    let mut err: f32 = 0.;
+    let mut sig: f32 = 0.;
+    for i in 2000..9600 {
+        let d = y[i] - x[i - l];
+        err += d * d;
+        sig += x[i - l] * x[i - l];
+    }
+    let null = 10. * (err / sig).log10();
+    // The saw has energy above the passband edge, so the null is limited by that, not by timing.
+    assert!(null < -40., "{null}");
+}
+
+#[test]
+fn oversampler_passband_is_flat_and_images_are_removed() {
+    for hz in [50., 1000., 10000., 18000.] {
+        let mut o = Oversampler::new();
+        let g = sine_gain(
+            |x| {
+                let u = o.up(x);
+                o.down(u)
+            },
+            hz,
+        );
+        assert!(g.abs() < 0.1, "{hz}: {g}");
+    }
+    // An image of a 1 kHz tone at 4× would sit at 47 kHz; check the 4× signal there.
+    let mut o = Oversampler::new();
+    let n = 48000;
+    let (mut a, mut b) = (0f64, 0f64);
+    let w = TAU as f64 * 47000. / (4. * RATE as f64);
+    for i in 0..n {
+        let x = (TAU * 1000. * i as f32 / RATE).sin();
+        for (k, v) in o.up(x).into_iter().enumerate() {
+            let t = (4 * i + k) as f64;
+            a += v as f64 * (w * t).cos();
+            b += v as f64 * (w * t).sin();
+        }
+    }
+    let image = 20.
+        * ((a * a + b * b).sqrt() / (2. * n as f64))
+            .max(1e-12)
+            .log10();
+    assert!(image < -85., "{image}");
+}
+
+#[test]
+fn harmonic_meter_reads_saw_harmonics() {
+    let hz = 55.;
+    let mut m = HarmonicMeter::new(RATE, 85.);
+    let mut saw = Saw::new(RATE, hz);
+    let mut done = 0;
+    for _ in 0..48000 {
+        if m.push(saw.sample(), hz) {
+            done += 1;
+        }
+    }
+    assert!(done >= 5);
+    // A saw's k-th harmonic has peak 2/(πk).
+    for k in 1..=16 {
+        let want = 20. * (2. / (std::f32::consts::PI * k as f32)).log10();
+        let got = m.levels()[k - 1];
+        assert!((got - want).abs() < 0.5, "harmonic {k}: {got} vs {want}");
+    }
+}
+
+#[test]
+fn tracker_reports_notes_at_output_time() {
+    let mut t = Tracker::new(RATE, TrackerConfig::BASS);
+    t.set(false, -42., false);
+    let l = t.latency();
+    assert!(l < (0.08 * RATE) as usize, "{l}");
+    let onset = 4800;
+    let mut events = vec![];
+    let mut saw_a = Saw::new(RATE, 87.31);
+    let mut saw_b = Saw::new(RATE, 220.);
+    for i in 0..onset + 48000 {
+        let x = if i < onset {
+            0.
+        } else if i < onset + 24000 {
+            0.5 * saw_a.sample()
+        } else {
+            0.5 * saw_b.sample()
+        };
+        t.process(x, |e| events.push((i, e)));
+    }
+    let starts: Vec<_> = events
+        .iter()
+        .filter_map(|(i, e)| match e {
+            NoteEvent::Start { pitch, .. } => Some((*i, *pitch)),
+            _ => None,
+        })
+        .collect();
+    assert_eq!(starts.len(), 2, "{starts:?}");
+    assert!(
+        (starts[0].0 as i64 - (onset + l) as i64).abs() <= 24,
+        "{starts:?}"
+    );
+    assert!((starts[0].1 - hz_to_midi(87.31)).abs() < 0.2);
+    assert!((starts[1].1 - hz_to_midi(220.)).abs() < 0.2);
+}
+
+#[test]
+fn tracker_delays_midi_by_the_latency() {
+    let mut t = Tracker::new(RATE, TrackerConfig::BASS);
+    assert!(t.set(true, -42., true));
+    let l = t.latency();
+    let mut events = vec![];
+    for i in 0..l + 2000 {
+        if i == 100 {
+            t.note_on(41);
+        }
+        if i == 600 {
+            t.note_on(43);
+        }
+        if i == 900 {
+            // Releasing the lower held note first leaves the top note; then the top ends it.
+            t.note_off(41);
+            t.note_off(43);
+        }
+        t.process(0., |e| events.push((i, e)));
+    }
+    assert_eq!(
+        events,
+        vec![
+            (
+                100 + l,
+                NoteEvent::Start {
+                    pitch: 41.,
+                    glide: false
+                }
+            ),
+            (
+                600 + l,
+                NoteEvent::Start {
+                    pitch: 43.,
+                    glide: true
+                }
+            ),
+            (900 + l, NoteEvent::Stop),
+        ]
+    );
+}
@@ -0,0 +1,108 @@
+use common_dsp::{hz_to_midi, midi_to_hz, note_name, wav, Crossover, Saw, Yin};
+
+fn cents(a: f32, b: f32) -> f32 {
+    1200. * (a / b).log2()
+}
+
+#[test]
+fn yin_tracks_bass_fundamentals_within_two_cents() {
+    let rate = 48000.;
+    let mut yin = Yin::new(2400);
+    for hz in [43.65, 55., 110., 220.] {
+        let mut saw = Saw::new(rate, hz);
+        let x: Vec<f32> = (0..6000).map(|_| saw.sample()).collect();
+        let (got, clarity) = yin.estimate(&x, rate, 25., 1000.).unwrap();
+        assert!(cents(got, hz).abs() < 2., "{hz}: {got}");
+        assert!(clarity > 0.8);
+    }
+}
+
+#[test]
+fn yin_rejects_silence_and_noise() {
+    let mut yin = Yin::new(2400);
+    assert!(yin.estimate(&[0.; 6000], 48000., 25., 1000.).is_none());
+    let mut seed = 1u32;
+    let noise: Vec<f32> = (0..6000)
+        .map(|_| {
+            seed = seed.wrapping_mul(1664525).wrapping_add(1013904223);
+            (seed >> 8) as f32 / (1u32 << 24) as f32 - 0.5
+        })
+        .collect();
+    assert!(yin.estimate(&noise, 48000., 25., 1000.).is_none());
+}
+
+#[test]
+fn crossover_bands_sum_to_flat_magnitude() {
+    let rate = 48000.;
+    for hz in [20., 45., 90., 180., 1000., 8000., 18000.] {
+        let mut x = Crossover::new(rate, 90.);
+        let (mut a, mut b) = (0f64, 0f64);
+        let n = 96000;
+        for i in 0..n {
+            let s = (std::f32::consts::TAU * hz * i as f32 / rate).sin();
+            let (l, h) = x.process(s);
+            if i > n / 2 {
+                a += (s as f64).powi(2);
+                b += ((l + h) as f64).powi(2);
+            }
+        }
+        let db = 10. * (b / a).log10();
+        assert!(db.abs() < 0.1, "{hz} Hz: {db} dB");
+    }
+}
+
+#[test]
+fn notes_round_trip() {
+    assert!((midi_to_hz(29.) - 43.65).abs() < 0.01);
+    assert!((hz_to_midi(440.) - 69.).abs() < 1e-4);
+    assert_eq!(note_name(29), "F1");
+    assert_eq!(note_name(61), "C#4");
+}
+
+#[test]
+fn wave_round_trip_keeps_root_and_wavetable_chunks() {
+    let w = wav::Wave {
+        channels: 2,
+        rate: 44100,
+        samples: (0..999)
+            .map(|i| (i as f32 * 0.01).sin())
+            .collect::<Vec<_>>()[..998]
+            .to_vec(),
+        root: Some(29),
+        frame: Some(2048),
+    };
+    let bytes = wav::encode(&w);
+    assert_eq!(&bytes[..4], b"RIFF");
+    assert_eq!(
+        u32::from_le_bytes(bytes[4..8].try_into().unwrap()) as usize,
+        bytes.len() - 8
+    );
+    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.);
+}
@@ -0,0 +1,8 @@
+[package]
+name = "common-ui"
+version = "0.1.0"
+edition.workspace = true
+license.workspace = true
+
+[dependencies]
+egui = "0.31.1"
@@ -0,0 +1,361 @@
+//! Shared hardware look for every plugin editor: palette, fonts, knobs, panels.
+use egui::{self, Color32, FontId, Pos2, Rect, RichText, Sense, Stroke, Vec2};
+
+// Dark anodized hardware: graphite surfaces, one signal colour, steel data traces.
+pub const BG: Color32 = Color32::from_rgb(14, 15, 17);
+pub const PANEL: Color32 = Color32::from_rgb(25, 27, 31);
+pub const PANEL_TOP: Color32 = Color32::from_rgb(34, 36, 41);
+pub const EDGE: Color32 = Color32::from_rgb(44, 47, 53);
+pub const SCREEN: Color32 = Color32::from_rgb(9, 10, 11);
+pub const TEXT: Color32 = Color32::from_rgb(232, 233, 236);
+pub const MUTED: Color32 = Color32::from_rgb(140, 146, 156);
+pub const DIM: Color32 = Color32::from_rgb(70, 74, 82);
+/// Signal colour: cuts, active states, value arcs.
+pub const ACCENT: Color32 = Color32::from_rgb(255, 1, 96);
+/// Measured input and neutral data.
+pub const STEEL: Color32 = Color32::from_rgb(184, 192, 204);
+/// Focus / protect curve, distinct from cuts without competing with them.
+pub const FOCUS: Color32 = Color32::from_rgb(126, 167, 216);
+pub fn style(ctx: &egui::Context) {
+    let mut fonts = egui::FontDefinitions::default();
+    fonts.font_data.insert(
+        "regular".into(),
+        egui::FontData::from_static(include_bytes!("../assets/RobotoCondensed-Regular.ttf")).into(),
+    );
+    fonts.font_data.insert(
+        "medium".into(),
+        egui::FontData::from_static(include_bytes!("../assets/RobotoCondensed-Medium.ttf")).into(),
+    );
+    fonts
+        .families
+        .get_mut(&egui::FontFamily::Proportional)
+        .unwrap()
+        .insert(0, "regular".into());
+    fonts.families.insert(
+        egui::FontFamily::Name("medium".into()),
+        vec![
+            "medium".into(),
+            "Ubuntu-Light".into(),
+            "NotoEmoji-Regular".into(),
+            "emoji-icon-font".into(),
+        ],
+    );
+    ctx.set_fonts(fonts);
+    let mut s = (*ctx.style()).clone();
+    let v = &mut s.visuals;
+    *v = egui::Visuals::dark();
+    v.panel_fill = BG;
+    v.window_fill = PANEL;
+    v.extreme_bg_color = SCREEN;
+    v.faint_bg_color = PANEL;
+    v.override_text_color = Some(TEXT);
+    v.selection.bg_fill = Color32::from_rgb(110, 6, 46);
+    v.selection.stroke = Stroke::new(1.0_f32, ACCENT);
+    v.hyperlink_color = ACCENT;
+    v.window_stroke = Stroke::new(1.0_f32, EDGE);
+    for (w, fill, stroke) in [
+        (&mut v.widgets.noninteractive, PANEL, EDGE),
+        (&mut v.widgets.inactive, Color32::from_rgb(35, 38, 43), EDGE),
+        (
+            &mut v.widgets.hovered,
+            Color32::from_rgb(45, 48, 54),
+            Color32::from_rgb(78, 82, 90),
+        ),
+        (&mut v.widgets.active, Color32::from_rgb(58, 18, 34), ACCENT),
+        (&mut v.widgets.open, Color32::from_rgb(35, 38, 43), EDGE),
+    ] {
+        w.bg_fill = fill;
+        w.weak_bg_fill = fill;
+        w.bg_stroke = Stroke::new(1.0_f32, stroke);
+        w.corner_radius = 3.into();
+    }
+    v.widgets.noninteractive.fg_stroke = Stroke::new(1.0_f32, TEXT);
+    v.widgets.inactive.fg_stroke = Stroke::new(1.0_f32, TEXT);
+    v.slider_trailing_fill = true;
+    s.spacing.item_spacing = Vec2::new(10., 8.);
+    s.spacing.button_padding = Vec2::new(12., 6.);
+    s.text_styles
+        .insert(egui::TextStyle::Body, FontId::proportional(16.));
+    s.text_styles
+        .insert(egui::TextStyle::Button, FontId::proportional(16.));
+    ctx.set_style(s);
+}
+/// Disc with a vertical light-to-dark gradient, like brushed metal lit from above.
+pub fn metal_disc(p: &egui::Painter, center: Pos2, radius: f32, top: Color32, bottom: Color32) {
+    let mut mesh = egui::Mesh::default();
+    let mix = |t: f32| {
+        let l = |a: u8, b: u8| (a as f32 + (b as f32 - a as f32) * t).round() as u8;
+        Color32::from_rgb(
+            l(top.r(), bottom.r()),
+            l(top.g(), bottom.g()),
+            l(top.b(), bottom.b()),
+        )
+    };
+    mesh.colored_vertex(center, mix(0.5));
+    let n = 48;
+    for i in 0..=n {
+        let a = std::f32::consts::TAU * i as f32 / n as f32;
+        let point = center + Vec2::angled(a) * radius;
+        mesh.colored_vertex(point, mix((point.y - (center.y - radius)) / (2. * radius)));
+        if i > 0 {
+            mesh.add_triangle(0, i, i + 1);
+        }
+    }
+    p.add(egui::Shape::mesh(mesh));
+}
+#[allow(clippy::too_many_arguments)]
+pub fn rotary(
+    ui: &mut egui::Ui,
+    name: &str,
+    value: &mut f32,
+    range: std::ops::RangeInclusive<f32>,
+    default: f32,
+    unit: &str,
+    size: f32,
+    color: Color32,
+) -> egui::Response {
+    let response = dial(ui, value, range.clone(), default, size, color);
+    dial_caption(ui, name, size);
+    ui.add(
+        egui::DragValue::new(value)
+            .range(range)
+            .speed(0.1)
+            .suffix(unit),
+    );
+    response
+}
+/// A rotary whose value field shows custom text, for values that are not a plain number
+/// with a unit (a ratio, a mapped knob position).
+#[allow(clippy::too_many_arguments)]
+pub fn rotary_text(
+    ui: &mut egui::Ui,
+    name: &str,
+    value: &mut f32,
+    range: std::ops::RangeInclusive<f32>,
+    default: f32,
+    size: f32,
+    color: Color32,
+    format: impl Fn(f32) -> String,
+    parse: impl Fn(&str) -> Option<f32>,
+) -> egui::Response {
+    let response = dial(ui, value, range.clone(), default, size, color);
+    dial_caption(ui, name, size);
+    let speed = (*range.end() - *range.start()) as f64 / 200.;
+    ui.add(
+        egui::DragValue::new(value)
+            .range(range)
+            .speed(speed)
+            .custom_formatter(|v, _| format(v as f32))
+            .custom_parser(|s| parse(s).map(f64::from)),
+    );
+    response
+}
+fn dial_caption(ui: &mut egui::Ui, name: &str, size: f32) {
+    ui.label(
+        RichText::new(name.to_uppercase())
+            .size(if size > 100. { 14. } else { 12. })
+            .color(MUTED),
+    );
+}
+/// The knob itself: drag, keys, double-click reset, and drawing.
+fn dial(
+    ui: &mut egui::Ui,
+    value: &mut f32,
+    range: std::ops::RangeInclusive<f32>,
+    default: f32,
+    size: f32,
+    color: Color32,
+) -> egui::Response {
+    let low = *range.start();
+    let high = *range.end();
+    let (rect, response) = ui.allocate_exact_size(Vec2::splat(size), Sense::click_and_drag());
+    if response.drag_started() {
+        response.request_focus();
+    }
+    if response.dragged() {
+        let delta = ui.input(|i| i.pointer.delta().y);
+        let fine = if ui.input(|i| i.modifiers.shift) {
+            0.1
+        } else {
+            1.
+        };
+        *value = (*value - delta * (high - low) / 180. * fine).clamp(low, high);
+    }
+    if response.double_clicked() {
+        *value = default;
+    }
+    if response.has_focus() {
+        let step = if ui.input(|i| i.modifiers.shift) {
+            0.1
+        } else {
+            1.
+        };
+        if ui.input(|i| i.key_pressed(egui::Key::ArrowUp) || i.key_pressed(egui::Key::ArrowRight)) {
+            *value = (*value + step).min(high);
+        }
+        if ui.input(|i| i.key_pressed(egui::Key::ArrowDown) || i.key_pressed(egui::Key::ArrowLeft))
+        {
+            *value = (*value - step).max(low);
+        }
+    }
+    let center = rect.center();
+    let radius = size * 0.46;
+    let p = ui.painter();
+    let start = std::f32::consts::PI * 0.75;
+    let span = std::f32::consts::PI * 1.5;
+    let normalized = ((*value - low) / (high - low)).clamp(0., 1.);
+    // Scale track and value arc around the knob.
+    for (fraction, stroke) in [
+        (1., Stroke::new(2.5_f32, DIM)),
+        (normalized, Stroke::new(2.5_f32, color)),
+    ] {
+        // A zero-length polyline tessellates to NaN vertices.
+        if fraction < 1e-3 {
+            continue;
+        }
+        let points: Vec<_> = (0..=64)
+            .map(|i| {
+                let a = start + span * fraction * i as f32 / 64.;
+                center + Vec2::angled(a) * (radius - 1.5)
+            })
+            .collect();
+        p.add(egui::Shape::line(points, stroke));
+    }
+    // Machined body: drop shadow, brushed gradient skirt, flat cap.
+    let body = radius - 7.;
+    p.circle_filled(
+        center + Vec2::new(0., 2.),
+        body + 1.,
+        Color32::from_black_alpha(140),
+    );
+    metal_disc(
+        p,
+        center,
+        body,
+        Color32::from_rgb(78, 82, 90),
+        Color32::from_rgb(28, 30, 34),
+    );
+    p.circle_stroke(
+        center,
+        body,
+        Stroke::new(1.0_f32, Color32::from_rgb(10, 11, 12)),
+    );
+    let cap = body * 0.74;
+    metal_disc(
+        p,
+        center,
+        cap,
+        Color32::from_rgb(44, 47, 52),
+        Color32::from_rgb(33, 35, 40),
+    );
+    p.circle_stroke(
+        center,
+        cap,
+        Stroke::new(1.0_f32, Color32::from_rgba_unmultiplied(255, 255, 255, 22)),
+    );
+    let angle = start + span * normalized;
+    p.line_segment(
+        [
+            center + Vec2::angled(angle) * (cap * 0.35),
+            center + Vec2::angled(angle) * (cap - 2.),
+        ],
+        Stroke::new(2.0_f32, TEXT),
+    );
+    if response.has_focus() {
+        p.circle_stroke(center, radius + 2., Stroke::new(1.0_f32, color));
+    }
+    response
+}
+/// Vertical gradient rectangle, used for panel faces.
+pub fn gradient(rect: Rect, top: Color32, bottom: Color32) -> egui::Shape {
+    let mut mesh = egui::Mesh::default();
+    for (pos, color) in [
+        (rect.left_top(), top),
+        (rect.right_top(), top),
+        (rect.right_bottom(), bottom),
+        (rect.left_bottom(), bottom),
+    ] {
+        mesh.colored_vertex(pos, color);
+    }
+    mesh.add_triangle(0, 1, 2);
+    mesh.add_triangle(0, 2, 3);
+    egui::Shape::mesh(mesh)
+}
+/// Raised hardware panel: graphite face, hairline edge, faint top highlight.
+pub fn panel<R>(ui: &mut egui::Ui, add: impl FnOnce(&mut egui::Ui) -> R) -> R {
+    let face = ui.painter().add(egui::Shape::Noop);
+    let inner = egui::Frame::new()
+        .inner_margin(14.)
+        .stroke(Stroke::new(1.0_f32, EDGE))
+        .show(ui, add);
+    let r = inner.response.rect;
+    ui.painter().set(face, gradient(r, PANEL_TOP, PANEL));
+    ui.painter().line_segment(
+        [
+            r.left_top() + Vec2::new(1., 1.),
+            r.right_top() + Vec2::new(-1., 1.),
+        ],
+        Stroke::new(1.0_f32, Color32::from_rgba_unmultiplied(255, 255, 255, 16)),
+    );
+    inner.inner
+}
+pub fn caption(ui: &mut egui::Ui, text: &str) {
+    ui.label(RichText::new(text).size(11.).color(MUTED));
+}
+/// Small labelled hardware-style readout.
+pub fn readout(ui: &mut egui::Ui, label: &str, value: String, color: Color32) {
+    ui.label(RichText::new(label).size(11.).color(MUTED));
+    ui.label(RichText::new(value).monospace().size(13.).color(color));
+    ui.add_space(10.);
+}
+/// Product header: accent mark, product name, subtitle, then right-aligned controls.
+pub fn header(ui: &mut egui::Ui, name: &str, subtitle: &str, right: impl FnOnce(&mut egui::Ui)) {
+    ui.horizontal(|ui| {
+        let (mark, _) = ui.allocate_exact_size(Vec2::new(4., 26.), Sense::hover());
+        ui.painter().rect_filled(mark, 1., ACCENT);
+        ui.label(
+            RichText::new(name)
+                .font(FontId::new(26., egui::FontFamily::Name("medium".into())))
+                .color(TEXT),
+        );
+        ui.label(RichText::new(subtitle).size(12.).color(MUTED));
+        ui.with_layout(egui::Layout::right_to_left(egui::Align::Center), right);
+    });
+}
+/// Full-window backdrop gradient used behind every editor.
+pub fn backdrop(ui: &egui::Ui) {
+    ui.painter()
+        .add(gradient(ui.max_rect(), Color32::from_rgb(20, 21, 24), BG));
+}
+/// Horizontal level bar in dBFS (−60..0) with a hairline frame.
+pub fn meter(ui: &mut egui::Ui, label: &str, db: f32, color: Color32, width: f32) {
+    ui.horizontal(|ui| {
+        ui.add_sized(
+            Vec2::new(70., 16.),
+            egui::Label::new(RichText::new(label).size(11.).color(MUTED)),
+        );
+        let (rect, _) = ui.allocate_exact_size(Vec2::new(width, 10.), Sense::hover());
+        let p = ui.painter();
+        p.rect_filled(rect, 1., SCREEN);
+        let t = ((db + 60.) / 60.).clamp(0., 1.);
+        let mut fill = rect;
+        fill.set_width(rect.width() * t);
+        p.rect_filled(fill, 1., color);
+        p.rect_stroke(
+            rect,
+            1.,
+            Stroke::new(1.0_f32, EDGE),
+            egui::StrokeKind::Inside,
+        );
+        ui.label(
+            RichText::new(if db <= -60. {
+                "−∞".to_string()
+            } else {
+                format!("{db:.1} dB")
+            })
+            .monospace()
+            .size(12.)
+            .color(TEXT),
+        );
+    });
+}
@@ -0,0 +1,13 @@
+[package]
+name = "crucible-core"
+version = "0.1.0"
+edition.workspace = true
+license.workspace = true
+
+[dependencies]
+common-dsp = { path = "../../common/dsp" }
+crossbeam-queue = "0.3"
+serde = { workspace = true }
+
+[dev-dependencies]
+serde_json = { workspace = true }