docs(design): propose a multi-band Tone EQ

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) <noreply@anthropic.com>
This commit is contained in:
Vance Ingalls
2026-08-09 20:13:53 -07:00
co-authored by Claude Opus 5
parent 05ea338255
commit 6594cc0d86
2 changed files with 132 additions and 0 deletions
+29
View File
@@ -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
+103
View File
@@ -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 `<div class="fader">
<div class="slot">
<span class="zero"></span>
<span class="fill" style="${b.gain >= 0 ? `top:${pct}%;bottom:50%` : `top:50%;bottom:${100 - pct}%`}"></span>
<span class="cap" style="top:${pct}%"></span>
</div>
<span class="fname">${esc(b.name)}</span>
<span class="fval${on ? " on" : ""}">${b.gain > 0 ? "+" : ""}${b.gain === 0 ? "0" : b.gain}</span>
</div>`;
})
.join("");
}
function eqSummary(bands: Band[]) {
const moved = bands.filter((b) => Math.abs(b.gain) > 0.05);
if (moved.length === 0) return "Flat &mdash; 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 `<figure class="specimen state">
<div class="rack">
<div class="flow">
<div class="node fam-eq" style="--h:oklch(76% 0.13 200)">
<span class="n">02</span>
<div class="nmrow"><span class="nm">Tone</span><span class="tag">${bands.length}-band EQ</span></div>
${collapsed
? `<div class="says">${eqSummary(bands)}</div>`
: `<div class="faders">${eqFaders(bands)}</div>
<div class="eqfoot"><span>Cut</span><span>Boost</span></div>`}
</div>
</div>
</div>
<figcaption><p class="sl">${esc(label)}</p><p class="sn">${note}</p></figcaption>
</figure>`;
}
const eqGrid = [
eqSpecimen(EQ3, "Collapsed", "Reads as the sentence the rest of the rack does &mdash; and says <em>Flat</em> 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 = `<title>FX rack — the casual author's view</title>
.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 = `<title>FX rack — the casual author's view</title>
${modulesByGroup}
</section>
<section>
<h2>The module that should exist</h2>
<p class="lede">
A rack can currently hold two <em>Shape One Range</em> 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 &mdash; and its bands can <em>be</em> the shared vocabulary, so using it
teaches the words everything else uses.
</p>
<div class="mods">${eqGrid}</div>
<p class="lede" style="margin-top:var(--s5)">
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 &mdash; 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.
</p>
</section>
<section>
<h2>One module, every state</h2>
<p class="lede">