feat(core): expose the AudioParams behind automatable FX knobs

Marks the knobs an automation lane can drive and has each graph builder hand
back the AudioParam behind them, so a scheduler can write to a running effect
without knowing what the effect is.

A knob is not always one AudioParam. A wet/dry mix is two gains moving in
opposition, and a knob in milliseconds drives a delay time in seconds, so
each target carries the mapping out of the knob's own declared unit.

What stays unautomatable is stated where it is decided: a WaveShaper curve, a
convolution impulse and a one-pole filter's coefficients are all rebuilt
wholesale rather than scheduled, and the four worklet effects take values by
postMessage rather than through AudioParams.

The registry flag is written by hand, so a test builds every effect and
checks the exposure both ways — nothing flagged is missing, nothing exposed
is unflagged. A flag that lied would offer a lane that silently did nothing.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: vanceingalls

packages/core/src/audio/audioFxGraph.test.ts

@@ -341,3 +341,67 @@ describe("levels and per-channel state", () => {
     expect(buildFxChain(ctx, twoPole(300)).update(twoPole(2000))).toBe(true);
   });
 });
+
+describe("automatable parameters", () => {
+  /**
+   * The registry's `automatable` flag is what the panel and the scheduler both
+   * trust, and it is written by hand. Build every effect and check that each
+   * flagged knob really does reach an AudioParam — a flag that lies would
+   * offer an automation lane that silently does nothing.
+   */
+  it("exposes an AudioParam for every knob the registry marks automatable", () => {
+    for (const def of HF_AUDIO_FX) {
+      const ctx = new FakeCtx() as unknown as BaseAudioContext;
+      const handle = buildFxNode(ctx, def.id, defaultAudioFxParams(def.id));
+      const flagged = def.params
+        .filter((p) => p.kind === "number" && p.automatable)
+        .map((p) => p.key);
+      for (const key of flagged) {
+        const targets = handle.automation?.[key];
+        expect(
+          targets,
+          `${def.id}.${key} is flagged automatable but exposes no AudioParam`,
+        ).toBeTruthy();
+        expect(targets?.length, `${def.id}.${key} exposes an empty target list`).toBeGreaterThan(0);
+      }
+    }
+  });
+
+  it("exposes nothing the registry has not flagged", () => {
+    for (const def of HF_AUDIO_FX) {
+      const ctx = new FakeCtx() as unknown as BaseAudioContext;
+      const handle = buildFxNode(ctx, def.id, defaultAudioFxParams(def.id));
+      const flagged = new Set(
+        def.params.filter((p) => p.kind === "number" && p.automatable).map((p) => p.key),
+      );
+      for (const key of Object.keys(handle.automation ?? {})) {
+        expect(flagged.has(key), `${def.id}.${key} is exposed but not flagged automatable`).toBe(
+          true,
+        );
+      }
+    }
+  });
+
+  it("maps a knob's own unit onto the AudioParam it drives", () => {
+    const ctx = new FakeCtx() as unknown as BaseAudioContext;
+    const delay = buildFxNode(ctx, "delay", { ...defaultAudioFxParams("delay"), time: 250 });
+    // The knob reads milliseconds; delayTime is in seconds.
+    expect(delay.automation?.time?.[0]?.map?.(250)).toBeCloseTo(0.25, 10);
+    // A wet/dry mix is two gains moving in opposition, not one.
+    const mix = delay.automation?.mix ?? [];
+    expect(mix.length).toBe(2);
+    expect(mix[0]?.map?.(0.3) ?? 0.3).toBeCloseTo(0.3, 10);
+    expect(mix[1]?.map?.(0.3)).toBeCloseTo(0.7, 10);
+  });
+
+  it("leaves a one-pole filter unexposed, since its coefficients are fixed", () => {
+    const ctx = new FakeCtx() as unknown as BaseAudioContext;
+    const twoPole = buildFxNode(ctx, "highpass", defaultAudioFxParams("highpass"));
+    expect(twoPole.automation?.frequency?.length).toBe(1);
+    const onePole = buildFxNode(ctx, "highpass", {
+      ...defaultAudioFxParams("highpass"),
+      poles: "1",
+    });
+    expect(onePole.automation?.frequency).toBeUndefined();
+  });
+});

