feat: the shared frequency ruler, so the vocabulary gets taught

`BANDS` has named the ranges since the copy layer landed — rumble,
weight, mud, middle, presence, edge, air — and nothing showed them. The
rack spoke entirely in Hz, which mean nothing to somebody who has not
been taught them, and the words that would teach them sat unread in core.

Every spectral module now shows where it acts on one ruler. Two things at
once, deliberately: the bar says where this module works relative to
everything else, and the caption names the range and what lives there.
A bar alone is decoration; a caption alone does not teach the shape.

Log-spaced, because hearing is. Rumble is 20–80 Hz — three tenths of one
percent of the range linearly and about a fifth of it by ear — so laid
out linearly the bottom six bands collapse into a sliver and the ruler
teaches nothing. A test asserts the bottom segment is over a tenth of the
bar, which a linear layout fails.

Segments outside what the module can reach are dimmed rather than hidden:
a filter that only works in the bottom three bands should not look like
it could move anywhere, and it should still be legible against the whole
range.

`audioBandAt` clamps past both ends rather than returning nothing — 15 Hz
is still rumble to anybody who can hear it, and the alternative is a
filter parked at the edge of its range having no name at all. Boundaries
belong to the band they open, or a filter at exactly 250 Hz reads as
Weight while the ruler beside it highlights Mud.

Nothing under an effect with no range to place: there is nothing spectral
about a limiter, and a bar under one would be a decoration claiming to be
information.

core 1754 passing (112 files), studio 3690 passing / 18 todo.

Author: vanceingalls

packages/core/src/audioFxCopy.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from "vitest";
 import { defaultAudioFxParams, HF_AUDIO_FX } from "./audioFx.js";
 import { HF_AUDIO_FX_PRESETS } from "./audioFxPresets.js";
