Skip to content

Write HTML. Render video. Built for agents.

12.3 KB
Raw Blame
import { describe, expect, it, vi } from "vitest";
import { audioFxWorkletsReady, ensureAudioFxWorklets } from "./audioFxWorklets.js";
import {
  loadProcessors as loadProcessorsAt,
  type Processor,
} from "./audioFxProcessors.test-helpers.js";

/** Just enough of a BaseAudioContext for the registration cache to key on. */
const contextWith = (addModule: (url: string) => Promise<void>): BaseAudioContext =>
  ({ audioWorklet: { addModule } }) as unknown as BaseAudioContext;

describe("ensureAudioFxWorklets", () => {
  it("registers once per context and reuses the result", async () => {
    const addModule = vi.fn(async () => undefined);
    const ctx = contextWith(addModule);

    await ensureAudioFxWorklets(ctx);
    await ensureAudioFxWorklets(ctx);

    expect(addModule).toHaveBeenCalledTimes(1);
    expect(audioFxWorkletsReady(ctx)).toBe(true);
  });

  it("retries after a failure instead of replaying it forever", async () => {
    // The rejected promise used to stay in the cache, so every later attempt
    // got the same rejection back — the limiter, compressor, gate and bitcrush
    // were silent for the life of the context after one transient failure.
    const addModule = vi
      .fn<(url: string) => Promise<void>>()
      .mockRejectedValueOnce(new Error("module load failed"))
      .mockResolvedValue(undefined);
    const ctx = contextWith(addModule);

    await expect(ensureAudioFxWorklets(ctx)).rejects.toThrow("module load failed");
    expect(audioFxWorkletsReady(ctx)).toBe(false);

    await expect(ensureAudioFxWorklets(ctx)).resolves.toBeUndefined();
    expect(addModule).toHaveBeenCalledTimes(2);
    expect(audioFxWorkletsReady(ctx)).toBe(true);
  });

  it("refuses a context with no AudioWorklet rather than hanging", async () => {
    const ctx = {} as BaseAudioContext;
    await expect(ensureAudioFxWorklets(ctx)).rejects.toThrow(/secure context/);
  });
});

/**
 * A processor lives until its `process()` returns false — disconnecting the
 * node does not retire it. These all returned true unconditionally, so every
 * chain rebuild that dropped a worklet effect left it running on the audio
 * thread for the rest of the session.
 *
 * The source is taken from the data: URL registration actually hands to
 * `addModule`, so this also proves the URL carries what it claims to.
 */
