From 6594cc0d8658f37e8cfd246fabc4d2b33ab0e18b Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Sun, 9 Aug 2026 20:13:53 -0700 Subject: [PATCH] docs(design): propose a multi-band Tone EQ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The clearest failure this exercise surfaced is a rack holding two Shape One Range modules doing different jobs. A multi-band EQ answers it better than a per-node role label would, because an author already understands it — bass, middle, treble is the most widely used audio control there is. Its bands can BE the shared vocabulary: three are Bass / Middle / Treble, five open to Bass / Warmth / Middle / Clarity / Air. So using the EQ teaches the words the rest of the rack relies on, rather than the vocabulary living only on a ruler somebody has to go and read. Built like the carve, not like a new effect. Carve already owns several tagged nodes and presents as one module; an EQ does the same with `fromEq`. Three bands are a low shelf, a peaking and a high shelf — all already shipping. There is nothing new in the graph or the render, and the nodes stay ordinary, so an author who opens the details finds the filters they could have added by hand. That route also sidesteps a real constraint: the registry's parameter model is flat key/value, so an `eq` effect TYPE with N bands would need array-shaped params it does not support. Drawn with vertical faders around a centre detent, because that is what an equaliser looks like to everyone who has met one. Collapsed, it reads like every other module — "Bass +3, Middle -2, Treble +2", or "Flat" when nothing has been touched. Design only; not built. Co-Authored-By: Claude Opus 5 (1M context) --- plans/audio-fx-ux/README.md | 29 ++++++++ plans/audio-fx-ux/build-preview.mts | 103 ++++++++++++++++++++++++++++ 2 files changed, 132 insertions(+) diff --git a/plans/audio-fx-ux/README.md b/plans/audio-fx-ux/README.md index 90335f3c09..50d5a45199 100644 --- a/plans/audio-fx-ux/README.md +++ b/plans/audio-fx-ux/README.md @@ -97,6 +97,35 @@ property print as their escape sequence on the page. This cost three rounds of chasing what looked like three unrelated rendering bugs. The template is a plain literal; keep it that way, and use HTML entities for typographic characters. +## Proposed: a multi-band EQ ("Tone") + +The clearest failure this exercise surfaced is a rack holding two *Shape One +Range* modules doing different jobs. A multi-band EQ is the answer, and it is a +better one than a role label because an author already understands it: bass, +middle, treble is the most widely used audio control there is. + +**Its bands can be the shared vocabulary.** Three bands are Bass / Middle / +Treble; five open up to Bass / Warmth / Middle / Clarity / Air. So using the EQ +teaches the words the rest of the rack relies on, instead of the vocabulary +living only on a ruler somebody has to read. + +**Built like the carve, not like a new effect.** Carve already owns several +tagged nodes and presents as one module (`fromCarve`, filtered out of the +hand-built list). An EQ does the same with `fromEq`: three bands are a low +shelf, a peaking and a high shelf — all effects that already ship. Nothing new +in the render, nothing new in the graph, and the nodes stay ordinary, so an +author who opens the details finds exactly the filters they could have added by +hand. + +The registry's parameter model is flat key/value, so an `eq` effect *type* with +N bands would need array-shaped params it does not support. The composite-module +route avoids that entirely and is the pattern this codebase already proved. + +Faders rather than sliders, because a row of vertical faders around a centre +detent is what an equaliser looks like to everyone who has met one. Collapsed, +it reads like every other module: "Bass +3, Middle −2, Treble +2", or "Flat" +when nothing has been touched. + ## What still needs deciding - Does the plain name **replace** the DSP name or sit beside it? Replacing is diff --git a/plans/audio-fx-ux/build-preview.mts b/plans/audio-fx-ux/build-preview.mts index 163f8fde8b..6073c75ac1 100644 --- a/plans/audio-fx-ux/build-preview.mts +++ b/plans/audio-fx-ux/build-preview.mts @@ -210,6 +210,72 @@ const statesGrid = [ stateSpecimen("peaking", { frequency: 400, gain: -8.2, q: 1.4 }, { label: "Measuring", smart: true, locked: true, note: "A smart module analysing. The rack locks while it works — nothing here can be edited into an inconsistent state." }), ].join(""); + +/* ---- the module that should exist: a multi-band EQ ---------------------- */ +type Band = { name: string; hz: number; gain: number; kind: string }; +const EQ3: Band[] = [ + { name: "Bass", hz: 200, gain: 3, kind: "lowshelf" }, + { name: "Middle", hz: 1000, gain: -2, kind: "peaking" }, + { name: "Treble", hz: 4000, gain: 2, kind: "highshelf" }, +]; +const EQ5: Band[] = [ + { name: "Bass", hz: 160, gain: 2, kind: "lowshelf" }, + { name: "Warmth", hz: 350, gain: -3.5, kind: "peaking" }, + { name: "Middle", hz: 1000, gain: 0, kind: "peaking" }, + { name: "Clarity", hz: 3000, gain: 2.5, kind: "peaking" }, + { name: "Air", hz: 9000, gain: 1.5, kind: "highshelf" }, +]; + +/** Faders, because a row of them IS what an equaliser looks like to everyone. */ +function eqFaders(bands: Band[]) { + return bands + .map((b) => { + // -12..+12 dB across the fader; centre is flat. + const pct = 50 - (b.gain / 24) * 100; + const on = Math.abs(b.gain) > 0.05; + return `
+
+ + + +
+ ${esc(b.name)} + ${b.gain > 0 ? "+" : ""}${b.gain === 0 ? "0" : b.gain} +
`; + }) + .join(""); +} + +function eqSummary(bands: Band[]) { + const moved = bands.filter((b) => Math.abs(b.gain) > 0.05); + if (moved.length === 0) return "Flat — nothing changed yet"; + return moved.map((b) => `${b.name} ${b.gain > 0 ? "+" : ""}${b.gain}`).join(", "); +} + +function eqSpecimen(bands: Band[], label: string, note: string, collapsed = false) { + return `
+
+
+
+ 02 +
Tone${bands.length}-band EQ
+ ${collapsed + ? `
${eqSummary(bands)}
` + : `
${eqFaders(bands)}
+
CutBoost
`} +
+
+
+

