Files
hyperframes/packages/core/src/audio/audioFxGraph.test.ts
T
Jerrai 3746703ea7 feat(core): truepeak, a lookahead true-peak limiter FX (#5419)
* feat(core): add a lookahead true-peak limiter FX (truepeak)

The existing limiter is an envelope follower with no lookahead and no
inter-sample detection, so a -14 dB ceiling can leave the true peak several dB
over. truepeak estimates the true peak on a 4x polyphase interpolator, takes the
minimum required gain over a lookahead window and smooths it with a boxcar of
the same length, so the gain is already down when the peak leaves the delay
line. Release is exponential and can only lower the gain further; channels
share one gain.

The offline render lengthens the OfflineAudioContext by the chain's latency and
drops the lead-in, so a limited clip stays sample-aligned with its source.
Preview plays the lookahead (about 3.3 ms at the default).

— Jerrai

* docs(audio): truepeak ceiling is a 4x estimate; measure it with an ideal interpolator

The unit test's meter was a 96-tap Kaiser sinc, which rolls off near Nyquist and
reads full-band noise about 0.5 dB low, so the PR reported a 0.3 dB broadband
overshoot. Against an ideal 16x interpolation (zero-padded FFT, cross-checked with
a 16x soxr resample) hot full-band white noise ends 1.2 to 1.7 dB over the ceiling
(median 1.4 over 28 runs of 10 to 30 s). ffmpeg's ebur128 true peak is also a 4x
meter and reads the same files 0.1 dB over.

- The test meter is now the FFT interpolation. Tolerances are what it measures on
  each fixed signal: tones 0.01 dB (they land on the ceiling), the dense program
  0.5 dB (reads 0.445, the old 0.4 passed only because the meter read low), and a
  new full-band noise case at -1, -6 and -14 dBTP with 1.35 dB (reads 1.09 to 1.31).
- audio-effects.mdx and the hyperframes-audio skill say the ceiling is a 4x
  estimate, give the measured overshoot and recommend a 2 dB margin under a hard
  delivery limit.
- skills-manifest.json regenerated.

— Jerrai

* fix(core): truepeak UI copy no longer promises a hard ceiling

The registry description and the rack summary said the true peak is never above
the ceiling. The limiter holds a 4x estimate, and full-band noise can land up to
about 1.7 dB above it, as the docs now say. The summary reads "held near", the
description names the estimate and the overshoot, and the rack blurb says "holds
... to a ceiling". No skill file changed, so the skills manifest is unchanged.

— Jerrai

* fix(core): Studio truepeak copy states the 4x-estimate margin

The ceiling control was labelled "Never exceed" and the module said the mix
"must not clip", so a Studio user never saw that dense full-band content can end
up to about 1.7 dB above the ceiling. The label is now "Target ceiling" with a
hint that names the 4x estimate and the headroom to leave, the blurb says
"toward a target ceiling", the rack summary says peaks are pulled down toward the
value, and the registry hint no longer says "highest true peak allowed". The
audio skill's "hard dBTP ceiling" wording is gone and the skills manifest is
regenerated. A copy test keeps the promise out.

— Jerrai

* fix(core): truepeak clears on a seek, and the review nits (fallow, comments)

- Unexport TRUE_PEAK_OVERSAMPLE, TRUE_PEAK_DETECTOR_DELAY and
  truePeakLookaheadSamples: nothing imports them (Fallow audit).
- A persistent group bus keeps its chain across a seek, so the limiter's
  delay line and held gain carried over. The worklet takes __hfReset, the
  graph exposes FxChainHandle.reset(), and reanchor() calls it.
- The processor-loading harness is shared by the truepeak and worklet tests
  (it was a 12-line clone); the test FFT no longer repeats audioCarve's
  bit-reversal; two test bodies are under the CRAP threshold.
- Comment blocks cut to four lines or fewer (Comments check).
- Docs state the preview delay in ms.

— Jerrai
2026-10-10 18:28:21 +00:00

793 lines
31 KiB
TypeScript

// @vitest-environment happy-dom
import { describe, expect, it } from "vitest";
import { defaultAudioFxParams, HF_AUDIO_FX, type HfAudioFxChain } from "../audioFx.js";
import {
buildFxChain,
buildFxNode,
chainNeedsWorklets,
synthesizeReverbImpulse,
} from "./audioFxGraph.js";
/**
* happy-dom has no Web Audio, and a real AudioContext needs a browser. These
* cover the graph wiring: which nodes get made, how they connect, and when an
* update can happen in place instead of forcing a rebuild. Whether each graph
* *sounds* like its FFmpeg counterpart is a separate measurement — that is the
* parity harness's job, and it runs in a real browser.
*/
class FakeParam {
constructor(public value = 0) {}
}
class FakeNode {
connections: FakeNode[] = [];
disconnected = false;
frequency = new FakeParam();
Q = new FakeParam();
gain = new FakeParam();
delayTime = new FakeParam();
playbackRate = new FakeParam();
loop = false;
type = "";
curve: Float32Array | null = null;
oversample = "none";
buffer: FakeBuffer | null = null;
normalize = true;
port = { postMessage: (m: unknown) => this.messages.push(m) };
messages: unknown[] = [];
/** `start(when, offset)` — the offset is the LFO's phase, so it is asserted. */
startArgs: (number | undefined)[] | null = null;
constructor(public kind: string) {}
connect(next: FakeNode): FakeNode {
this.connections.push(next);
return next;
}
disconnect(): void {
this.disconnected = true;
}
start(...args: (number | undefined)[]): void {
this.startArgs = args;
}
stop(): void {}
}
/** One channel, kept across `getChannelData` calls so what is written can be read. */
class FakeBuffer {
private data: Float32Array;
constructor(public length: number) {
this.data = new Float32Array(length);
}
getChannelData(): Float32Array {
return this.data;
}
}
class FakeCtx {
sampleRate = 48000;
created: FakeNode[] = [];
private make(kind: string): FakeNode {
const node = new FakeNode(kind);
this.created.push(node);
return node;
}
createGain() {
return this.make("gain");
}
createBiquadFilter() {
return this.make("biquad");
}
createIIRFilter() {
return this.make("iir");
}
createDelay() {
return this.make("delay");
}
createOscillator() {
return this.make("osc");
}
createBufferSource() {
return this.make("bufferSource");
}
createWaveShaper() {
return this.make("waveshaper");
}
createConvolver() {
return this.make("convolver");
}
createBuffer(_c: number, length: number) {
return new FakeBuffer(length);
}
}
// AudioWorkletNode is constructed directly, not via a context factory, so the
// instances are recorded here rather than in FakeCtx.created.
const workletNodes: FakeWorkletNode[] = [];
class FakeWorkletNode extends FakeNode {
constructor(
_ctx: unknown,
public name: string,
public options: { processorOptions: unknown },
) {
super("worklet");
workletNodes.push(this);
}
}
(globalThis as unknown as { AudioWorkletNode: unknown }).AudioWorkletNode = FakeWorkletNode;
const ctx = (): FakeCtx => new FakeCtx();
const asCtx = (c: FakeCtx) => c as unknown as BaseAudioContext;
const chain = (...types: string[]): HfAudioFxChain => ({
version: 1,
nodes: types.map((t) => ({ type: t, enabled: true, params: defaultAudioFxParams(t) })),
});
describe("buildFxNode", () => {
it("builds a node for every effect in the registry", () => {
for (const def of HF_AUDIO_FX) {
const c = ctx();
expect(
() => buildFxNode(asCtx(c), def.id, defaultAudioFxParams(def.id)),
`${def.id} failed to build`,
).not.toThrow();
}
});
it("rejects an unknown effect", () => {
expect(() => buildFxNode(asCtx(ctx()), "nope", {})).toThrow(/Unknown effect/);
});
it("uses a two-pole biquad by default and a one-pole IIR when asked", () => {
const two = ctx();
buildFxNode(asCtx(two), "highpass", { ...defaultAudioFxParams("highpass"), poles: "2" });
expect(two.created.some((n) => n.kind === "biquad")).toBe(true);
expect(two.created.some((n) => n.kind === "iir")).toBe(false);
const one = ctx();
buildFxNode(asCtx(one), "highpass", { ...defaultAudioFxParams("highpass"), poles: "1" });
expect(one.created.some((n) => n.kind === "iir")).toBe(true);
});
it("applies parameters to the biquad rather than leaving defaults", () => {
const c = ctx();
buildFxNode(asCtx(c), "peaking", { frequency: 750, gain: -9, q: 3 });
const bq = c.created.find((n) => n.kind === "biquad")!;
expect(bq.type).toBe("peaking");
expect(bq.frequency.value).toBe(750);
expect(bq.gain.value).toBe(-9);
expect(bq.Q.value).toBe(3);
});
it("clamps an out-of-range value on the way into the graph", () => {
const c = ctx();
buildFxNode(asCtx(c), "peaking", { frequency: 10_000_000, gain: 0, q: 1 });
expect(c.created.find((n) => n.kind === "biquad")!.frequency.value).toBe(20000);
});
it("sends worklet parameters through the port on update", () => {
workletNodes.length = 0;
const c = ctx();
const h = buildFxNode(asCtx(c), "compressor", defaultAudioFxParams("compressor"));
expect(workletNodes).toHaveLength(1);
expect(workletNodes[0]!.name).toBe("hf-compressor");
h.update({ ...defaultAudioFxParams("compressor"), threshold: -30 });
// Turning a dial re-parameterises the running processor instead of
// rebuilding it, which is what keeps the knob-to-ear loop immediate.
expect(workletNodes[0]!.messages).toHaveLength(1);
expect(workletNodes[0]!.messages[0]).toMatchObject({ threshold: -30 });
});
it("tells a worklet processor to retire on dispose, not just disconnect it", () => {
// Disconnecting leaves the processor alive — it lives until `process()`
// returns false — so every rebuild that dropped a worklet effect left one
// running on the audio thread for the rest of the session.
workletNodes.length = 0;
const h = buildFxNode(asCtx(ctx()), "compressor", defaultAudioFxParams("compressor"));
h.dispose();
expect(workletNodes[0]!.messages).toEqual([{ __hfDispose: true }]);
});
it("rebuilds the saturation curve for the selected shape", () => {
const c = ctx();
buildFxNode(asCtx(c), "saturate", { ...defaultAudioFxParams("saturate"), type: "hard" });
const ws = c.created.find((n) => n.kind === "waveshaper")!;
expect(ws.curve).toBeInstanceOf(Float32Array);
// A hard clip saturates to the threshold and stays flat at the extremes.
expect(ws.curve!.at(-1)).toBeCloseTo(ws.curve![ws.curve!.length - 2]!, 6);
});
});
describe("buildFxChain", () => {
it("passes audio straight through for an empty chain", () => {
const c = ctx();
const h = buildFxChain(asCtx(c), { version: 1, nodes: [] });
expect(h.input.connect).toBeDefined();
expect((h.input as unknown as FakeNode).connections).toContain(h.output);
});
it("chains effects in order", () => {
const c = ctx();
const h = buildFxChain(asCtx(c), chain("highpass", "peaking"));
// input -> highpass -> peaking -> output, so input reaches exactly one node.
expect((h.input as unknown as FakeNode).connections).toHaveLength(1);
expect(c.created.filter((n) => n.kind === "biquad")).toHaveLength(2);
});
it("skips bypassed nodes", () => {
const c = ctx();
buildFxChain(asCtx(c), {
version: 1,
nodes: [
{ type: "peaking", enabled: false, params: defaultAudioFxParams("peaking") },
{ type: "lowpass", enabled: true, params: defaultAudioFxParams("lowpass") },
],
});
expect(c.created.filter((n) => n.kind === "biquad")).toHaveLength(1);
});
it("updates in place when only values changed", () => {
const c = ctx();
const h = buildFxChain(asCtx(c), chain("peaking"));
const before = c.created.length;
const ok = h.update({
version: 1,
nodes: [{ type: "peaking", enabled: true, params: { frequency: 2000, gain: 5, q: 2 } }],
});
expect(ok).toBe(true);
expect(c.created.length).toBe(before); // nothing rebuilt
expect(c.created.find((x) => x.kind === "biquad")!.frequency.value).toBe(2000);
});
it("lines new values up against the built nodes, skipping a bypassed one", () => {
// A bypassed node is not in the graph, so the update has to walk the
// ENABLED nodes to stay aligned with what was built. Walking `next.nodes`
// instead shifts everything after the bypass by one and pushes each node's
// parameters into its neighbour — and the shape is unchanged either way,
// so nothing forces a rebuild that would hide it.
const c = ctx();
const withBypass = (frequency: number): HfAudioFxChain => ({
version: 1,
nodes: [
{
type: "highpass",
enabled: true,
params: { ...defaultAudioFxParams("highpass"), frequency: 100 },
},
{ type: "peaking", enabled: false, params: defaultAudioFxParams("peaking") },
{
type: "lowpass",
enabled: true,
params: { ...defaultAudioFxParams("lowpass"), frequency },
},
],
});
const h = buildFxChain(asCtx(c), withBypass(8000));
const biquads = c.created.filter((n) => n.kind === "biquad");
expect(biquads).toHaveLength(2);
expect(h.update(withBypass(3000))).toBe(true);
// The lowpass took the new cutoff; the highpass was left where it was.
expect(biquads[0]!.frequency.value).toBe(100);
expect(biquads[1]!.frequency.value).toBe(3000);
});
it("reports that a rebuild is needed when the chain shape changes", () => {
const c = ctx();
const h = buildFxChain(asCtx(c), chain("peaking"));
expect(h.update(chain("peaking", "lowpass"))).toBe(false);
expect(h.update(chain("lowpass"))).toBe(false);
});
it("treats a pole-count change as a rebuild, since it changes the node type", () => {
const c = ctx();
const h = buildFxChain(asCtx(c), chain("highpass"));
expect(
h.update({
version: 1,
nodes: [
{
type: "highpass",
enabled: true,
params: { ...defaultAudioFxParams("highpass"), poles: "1" },
},
],
}),
).toBe(false);
});
it("treats bypassing a node as a shape change", () => {
const c = ctx();
const h = buildFxChain(asCtx(c), chain("peaking", "lowpass"));
expect(
h.update({
version: 1,
nodes: [
{ type: "peaking", enabled: true, params: defaultAudioFxParams("peaking") },
{ type: "lowpass", enabled: false, params: defaultAudioFxParams("lowpass") },
],
}),
).toBe(false);
});
it("disconnects everything it made on dispose", () => {
const c = ctx();
const h = buildFxChain(asCtx(c), chain("delay"));
h.dispose();
expect(c.created.every((n) => n.disconnected)).toBe(true);
});
});
describe("chainNeedsWorklets", () => {
it("is true only when the chain contains a worklet-backed effect", () => {
expect(chainNeedsWorklets(chain("peaking", "delay"))).toBe(false);
expect(chainNeedsWorklets(chain("peaking", "compressor"))).toBe(true);
});
});
describe("synthesizeReverbImpulse", () => {
it("is deterministic for the same room, so preview and render convolve the same tail", () => {
const a = synthesizeReverbImpulse(48000, 0.7, 0.5);
const b = synthesizeReverbImpulse(48000, 0.7, 0.5);
expect(Array.from(a.slice(0, 64))).toEqual(Array.from(b.slice(0, 64)));
});
it("varies with the room and decays to near-silence", () => {
const small = synthesizeReverbImpulse(48000, 0.1, 0.5);
const large = synthesizeReverbImpulse(48000, 1.0, 0.5);
expect(large.length).toBeGreaterThan(small.length);
const tail = large.subarray(large.length - 128);
expect(Math.max(...Array.from(tail, Math.abs))).toBeLessThan(0.01);
});
});
describe("levels and per-channel state", () => {
const energy = (ir: Float32Array): number => {
let e = 0;
for (const v of ir) e += v * v;
return Math.sqrt(e);
};
it("normalises the reverb impulse, so adding one does not clip the mix", () => {
// A ConvolverNode applies the impulse's gain whole (normalize is off so the
// room is deterministic). Raw decaying noise ran to +33 dB at the registry
// default, which put the wet path ~24 dB over dry at wet: 0.35.
for (const [size, damping] of [
[0.7, 0.5],
[1, 0],
[0, 1],
[0.5, 0.5],
]) {
expect(energy(synthesizeReverbImpulse(48000, size, damping))).toBeCloseTo(1, 5);
}
});
it("keeps a phaser at unity, rather than summing its two gains above it", () => {
// in_gain/out_gain trim what enters and leaves the effect; wired as a wet/dry
// pair their defaults summed to 1.14, so inserting a phaser raised the level.
const ctx = new FakeCtx();
buildFxNode(ctx as unknown as BaseAudioContext, "phaser", defaultAudioFxParams("phaser"));
const gains = ctx.created.filter((n) => n.kind === "gain").map((n) => n.gain.value);
// The wet and dry legs are summed at unity; the trims carry the knob values.
expect(gains.filter((g) => g === 1).length).toBeGreaterThanOrEqual(2);
});
it("sets the phaser LFO waveform it declares", () => {
// A quarter of the way through the cycle both waveforms peak at 1, so the
// eighth is where they part: a sine is at sin(π/4), a triangle halfway up.
const eighth = (c: FakeCtx): number => {
const buffer = c.created.find((n) => n.kind === "bufferSource")?.buffer;
if (!buffer) throw new Error("no LFO buffer");
return buffer.getChannelData()[Math.round(buffer.length / 8)] ?? 0;
};
const build = (type: string): FakeCtx => {
const c = new FakeCtx();
buildFxNode(c as unknown as BaseAudioContext, "phaser", {
...defaultAudioFxParams("phaser"),
type,
});
return c;
};
expect(eighth(build("0"))).toBeCloseTo(0.5, 3);
expect(eighth(build("1"))).toBeCloseTo(Math.SQRT1_2, 3);
});
/**
* The waveform is baked into a buffer at construction, so pushing a type change
* into the running graph would be a no-op — preview would keep sweeping on a
* triangle while the render used the sine the attribute now says.
*/
it("rebuilds a phaser when its LFO waveform changes", () => {
const phaser = (params: Record<string, number | string>): HfAudioFxChain => ({
version: 1,
nodes: [
{
type: "phaser",
enabled: true,
params: { ...defaultAudioFxParams("phaser"), type: "0", ...params },
},
],
});
const built = buildFxChain(asCtx(ctx()), phaser({}));
expect(built.update(phaser({ type: "1" }))).toBe(false);
// Everything else about a phaser still updates in place.
const other = buildFxChain(asCtx(ctx()), phaser({}));
expect(other.update(phaser({ speed: 2 }))).toBe(true);
});
it("builds the true-peak limiter on its own processor and rebuilds when the lookahead moves", () => {
workletNodes.length = 0;
const limiter = (params: Record<string, number>): HfAudioFxChain => ({
version: 1,
nodes: [
{
type: "truepeak",
enabled: true,
params: { ...defaultAudioFxParams("truepeak"), ...params },
},
],
});
const built = buildFxChain(asCtx(ctx()), limiter({}));
expect(workletNodes.map((w) => w.name)).toEqual(["hf-truepeak"]);
expect(built.update(limiter({ ceiling: -3, release: 200 }))).toBe(true);
// The delay line is sized from the lookahead when the processor is built.
expect(built.update(limiter({ lookahead: 6 }))).toBe(false);
});
it("resets only the effects that carry signal history", () => {
workletNodes.length = 0;
const built = buildFxChain(asCtx(ctx()), chain("truepeak", "compressor"));
built.reset();
expect(workletNodes.map((w) => [w.name, w.messages])).toEqual([
["hf-truepeak", [{ __hfReset: true }]],
["hf-compressor", []],
]);
});
/**
* An LFO's phase is the whole reason it is a looping buffer rather than an
* OscillatorNode, whose phase is zero at `start()` and cannot be set.
*
* Preview rebuilds the graph mid-play — a seek, a scrub, any structural edit —
* and an oscillator restarted there put the chorus at the top of its sweep
* wherever the playhead happened to be, so preview disagreed with the render
* and with itself across an edit.
*/
it("starts a modulated effect's LFO at the phase the clip has reached", () => {
// 3.5 s at 2 Hz is seven whole cycles: back at phase zero.
const whole = ctx();
buildFxNode(asCtx(whole), "chorus", { ...defaultAudioFxParams("chorus"), speed: 2 }, 3.5);
expect(whole.created.find((n) => n.kind === "bufferSource")?.startArgs?.[1]).toBeCloseTo(0, 6);
// 3.6 s at 2 Hz is seven cycles and a fifth.
const part = ctx();
buildFxNode(asCtx(part), "chorus", { ...defaultAudioFxParams("chorus"), speed: 2 }, 3.6);
const src = part.created.find((n) => n.kind === "bufferSource");
expect(src?.startArgs?.[1]).toBeCloseTo(0.2, 6);
expect(src?.loop).toBe(true);
// One second of waveform: the rate reads in Hz, so a speed lane needs no map.
expect(src?.playbackRate.value).toBeCloseTo(2, 6);
});
/**
* A source node is not retired by disconnecting what it feeds. The chorus and
* phaser stopped their LFO and left it out of the nodes they disconnect, so
* every rebuild that dropped one left a modulator still wired to the delay or
* the allpass bank it had been driving.
*/
it("unwires a modulated effect's LFO when the effect is disposed", () => {
for (const type of ["chorus", "phaser"]) {
const c = ctx();
buildFxNode(asCtx(c), type, defaultAudioFxParams(type)).dispose();
const lfo = c.created.find((node) => node.kind === "bufferSource");
expect(lfo?.disconnected, `${type} left its LFO connected`).toBe(true);
}
});
it("starts the LFO at zero for a render, which always begins at the clip's start", () => {
const c = ctx();
buildFxNode(asCtx(c), "phaser", defaultAudioFxParams("phaser"));
expect(c.created.find((n) => n.kind === "bufferSource")?.startArgs?.[1]).toBe(0);
});
it("rebuilds a one-pole filter when its cutoff moves", () => {
// Its coefficients are fixed at construction, so a cutoff change cannot be
// pushed into the running graph — preview kept filtering at the old
// frequency while the render used the new one.
const ctx = new FakeCtx() as unknown as BaseAudioContext;
const chain = (frequency: number): HfAudioFxChain => ({
version: 1,
nodes: [{ type: "highpass", enabled: true, params: { frequency, q: 0.707, poles: "1" } }],
});
const built = buildFxChain(ctx, chain(300));
expect(built.update(chain(2000))).toBe(false);
// A two-pole filter is a BiquadFilterNode and still updates in place.
const twoPole = (frequency: number): HfAudioFxChain => ({
version: 1,
nodes: [{ type: "highpass", enabled: true, params: { frequency, q: 0.707, poles: "2" } }],
});
expect(buildFxChain(ctx, twoPole(300)).update(twoPole(2000))).toBe(true);
});
});
describe("gain stage", () => {
/**
* A level control the chain owns, so a carve can make broadband room for a
* voice without touching the track's own volume lane — which belongs to the
* author, and which a carve re-run would otherwise have to overwrite.
*/
it("sets a GainNode from a value in dB", () => {
const c = ctx();
buildFxNode(c as unknown as BaseAudioContext, "gain", { gain: -6 });
const node = c.created.find((x) => x.kind === "gain");
expect(node).toBeTruthy();
expect(node!.gain.value).toBeCloseTo(0.501, 3);
});
it("passes unity through at 0 dB", () => {
const c = ctx();
buildFxNode(c as unknown as BaseAudioContext, "gain", { gain: 0 });
expect(c.created.find((x) => x.kind === "gain")!.gain.value).toBeCloseTo(1, 6);
});
it("maps an automation lane's dB into the AudioParam's linear units", () => {
// The lane is authored in the knob's own unit — dB, like every other gain in
// the registry — but a GainNode's param is a linear multiplier. Without the
// mapping, a lane point of -12 would schedule a gain of -12: a phase flip
// twelve times too loud, not a cut.
const handle = buildFxNode(ctx() as unknown as BaseAudioContext, "gain", { gain: 0 });
const target = handle.automation?.gain?.[0];
expect(target?.map).toBeTypeOf("function");
expect(target!.map!(-12)).toBeCloseTo(0.251, 3);
expect(target!.map!(0)).toBeCloseTo(1, 6);
});
});
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();
});
});
describe("phaser automation targets", () => {
/**
* `in_gain` and `out_gain` trim the signal entering and leaving the effect,
* which the builder drives through inTrim/outTrim while pinning wet and dry
* to 1. The automation map used to aim both lanes at wet/dry — so an envelope
* modulated a constant, the trim it was supposed to move stayed frozen, and
* "fade the phaser out" left the dry leg playing at full level.
*
* Asserted by VALUE rather than by node identity: the trims are internal, and
* the only honest question is whether the param a lane would drive is the one
* the knob sets.
*/
it("drives the trims a lane is named for, not the pinned wet/dry pair", () => {
const handle = buildFxNode(ctx() as unknown as BaseAudioContext, "phaser", {
...defaultAudioFxParams("phaser"),
in_gain: 0.25,
out_gain: 0.5,
});
expect(handle.automation?.in_gain?.[0]?.param.value).toBeCloseTo(0.25, 6);
expect(handle.automation?.out_gain?.[0]?.param.value).toBeCloseTo(0.5, 6);
});
});
describe("chain update keeps ids with their effects", () => {
const band = (id: string, frequency: number) => ({
type: "peaking",
id,
enabled: true,
params: { ...defaultAudioFxParams("peaking"), frequency },
});
/**
* Reordering two effects of the same type leaves the shape string identical,
* so the chain updates in place rather than rebuilding — correct for the
* audio, since the params move with the position. The ids have to move too:
* a lane addresses its effect by id, and an id captured at build time names
* whichever effect used to occupy that slot. The scheduler would then drive
* `fx.n2.frequency` into the band that is now n1 — the exact swap that
* HfAudioFxNode.id documents itself as preventing, and the one the voiceover
* carve's all-peaking chains make easy to hit.
*/
it("moves an id with its slot when same-type effects are reordered", () => {
const chain: HfAudioFxChain = { version: 1, nodes: [band("n1", 200), band("n2", 4000)] };
const handle = buildFxChain(ctx() as unknown as BaseAudioContext, chain);
const swapped: HfAudioFxChain = { version: 1, nodes: [band("n2", 4000), band("n1", 200)] };
expect(handle.update(swapped)).toBe(true);
expect(handle.nodes.map((n) => n.id)).toEqual(["n2", "n1"]);
});
});
describe("a preset's run is wrapped in a wet/dry blend", () => {
/** Two nodes from one preset, with an ordinary effect after them. */
const chainWith = (amount?: number): HfAudioFxChain => ({
version: 1,
nodes: [
{
type: "highpass",
id: "p1",
fromPreset: "telephone",
enabled: true,
...(amount === undefined ? {} : { presetAmount: amount }),
params: defaultAudioFxParams("highpass"),
},
{
type: "lowpass",
id: "p2",
fromPreset: "telephone",
enabled: true,
params: defaultAudioFxParams("lowpass"),
},
{ type: "reverb", id: "own", enabled: true, params: defaultAudioFxParams("reverb") },
],
});
it("exposes one blend for the whole preset, not one per node", () => {
// The reason this exists: a preset's nodes share no automatable parameter,
// and its worklet effects expose no AudioParams at all, so there is nothing
// to aim a lane at node-by-node.
const built = buildFxChain(asCtx(ctx()), chainWith());
expect(Object.keys(built.presets)).toEqual(["telephone"]);
// Two gains in opposition, the same shape an effect's own mix knob has.
expect(built.presets.telephone).toHaveLength(2);
});
it("blends dry against wet at the stored amount", () => {
const built = buildFxChain(asCtx(ctx()), chainWith(0.25));
const [wet, dry] = built.presets.telephone ?? [];
expect(wet?.param.value).toBeCloseTo(0.25, 6);
expect(dry?.param.value).toBeCloseTo(0.75, 6);
});
it("is fully applied when nothing says otherwise", () => {
// Every chain written before this shipped means "all of it".
const [wet, dry] = buildFxChain(asCtx(ctx()), chainWith()).presets.telephone ?? [];
expect(wet?.param.value).toBe(1);
expect(dry?.param.value).toBe(0);
});
it("pushes a changed amount into the running graph rather than rebuilding", () => {
// Switching a preset off is a value change, and a rebuild would restart the
// audio underneath it.
const built = buildFxChain(asCtx(ctx()), chainWith(1));
expect(built.update(chainWith(0))).toBe(true);
const [wet, dry] = built.presets.telephone ?? [];
expect(wet?.param.value).toBe(0);
expect(dry?.param.value).toBe(1);
});
it("wraps nothing around effects the author placed themselves", () => {
const built = buildFxChain(asCtx(ctx()), chain("peaking", "reverb"));
expect(Object.keys(built.presets)).toEqual([]);
});
it("unwires the blend on dispose", () => {
// The wrap belongs to the chain rather than to any effect, so it is not in
// `handles` — without this a rebuild leaves a crossfade connected to the
// graph it used to bridge.
const c = ctx();
buildFxChain(asCtx(c), chainWith(0.5)).dispose();
const live = c.created.filter((n) => n.kind === "gain" && !n.disconnected);
expect(live).toEqual([]);
});
});
describe("a preset's wrap stays with the nodes it belongs to", () => {
const peak = (over: Partial<HfAudioFxNode>): HfAudioFxNode =>
({
type: "peaking",
enabled: true,
params: defaultAudioFxParams("peaking"),
...over,
}) as HfAudioFxNode;
it("rebuilds when a reorder moves a node across a preset boundary", () => {
// The type sequence is identical either way, so without preset identity in
// the shape the chain updated in place and left the wet/dry wrap bracketing
// the hand-added effect instead of the preset's — preview blending out the
// author's own node while the render, which rebuilds, blended out the
// preset's.
const before: HfAudioFxChain = {
version: 1,
nodes: [peak({ id: "p1", fromPreset: "boom-tame" }), peak({ id: "own" })],
};
const after: HfAudioFxChain = {
version: 1,
nodes: [peak({ id: "own" }), peak({ id: "p1", fromPreset: "boom-tame" })],
};
expect(buildFxChain(asCtx(ctx()), before).update(after)).toBe(false);
});
it("gives every run of one preset its own blend", () => {
// A preset pulled apart by a reorder occupies two runs. Keyed by id and
// assigned, the second wrap overwrote the first, so a whole-preset lane
// reached one fragment and the switch silently left the rest applied.
const split: HfAudioFxChain = {
version: 1,
nodes: [
peak({ id: "t1", fromPreset: "telephone" }),
{ type: "reverb", id: "own", enabled: true, params: defaultAudioFxParams("reverb") },
peak({ id: "t2", fromPreset: "telephone" }),
],
};
const built = buildFxChain(asCtx(ctx()), split);
// Two wraps, so two wet/dry pairs — four params under the one id.
expect(built.presets.telephone).toHaveLength(4);
});
it("pushes an amount into each run of a split preset, not one of them twice", () => {
const at = (amount: number): HfAudioFxChain => ({
version: 1,
nodes: [
peak({ id: "t1", fromPreset: "telephone", presetAmount: amount }),
{ type: "reverb", id: "own", enabled: true, params: defaultAudioFxParams("reverb") },
peak({ id: "t2", fromPreset: "telephone", presetAmount: amount }),
],
});
const built = buildFxChain(asCtx(ctx()), at(1));
expect(built.update(at(0))).toBe(true);
// Every wet leg off and every dry leg fully open: switching the preset off
// has to silence all of it, not the last fragment only.
const wets = (built.presets.telephone ?? []).filter((_, i) => i % 2 === 0);
const drys = (built.presets.telephone ?? []).filter((_, i) => i % 2 === 1);
for (const t of wets) expect(t.param.value).toBe(0);
for (const t of drys) expect(t.param.value).toBe(1);
});
});