describe("the worklet processors themselves", () => {
  const loadProcessors = () => loadProcessorsAt(48000);

  const block = (): Float32Array[][] => [[new Float32Array(128)]];

  it("every processor keeps running until it is told to stop, then retires", async () => {
    const processors = await loadProcessors();
    expect([...processors.keys()]).toEqual([
      "hf-compressor",
      "hf-limiter",
      "hf-gate",
      "hf-bitcrush",
      "hf-pitchshift",
      "hf-truepeak",
    ]);

    for (const [name, Cls] of processors) {
      const p = new Cls({ processorOptions: {} });
      expect(p.process(block(), block()), `${name} retired before it was disposed`).toBe(true);
      p.port.postMessage({ __hfDispose: true });
      expect(p.process(block(), block()), `${name} kept running after dispose`).toBe(false);
      // And it stays retired — a later parameter update must not revive it.
      p.port.postMessage({ mix: 0.5 });
      expect(p.process(block(), block()), `${name} came back to life`).toBe(false);
    }
  });

  describe("HfBitcrush", () => {
    it("does not open with silence when its hold counter starts part-way through a hold", async () => {
      const HfBitcrush = (await loadProcessors()).get("hf-bitcrush");
      if (!HfBitcrush) throw new Error("hf-bitcrush not registered");
      // 251 frames in with a hold of 250: one frame into a hold, with 249 left before the next sample.
      const p = new HfBitcrush({
        processorOptions: { bits: 8, samples: 250, mix: 1, __hfElapsed: 251 / 48000 },
      });
      const input = new Float32Array(128).fill(0.5);
      const output = new Float32Array(128);
      p.process([[input]], [[output]]);
      expect(Math.abs(output[0] ?? 0)).toBeGreaterThan(0.4);
      expect(output.every((x) => Math.abs(x) > 0.4)).toBe(true);
    });
  });

  describe("HfPitchshift", () => {
    const SR = 48000;
    const BLOCK = 128;

    /** Run a mono processor over a whole signal, 128 samples at a time. */
    function run(p: Processor, signal: Float32Array): Float32Array {
      const out = new Float32Array(signal.length);
      for (let at = 0; at < signal.length; at += BLOCK) {
        const inBlock = new Float32Array(BLOCK);
        inBlock.set(signal.subarray(at, at + BLOCK));
        const outBlock = new Float32Array(BLOCK);
        p.process([[inBlock]], [[outBlock]]);
        out.set(outBlock.subarray(0, Math.min(BLOCK, signal.length - at)), at);
      }
      return out;
    }

    function sine(freq: number, seconds: number): Float32Array {
      const n = Math.round(SR * seconds);
      const s = new Float32Array(n);
      for (let i = 0; i < n; i++) s[i] = Math.sin((2 * Math.PI * freq * i) / SR);
      return s;
    }

    /** Rising zero-crossings per second — coarse but enough to catch an octave. */
    function estimateFreq(s: Float32Array, from: number): number {
      const start = Math.round(from * SR);
      let crossings = 0;
      for (let i = start + 1; i < s.length; i++) {
        if ((s[i - 1] ?? 0) < 0 && (s[i] ?? 0) >= 0) crossings++;
      }
      return crossings / ((s.length - start) / SR);
    }

    // This assertion used to be that the output equalled the input DELAYED by
    // grain/2 — the measurement was right and was written down as the contract.
    // But the grain delay is there to shift pitch, and at semitones: 0 nothing
    // is being shifted: the node degenerated into a pure 50 ms delay of the
    // signal, plus a head of silence while the ring filled, under a label that
    // reads "Unchanged pitch".
    it("at semitones: 0, mix: 1 passes the input through untouched", async () => {
      const HfPitchshift = (await loadProcessors()).get("hf-pitchshift");
      if (!HfPitchshift) throw new Error("hf-pitchshift not registered");
      const p = new HfPitchshift({ processorOptions: { semitones: 0, mix: 1 } });
      const input = sine(440, 0.5);
      const output = run(p, input);
      let maxErr = 0;
      for (let i = 0; i < input.length; i++) {
        maxErr = Math.max(maxErr, Math.abs((output[i] ?? 0) - (input[i] ?? 0)));
      }
      expect(maxErr).toBeLessThan(1e-6);
    });

    it("mix: 0 passes the input through untouched too", async () => {
      const HfPitchshift = (await loadProcessors()).get("hf-pitchshift");
      if (!HfPitchshift) throw new Error("hf-pitchshift not registered");
      const p = new HfPitchshift({ processorOptions: { semitones: 7, mix: 0 } });
      const input = sine(440, 0.25);
      const output = run(p, input);
      let maxErr = 0;
      for (let i = 0; i < input.length; i++) {
        maxErr = Math.max(maxErr, Math.abs((output[i] ?? 0) - (input[i] ?? 0)));
      }
      expect(maxErr).toBeLessThan(1e-6);
    });

    /** Largest sample-to-sample step — a splice between the dry and the
     *  ~50 ms-delayed wet path shows up here as a discontinuity. */
    function maxStep(s: Float32Array, from: number, to: number): number {
      let worst = 0;
      for (let i = from + 1; i < to; i++) {
        worst = Math.max(worst, Math.abs((s[i] ?? 0) - (s[i - 1] ?? 0)));
      }
      return worst;
    }

    // Dragging the semitones slider off zero mid-playback swaps the output from
    // x[t] to x[t-50ms]. Switched hard that is an audible click; the wet amount
    // is ramped instead. A 440 Hz sine steps ~0.057 per sample at its steepest,
    // so anything near the signal's own peak is a splice, not the waveform.
    it("does not click when the shift moves off zero mid-signal", async () => {
      const HfPitchshift = (await loadProcessors()).get("hf-pitchshift");
      if (!HfPitchshift) throw new Error("hf-pitchshift not registered");
      const p = new HfPitchshift({ processorOptions: { semitones: 0, mix: 1 } });
      run(p, sine(440, 0.3)); // settled dry, ring warm
      p.p = { ...p.p, semitones: 7 };
      const output = run(p, sine(440, 0.3));
      expect(maxStep(output, 0, output.length)).toBeLessThan(0.2);
    });

    it("does not click on the way back to zero either", async () => {
      const HfPitchshift = (await loadProcessors()).get("hf-pitchshift");
      if (!HfPitchshift) throw new Error("hf-pitchshift not registered");
      const p = new HfPitchshift({ processorOptions: { semitones: 7, mix: 1 } });
      run(p, sine(440, 0.3));
      p.p = { ...p.p, semitones: 0 };
      const output = run(p, sine(440, 0.3));
      expect(maxStep(output, 0, output.length)).toBeLessThan(0.2);
    });

    // ...and having ramped back down it must reach TRUE bypass, not sit on a
    // permanently latched wet path. The render builds a fresh node from the
    // saved attribute and bypasses at semitones 0; a preview that stayed wet
    // would carry a 50 ms delay the export does not have.
    it("returns to true bypass after being shifted and set back to zero", async () => {
      const HfPitchshift = (await loadProcessors()).get("hf-pitchshift");
      if (!HfPitchshift) throw new Error("hf-pitchshift not registered");
      const p = new HfPitchshift({ processorOptions: { semitones: 7, mix: 1 } });
      run(p, sine(440, 0.3));
      p.p = { ...p.p, semitones: 0 };
      run(p, sine(440, 0.3)); // ramp down settles here

      const input = sine(440, 0.3);
      const output = run(p, input);
      let maxErr = 0;
      for (let i = 0; i < input.length; i++) {
        maxErr = Math.max(maxErr, Math.abs((output[i] ?? 0) - (input[i] ?? 0)));
      }
      expect(maxErr).toBeLessThan(1e-6);
    });

    // A node parked at mix 0 has shifted nothing, so it must not have spent
    // anything that stops the zero-shift bypass engaging later.
    it("is transparent at zero after sitting mixed fully out", async () => {
      const HfPitchshift = (await loadProcessors()).get("hf-pitchshift");
      if (!HfPitchshift) throw new Error("hf-pitchshift not registered");
      const p = new HfPitchshift({ processorOptions: { semitones: 7, mix: 0 } });
      run(p, sine(440, 0.3));

      p.p = { ...p.p, semitones: 0, mix: 1 };
      const input = sine(440, 0.3);
      const output = run(p, input);
      let maxErr = 0;
      for (let i = 0; i < input.length; i++) {
        maxErr = Math.max(maxErr, Math.abs((output[i] ?? 0) - (input[i] ?? 0)));
      }
      expect(maxErr).toBeLessThan(1e-6);
    });

    // The ring starts empty, so the taps read zeros for the first grain. That
    // used to come out of the head of every clip as silence; it ramps the wet
    // path in instead, which is unshifted audio rather than no audio.
    it("does not open with silence while the grain buffer fills", async () => {
      const HfPitchshift = (await loadProcessors()).get("hf-pitchshift");
      if (!HfPitchshift) throw new Error("hf-pitchshift not registered");
      const p = new HfPitchshift({ processorOptions: { semitones: 7, mix: 1 } });
      const input = sine(440, 0.5);
      const output = run(p, input);
      // Peak over the first 20 ms — well inside the old dead zone.
      let peak = 0;
      for (let i = 0; i < Math.round(SR * 0.02); i++)
        peak = Math.max(peak, Math.abs(output[i] ?? 0));
      expect(peak).toBeGreaterThan(0.5);
    });

    it("at semitones: 12, doubles the fundamental (one octave up)", async () => {
      const HfPitchshift = (await loadProcessors()).get("hf-pitchshift");
      if (!HfPitchshift) throw new Error("hf-pitchshift not registered");
      const p = new HfPitchshift({ processorOptions: { semitones: 12, mix: 1 } });
      const input = sine(220, 0.5);
      const output = run(p, input);
      // Skip the first couple of grains so the ring buffer is warm.
      const freq = estimateFreq(output, 0.05);
      expect(freq).toBeGreaterThan(220 * 1.7);
      expect(freq).toBeLessThan(220 * 2.3);
    });

    it("at semitones: -12, halves the fundamental (one octave down)", async () => {
      const HfPitchshift = (await loadProcessors()).get("hf-pitchshift");
      if (!HfPitchshift) throw new Error("hf-pitchshift not registered");
      const p = new HfPitchshift({ processorOptions: { semitones: -12, mix: 1 } });
      const input = sine(440, 0.5);
      const output = run(p, input);
      const freq = estimateFreq(output, 0.05);
      expect(freq).toBeGreaterThan(440 * 0.35);
      expect(freq).toBeLessThan(440 * 0.65);
    });
  });
});