${esc(label)}

${note}

+
`; +} + +const eqGrid = [ + eqSpecimen(EQ3, "Collapsed", "Reads as the sentence the rest of the rack does — and says Flat when nothing has been touched.", true), + eqSpecimen(EQ3, "Three bands", "Bass, middle, treble. The most widely understood audio control there is: everybody has used one on a car stereo.", false), + eqSpecimen(EQ5, "Five bands", "The same module opened up. Band names are the shared vocabulary, so using the EQ teaches the words the rest of the rack uses.", false), +].join(""); + /* ---- presets ------------------------------------------------------------ */ function presetCard(p: (typeof HF_AUDIO_FX_PRESETS)[number]) { const nodes = p.nodes @@ -427,6 +493,26 @@ const html = `FX rack — the casual author's view .rack.locked::after { content:""; position:absolute; inset:0; border-radius:3px; background:repeating-linear-gradient(135deg, transparent 0 6px, oklch(60% .012 250 / .05) 6px 12px); pointer-events:none; } + /* ---- multi-band EQ ---- */ + .fam-eq .nm { font-family:"DIN Alternate","Oswald",sans-serif; text-transform:uppercase; + letter-spacing:.1em; font-size:14px; font-weight:600; } + .faders { display:flex; gap:6px; margin-top:11px; } + .fader { flex:1; display:flex; flex-direction:column; align-items:center; gap:5px; min-width:0; } + .slot { position:relative; width:100%; height:74px; border-radius:2px; + background:linear-gradient(90deg, transparent calc(50% - 1px), oklch(26% .012 250) calc(50% - 1px), + oklch(26% .012 250) calc(50% + 1px), transparent calc(50% + 1px)); } + .zero { position:absolute; left:0; right:0; top:50%; height:1px; background:oklch(34% .012 250); } + .fill { position:absolute; left:calc(50% - 1.5px); width:3px; background:var(--h); border-radius:2px; } + .cap { position:absolute; left:50%; width:19px; height:7px; border-radius:1px; + background:oklch(80% .008 250); transform:translate(-50%,-50%); + box-shadow:0 1px 2px oklch(0% 0 0 / .6); } + .fname { font-family:"DIN Alternate",sans-serif; font-size:9.5px; letter-spacing:.06em; + text-transform:uppercase; color:oklch(72% .012 250); text-align:center; } + .fval { font-family:Monaco,monospace; font-size:9px; color:oklch(50% .012 250); font-variant-numeric:tabular-nums; } + .fval.on { color:var(--h); } + .eqfoot { display:flex; justify-content:space-between; margin-top:7px; + font-family:Monaco,monospace; font-size:8.5px; color:oklch(50% .012 250); letter-spacing:.08em; } + /* profiles */ .profs { display:grid; grid-template-columns:repeat(auto-fit,minmax(300px,1fr)); gap:var(--s4); } .prof { background:var(--card); border:1px solid var(--line); border-radius:4px; padding:var(--s4); } @@ -489,6 +575,23 @@ const html = `FX rack — the casual author's view ${modulesByGroup} +
+

The module that should exist

+

+ A rack can currently hold two Shape One Range modules doing different jobs, which is + the clearest failure on this page. A multi-band EQ collapses them into one module an author + already understands — and its bands can be the shared vocabulary, so using it + teaches the words everything else uses. +

+
${eqGrid}
+

+ Built the way the carve already is: one module owning several tagged nodes rather than a new + DSP primitive. Three bands are a low shelf, a peaking and a high shelf — effects that + already ship. Nothing new to render, and the nodes stay ordinary, so an author who opens the + details finds the same filters they could have added by hand. +

+
+

One module, every state