packages/core/src/audio/audioFxGraph.ts

@@ -58,22 +58,59 @@ export function synthesizeReverbImpulse(
   return out;
 }
 
+/**
+ * Where an automation lane writes when it drives one knob.
+ *
+ * A knob is not always one AudioParam. A wet/dry mix is two gains moving in
+ * opposition, and a knob in milliseconds drives a delay time in seconds, so
+ * each target carries its own mapping out of the knob's declared unit.
+ */
+export interface FxParamTarget {
+  param: AudioParam;
+  map?: (value: number) => number;
+}
+
 export interface FxNodeHandle {
   input: AudioNode;
   output: AudioNode;
   update(params: HfAudioFxParamValues): void;
+  /**
+   * AudioParams behind the knobs the registry marks `automatable`, keyed by
+   * parameter key. Absent for a node whose values cannot be scheduled.
+   */
+  automation?: Record<string, FxParamTarget[]>;
   dispose(): void;
 }
 
 type Builder = (ctx: BaseAudioContext, p: HfAudioFxParamValues) => FxNodeHandle;
 
 const n = (v: number | string | undefined): number => (typeof v === "number" ? v : Number(v ?? 0));
 
+/** Milliseconds on the knob, seconds on the AudioParam. */
+const msToSec = (v: number): number => v / 1000;
+
+/** A wet/dry pair: the dry side is whatever the wet side is not. */
+function mixTargets(wet: AudioParam, dry: AudioParam): FxParamTarget[] {
+  return [{ param: wet }, { param: dry, map: (v) => 1 - v }];
+}
+
 /** A node that is its own input and output and has nothing to tear down. */
-function simple(node: AudioNode, update: (p: HfAudioFxParamValues) => void): FxNodeHandle {
-  return { input: node, output: node, update, dispose: () => node.disconnect() };
+function simple(
+  node: AudioNode,
+  update: (p: HfAudioFxParamValues) => void,
+  automation?: Record<string, FxParamTarget[]>,
+): FxNodeHandle {
+  return { input: node, output: node, update, automation, dispose: () => node.disconnect() };
 }
 
+/**
+ * Filter types whose Q a BiquadFilterNode actually reads. The spec leaves it
+ * unused for shelving filters, so the registry offers no shelf Q and the graph
+ * must expose none either — the exposure invariant would otherwise advertise an
+ * AudioParam for a knob nobody can set.
+ */
+const USES_Q: ReadonlySet<BiquadFilterType> = new Set(["peaking", "highpass", "lowpass"]);
+
 function biquad(type: BiquadFilterType, useGain: boolean): Builder {
   return (ctx, p) => {
     const f = ctx.createBiquadFilter();
@@ -84,7 +121,11 @@ function biquad(type: BiquadFilterType, useGain: boolean): Builder {
       if (useGain) f.gain.value = n(v.gain);
     };
     apply(p);
-    return simple(f, apply);
+    return simple(f, apply, {
+      frequency: [{ param: f.frequency }],
+      ...(USES_Q.has(type) ? { q: [{ param: f.Q }] } : {}),
+      ...(useGain ? { gain: [{ param: f.gain }] } : {}),
+    });
   };
 }
 
@@ -102,6 +143,8 @@ function onePoleBuilder(kind: "highpass" | "lowpass"): Builder {
         ? ctx.createIIRFilter([1 / (1 + k), -1 / (1 + k)], [1, (k - 1) / (k + 1)])
         : ctx.createIIRFilter([k / (1 + k), k / (1 + k)], [1, (k - 1) / (k + 1)]);
     // IIRFilterNode coefficients are immutable; the caller rebuilds on change.
+    // Nothing here is schedulable either, so a frequency lane on a one-pole
+    // filter has nowhere to write — the scheduler skips what is not exposed.
     return simple(node, () => {});
   };
 }