-import { BANDS, EFFECT_COPY, PRESET_PROBLEM, SUMMARY } from "./audioFxCopy.js";
+import { audioBandAt, BANDS, EFFECT_COPY, PRESET_PROBLEM, SUMMARY } from "./audioFxCopy.js";
 
 /**
  * The copy layer is only worth having if it covers everything that ships. A gap
@@ -73,3 +73,33 @@ it("covers the spectrum without a gap or an overlap", () => {
     expect(BANDS[i]?.from, `gap or overlap before ${BANDS[i]?.name}`).toBe(BANDS[i - 1]?.to);
   }
 });
+
+describe("audioBandAt", () => {
+  it("names the range a frequency sits in", () => {
+    expect(audioBandAt(50)?.name).toBe("Rumble");
+    expect(audioBandAt(250)?.name).toBe("Mud");
+    expect(audioBandAt(3000)?.name).toBe("Presence");
+    expect(audioBandAt(12000)?.name).toBe("Air");
+  });
+
+  it("puts a boundary in the band it opens, not the one it closes", () => {
+    // Off by one here means a filter at exactly 250 Hz reads as "Weight" while
+    // the ruler beside it highlights Mud.
+    for (let i = 1; i < BANDS.length; i++) {
+      const edge = BANDS[i]?.from;
+      if (edge === undefined) continue;
+      expect(audioBandAt(edge)?.name).toBe(BANDS[i]?.name);
+    }
+  });
+
+  it("clamps past both ends rather than going nameless", () => {
+    // A filter parked at the edge of its range still has to say where it works.
+    expect(audioBandAt(5)?.name).toBe(BANDS[0]?.name);
+    expect(audioBandAt(30000)?.name).toBe(BANDS.at(-1)?.name);
+    expect(audioBandAt(20000)?.name).toBe(BANDS.at(-1)?.name);
+  });
+
+  it("has no answer for a value that is not a frequency", () => {
+    expect(audioBandAt(Number.NaN)).toBeUndefined();
+  });
+});

packages/core/src/audioFxCopy.ts

@@ -294,6 +294,24 @@ export const BANDS: { from: number; to: number; name: string; says: string }[] =
   { from: 10000, to: 20000, name: "Air", says: "sparkle, openness" },
 ];
 
+/**
+ * Which named range a frequency falls in.
+ *
+ * The whole point of `BANDS` is that the words get taught, and they only get
+ * taught if a module can say which one it is working in. Below the first band
+ * and above the last both clamp rather than returning nothing: 15 Hz is still
+ * rumble to anybody who can hear it, and the alternative is a filter at the edge
+ * of its range having no name at all.
+ */
+export function audioBandAt(hz: number): (typeof BANDS)[number] | undefined {
+  if (!Number.isFinite(hz)) return undefined;
+  const first = BANDS[0];
+  const last = BANDS.at(-1);
+  if (first && hz < first.from) return first;
+  if (last && hz >= last.to) return last;
+  return BANDS.find((band) => hz >= band.from && hz < band.to);
+}
+
 /** Which everyday complaint each preset answers. Presets ARE the product here. */
 export const PRESET_PROBLEM: Record<string, string> = {
   "voice-clean": "My voice sounds amateur",

packages/studio/src/components/editor/propertyPanelFxBandRuler.tsx

@@ -0,0 +1,72 @@
+/**
+ * The shared frequency ruler.
+ *
+ * Frequencies mean nothing to somebody who has not been taught them, and the
+ * rack speaks entirely in them. `BANDS` names the ranges in the words the same
+ * person would use unprompted — rumble, weight, mud, middle, presence, edge,
+ * air — and every spectral module shows where it acts on this one ruler, so
+ * naming them once teaches them everywhere they appear.
+ *
+ * Two things at once, deliberately. The bar says where this module works
+ * relative to everything else, which is the spatial fact; the caption under it
+ * names the range and what lives there, which is the vocabulary. A bar alone
+ * would be decoration and a caption alone would not teach the shape.
+ *
+ * Log-spaced, because hearing is: 20–200 Hz is as much of the range to an ear as
+ * 2–20 kHz, and a linear ruler would crush six of the seven bands into a corner.
+ */
+
+import { audioBandAt, BANDS } from "@hyperframes/core/audio-fx-copy";
+
+const LOW = BANDS[0]?.from ?? 20;
+const HIGH = BANDS.at(-1)?.to ?? 20000;
+
+/** Where a frequency sits across the ruler, 0..1. */
+function positionOf(hz: number): number {
+  const span = Math.log10(HIGH) - Math.log10(LOW);
+  const at = (Math.log10(Math.min(HIGH, Math.max(LOW, hz))) - Math.log10(LOW)) / span;
+  return Math.min(1, Math.max(0, at));
+}
+
+export interface FxBandRulerProps {
+  /** The range this effect can act over, from its copy. */
+  band: readonly [number, number];
+  /** Where it is acting right now. */
+  at: number;
+}
+
+export function FxBandRuler({ band, at }: FxBandRulerProps) {
+  const here = audioBandAt(at);
+  if (!here) return null;
+  const [from, to] = band;
+  return (
+    <div className="hf-fx-ruler px-1.5 pb-1" data-band={here.name}>
+      <div className="hf-fx-ruler-bar relative flex h-1 w-full overflow-hidden rounded-[1px]">
+        {BANDS.map((range) => {
+          // Reachable at all, and where it is now: a module that can only work in
+          // the bottom three bands should not look like it could move anywhere.
+          const reachable = range.to > from && range.from < to;
+          return (
+            <span
+              key={range.name}
+              title={`${range.name} — ${range.says}`}
+              className={
+                range.name === here.name
+                  ? "hf-fx-ruler-band bg-panel-accent"
+                  : reachable
+                    ? "hf-fx-ruler-band bg-panel-text-4/50"
+                    : "hf-fx-ruler-band bg-panel-text-4/15"
+              }
+              style={{
+                width: `${(positionOf(range.to) - positionOf(range.from)) * 100}%`,
+              }}
+            />
+          );
+        })}
+      </div>
+      <p className="hf-fx-ruler-label truncate pt-0.5 text-[9px] text-panel-text-4">
+        <span className="hf-fx-ruler-name text-panel-text-1">{here.name}</span> — {here.says}
+      </p>
+    </div>
+  );
+}

packages/studio/src/components/editor/propertyPanelFxNodeRow.tsx

@@ -21,6 +21,7 @@ import {
 import { EFFECT_COPY, SUMMARY } from "@hyperframes/core/audio-fx-copy";
 import { fxAutomationTarget } from "@hyperframes/core/audio-automation";
 import { FxParams } from "./propertyPanelFxControls.js";
+import { FxBandRuler } from "./propertyPanelFxBandRuler.js";
 
 /**
  * The one control that carries the module, if it has one.
@@ -347,6 +348,12 @@ export function FxNodeRow({
                   <span className="truncate text-right">{copy.primaryEnds.high}</span>
                 </p>
               ) : null}
+              {/* Where it is working, in the words the rack shares. Only for a
+                  module that acts on a range at all — there is nothing spectral
+                  about a limiter, and a ruler under one would be noise. */}
+              {copy?.band && typeof params.frequency === "number" ? (
+                <FxBandRuler band={copy.band} at={params.frequency} />
+              ) : null}
             </>
           ) : null}
           {/* The DSP name lives on the disclosure, so it is read at the moment

packages/studio/src/components/editor/propertyPanelFxSection.test.tsx

@@ -8,7 +8,7 @@ import {
   type HfAudioFxChain,
 } from "@hyperframes/core/audio-fx";
 import { DEFAULT_CARVE } from "@hyperframes/core/audio-carve";
-import { EFFECT_COPY, PRESET_PROBLEM } from "@hyperframes/core/audio-fx-copy";
+import { BANDS, EFFECT_COPY, PRESET_PROBLEM } from "@hyperframes/core/audio-fx-copy";
 import { HF_AUDIO_FX_JOBS, HF_AUDIO_FX_JOB_TYPES } from "@hyperframes/core/audio-fx-jobs";
 import { getAudioFxPreset } from "@hyperframes/core/audio-fx-presets";
 
@@ -362,6 +362,35 @@ describe("FxSection chain", () => {
     );
   });
 
+  it("says where a filter is working, in the words the rack shares", () => {
+    // Frequencies mean nothing to somebody who has not been taught them, and the
+    // rack speaks entirely in them. The ruler is where they get taught.
+    const { host } = mount({
+      chain: {
+        version: 1,
+        nodes: [{ type: "highpass", params: { frequency: 250, q: 0.707, poles: "2" } }],
+      } as unknown as HfAudioFxChain,
+    });
+    const ruler = fxCard(host).querySelector(".hf-fx-ruler");
+    expect(ruler?.getAttribute("data-band")).toBe("Mud");
+    expect(ruler?.querySelector(".hf-fx-ruler-name")?.textContent).toBe("Mud");
+    // Every named range is on the bar, or it is not a shared ruler.
+    const segments = Array.from(ruler?.querySelectorAll<HTMLElement>(".hf-fx-ruler-band") ?? []);
+    expect(segments).toHaveLength(BANDS.length);
+    // Log-spaced, because hearing is. Rumble is 20-80 Hz — three tenths of one
+    // percent of the range linearly, and a fifth of it by ear. Laid out linearly
+    // the bottom six bands collapse into a sliver and the ruler teaches nothing.
+    const rumble = Number.parseFloat(segments[0]?.style.width ?? "0");
+    expect(rumble).toBeGreaterThan(10);
+  });
+
+  it("puts no ruler under an effect that does not act on a range", () => {
+    // A limiter has no frequency to place, and a bar under one would be a
+    // decoration claiming to be information.
+    const { host } = mount({ chain: chainOf("limiter") });
+    expect(fxCard(host).querySelector(".hf-fx-ruler")).toBeNull();
+  });
+
   it("opens a module on all of its controls when its one knob does not exist yet", () => {
     // Five effects want a single DERIVED control over several parameters — the
     // `PROFILES` idea, whose figures are proposed rather than measured. Until it