@@ -154,6 +197,9 @@ const waveshaper: Builder = (ctx, p) => {
     input: preGain,
     output: postGain,
     update: apply,
+    // The curve itself is rebuilt wholesale, but the make-up gain after it is
+    // an ordinary AudioParam.
+    automation: { output: [{ param: postGain.gain, map: (v) => Math.pow(10, v / 20) }] },
     dispose: () => {
       preGain.disconnect();
       ws.disconnect();
@@ -185,6 +231,11 @@ const delayFeedback: Builder = (ctx, p) => {
     input,
     output: out,
     update: apply,
+    automation: {
+      time: [{ param: dl.delayTime, map: (v) => Math.min(5, msToSec(v)) }],
+      feedback: [{ param: fb.gain }],
+      mix: mixTargets(wet.gain, dry.gain),
+    },
     dispose: () => [input, out, dl, fb, wet, dry].forEach((x) => x.disconnect()),
   };
 };
@@ -213,6 +264,12 @@ const chorusLfo: Builder = (ctx, p) => {
     input,
     output: out,
     update: apply,
+    automation: {
+      delay: [{ param: dl.delayTime, map: msToSec }],
+      depth: [{ param: depth.gain, map: msToSec }],
+      speed: [{ param: lfo.frequency }],
+      mix: mixTargets(wet.gain, dry.gain),
+    },
     dispose: () => {
       try {
         lfo.stop();
@@ -279,6 +336,13 @@ const allpassPhaser: Builder = (ctx, p) => {
     input,
     output: out,
     update: apply,
+    // `delay` and `decay` set the sweep centre, which feeds every stage's
+    // frequency at once — not one knob, one param — so they stay unautomated.
+    automation: {
+      speed: [{ param: lfo.frequency }],
+      in_gain: [{ param: dry.gain }],
+      out_gain: [{ param: wet.gain }],
+    },
     dispose: () => {
       try {
         lfo.stop();
@@ -318,6 +382,9 @@ const convolver: Builder = (ctx, p) => {
     input,
     output: out,
     update: apply,
+    // Size and damping regenerate the impulse response, so only the wet/dry
+    // balance is schedulable.
+    automation: { wet: [{ param: wet.gain }], dry: [{ param: dry.gain }] },
     dispose: () => [input, out, conv, wet, dry].forEach((x) => x.disconnect()),
   };
 };

packages/core/src/audioAutomation.ts

@@ -88,6 +88,8 @@ export interface AutomationRange {
   unit: string;
   label: string;
   scale: "linear" | "log";
+  /** Where an empty lane draws its flat line, and what a new point starts at. */
+  default: number;
 }
 
 export const VOLUME_RANGE: AutomationRange = {
@@ -97,6 +99,7 @@ export const VOLUME_RANGE: AutomationRange = {
   unit: "",
   label: "Volume",
   scale: "linear",
+  default: 1,
 };
 
 /**
@@ -124,6 +127,7 @@ export function resolveAutomationRange(
     unit: p.unit,
     label: `${def?.label ?? node.type} · ${p.label}`,
     scale: p.scale === "log" && p.min > 0 ? "log" : "linear",
+    default: p.default,
   };
 }
 

packages/core/src/audioFx.ts

@@ -33,6 +33,15 @@ export interface HfAudioFxNumberParam {
   default: number;
   /** Frequency-style controls need a log knob to be usable. */
   scale?: "linear" | "log";
+  /**
+   * The knob is backed by an AudioParam, so an automation lane can drive it.
+   *
+   * Not every knob can be: a WaveShaper curve, a convolution impulse and a
+   * worklet's `processorOptions` are all set wholesale rather than scheduled.
+   * A graph builder must expose an AudioParam for every parameter flagged here
+   * — `audioFxGraph.test.ts` builds each effect and checks it.
+   */
+  automatable?: boolean;
   /** One line explaining what turning this does, shown on the control. */
   hint?: string;
 }
@@ -81,6 +90,7 @@ const freq = (
   step: 1,
   default: def,
   scale: "log",
+  automatable: true,
 });
 
 const qParam = (def = 0.707, hint = "Bandwidth — higher is narrower."): HfAudioFxNumberParam => ({
@@ -93,6 +103,7 @@ const qParam = (def = 0.707, hint = "Bandwidth — higher is narrower."): HfAudi
   step: 0.01,
   default: def,
   scale: "log",
+  automatable: true,
   hint,
 });
 
@@ -105,6 +116,7 @@ const gainDb = (min = -40, max = 40, def = 0): HfAudioFxNumberParam => ({
   max,
   step: 0.1,
   default: def,
+  automatable: true,
 });
 
 const poles: HfAudioFxEnumParam = {
@@ -411,6 +423,7 @@ export const HF_AUDIO_FX: readonly HfAudioFxDef[] = [
       {
         kind: "number",
         key: "output",
+        automatable: true,
         label: "Output",
         unit: "dB",
         min: -24,
@@ -482,6 +495,7 @@ export const HF_AUDIO_FX: readonly HfAudioFxDef[] = [
       {
         kind: "number",
         key: "time",
+        automatable: true,
         label: "Time",
         unit: "ms",
         min: 1,
@@ -495,6 +509,7 @@ export const HF_AUDIO_FX: readonly HfAudioFxDef[] = [
       {
         kind: "number",
         key: "feedback",
+        automatable: true,
         label: "Feedback",
         unit: "",
         min: 0.01,
@@ -505,6 +520,7 @@ export const HF_AUDIO_FX: readonly HfAudioFxDef[] = [
       {
         kind: "number",
         key: "mix",
+        automatable: true,
         label: "Mix",
         unit: "",
         min: 0,
@@ -524,6 +540,7 @@ export const HF_AUDIO_FX: readonly HfAudioFxDef[] = [
       {
         kind: "number",
         key: "delay",
+        automatable: true,
         label: "Delay",
         unit: "ms",
         min: 1,
@@ -534,6 +551,7 @@ export const HF_AUDIO_FX: readonly HfAudioFxDef[] = [
       {
         kind: "number",
         key: "depth",
+        automatable: true,
         label: "Depth",
         unit: "ms",
         min: 0,
@@ -544,6 +562,7 @@ export const HF_AUDIO_FX: readonly HfAudioFxDef[] = [
       {
         kind: "number",
         key: "speed",
+        automatable: true,
         label: "Rate",
         unit: "Hz",
         min: 0.01,
@@ -554,6 +573,7 @@ export const HF_AUDIO_FX: readonly HfAudioFxDef[] = [
       {
         kind: "number",
         key: "mix",
+        automatable: true,
         label: "Mix",
         unit: "",
         min: 0,
@@ -573,6 +593,7 @@ export const HF_AUDIO_FX: readonly HfAudioFxDef[] = [
       {
         kind: "number",
         key: "in_gain",
+        automatable: true,
         label: "Input",
         unit: "",
         min: 0,
@@ -583,6 +604,7 @@ export const HF_AUDIO_FX: readonly HfAudioFxDef[] = [
       {
         kind: "number",
         key: "out_gain",
+        automatable: true,
         label: "Output",
         unit: "",
         min: 0,
@@ -615,6 +637,7 @@ export const HF_AUDIO_FX: readonly HfAudioFxDef[] = [
       {
         kind: "number",
         key: "speed",
+        automatable: true,
         label: "Rate",
         unit: "Hz",
         min: 0.1,
@@ -666,6 +689,7 @@ export const HF_AUDIO_FX: readonly HfAudioFxDef[] = [
       {
         kind: "number",
         key: "wet",
+        automatable: true,
         label: "Wet",
         unit: "",
         min: 0,
@@ -676,6 +700,7 @@ export const HF_AUDIO_FX: readonly HfAudioFxDef[] = [
       {
         kind: "number",
         key: "dry",
+        automatable: true,
         label: "Dry",
         unit: "",
         min: 0,