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

Author: jerrai-bot-heygen

docs/reference/audio-effects.mdx

@@ -207,13 +207,34 @@ Web Audio spec leaves it unused for them.
 | `gain` | `gain` −60–12 dB (0) **AUTO** |
 | `compressor` | `threshold` −60–0 dB (−24) · `ratio` 1–20 (4) · `attack` 0.01–2000 ms (20, log) · `release` 0.01–9000 ms (250, log) · `knee` 1–8 (2.83) · `makeup` 0–36 dB (0) · `mix` 0–1 (1) |
 | `limiter` | `limit` −24–0 dB (−1) · `attack` 0.1–80 ms (5) · `release` 1–8000 ms (50, log) · `level_out` −24–24 dB (0) |
+| `truepeak` | `ceiling` −24–0 dBTP (−1) · `lookahead` 0.5–10 ms (3) · `release` 10–2000 ms (80, log) |
 | `gate` | `threshold` −80–0 dB (−35) · `range` −80–0 dB (−24) · `ratio` 1–20 (10) · `attack` 0.01–9000 ms (1, log) · `release` 0.01–9000 ms (100, log) · `knee` 1–8 (2.83) |
 
 Cuts on `gain` reach −60 dB, boosts stop at +12: it is a level stage for making
 room, and a chain that could add 40 dB would clip long before that was useful.
 `knee` of 1 is a hard corner. `mix` below 1 blends the dry signal back in
 (parallel compression). `range` is how far down the gate pulls when closed.
 
+`limiter` is an envelope follower: it reacts to the level of the signal, has no
+lookahead, and can let a sample peak or an inter-sample peak through. `truepeak`
+is the one to use for a delivery ceiling. It estimates the true peak on a 4x
+oversampled signal, reads `lookahead` ms ahead so the gain is already down when
+the peak arrives, and holds that estimate at `ceiling`. Channels share one
+gain. It delays its output by `lookahead` plus about 0.3 ms (3.3 to 10.3 ms across
+the range): the offline render trims that delay, live preview plays it, so the
+sound is that much behind the picture. A seek clears the limiter's delay line and
+held gain on a group bus. Changing `lookahead` rebuilds the node.
+
+The ceiling is held against that 4x estimate, not against the waveform itself. A
+4x interpolator cannot see the peaks of content close to Nyquist, so the true peak
+can end above `ceiling`. Measured against an ideal 16x interpolation, tones, pink
+noise and a dense mix ended at most 0.6 dB over. Full-band white noise driven 8 dB
+or more into the limiter ended 1.2 to 1.7 dB over (median 1.4 dB, 28 runs of 10
+to 30 s). A meter that also reads at 4x, such as ffmpeg's `ebur128=peak=true`,
+reports that same noise about 0.1 dB over, so it will not show the miss. Under a
+hard delivery limit set `ceiling` at least 2 dB below it: −3 dBTP for a −1 dBTP
+limit.
+
 ### Nonlinear — changes the waveform's shape
 
 | Effect | Parameters |
@@ -253,7 +274,7 @@ Three kinds do not:
 
 | Kind | Effects | Consequence |
 | --- | --- | --- |
-| Worklet processor options | `compressor`, `limiter`, `gate`, `bitcrush`, `pitchshift` | **No parameter is automatable at all** |
+| Worklet processor options | `compressor`, `limiter`, `truepeak`, `gate`, `bitcrush`, `pitchshift` | **No parameter is automatable at all** |
 | A WaveShaper curve | `saturate`'s `type`, `threshold`, `oversample` | Only its `output` stage is a real param |
 | A convolution impulse | `reverb`'s `size`, `damping` | `wet` / `dry` are gain stages and automate fine |
 

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

@@ -412,6 +412,35 @@ describe("levels and per-channel state", () => {
     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.

packages/core/src/audio/audioFxGraph.ts

@@ -81,6 +81,8 @@ export interface FxNodeHandle {
    * parameter key. Absent for a node whose values cannot be scheduled.
    */
   automation?: Record<string, FxParamTarget[]>;
+  /** Drop internal state (delay lines, held gain) when the signal jumps, as on a seek. */
+  reset?(): void;
   dispose(): void;
 }
 
@@ -250,13 +252,14 @@ function onePoleBuilder(kind: "highpass" | "lowpass"): Builder {
   };
 }
 
-function workletBuilder(processor: string): Builder {
+function workletBuilder(processor: string, resettable = false): Builder {
   return (ctx, p) => {
     const node = new AudioWorkletNode(ctx, processor, { processorOptions: { ...p } });
     return {
       input: node,
       output: node,
       update: (v) => node.port.postMessage({ ...v }),
+      ...(resettable ? { reset: () => node.port.postMessage({ __hfReset: true }) } : {}),
       dispose: () => {
         // Disconnecting is not enough to retire an AudioWorkletProcessor: it
         // lives until its `process()` returns false, and these all returned
@@ -503,6 +506,7 @@ const BUILDERS: Record<string, Builder> = {
   "biquad-lowpass": biquad("lowpass", false),
   "worklet-compressor": workletBuilder("hf-compressor"),
   "worklet-limiter": workletBuilder("hf-limiter"),
+  "worklet-truepeak": workletBuilder("hf-truepeak", true),
   "worklet-gate": workletBuilder("hf-gate"),
   "worklet-bitcrush": workletBuilder("hf-bitcrush"),
   "worklet-pitchshift": workletBuilder("hf-pitchshift"),
@@ -549,6 +553,8 @@ export interface FxChainHandle {
   presets: Record<string, FxParamTarget[]>;
   /** Re-parameterise in place when the shape is unchanged; false if a rebuild is needed. */
   update(chain: HfAudioFxChain): boolean;
+  /** Clear the state of every effect that carries signal history. */
+  reset(): void;
   dispose(): void;
 }
 
@@ -609,7 +615,8 @@ function shapeOf(chain: HfAudioFxChain): string {
       // author's own node while the render, which rebuilds, blended out the
       // preset's.
       const run = node.fromPreset ? `%${node.fromPreset}` : "";
-      return `${node.type}${poles}${fixedFreq}${wave}${run}`;
+      const lookahead = node.type === "truepeak" ? `^${p.lookahead}` : "";
+      return `${node.type}${poles}${fixedFreq}${wave}${lookahead}${run}`;
     })
     .join("|");
 }
@@ -731,6 +738,9 @@ export function buildFxChain(
       // join per observer tick to write back the string that was already there.
       return true;
     },
+    reset() {
+      for (const { handle } of handles) handle.reset?.();
+    },
     dispose() {
       for (const { handle } of handles) handle.dispose();
       // The wrap is not one of `handles` — it belongs to the chain rather than

packages/core/src/audio/audioFxProcessors.test-helpers.ts

@@ -0,0 +1,32 @@
+import { ensureAudioFxWorklets } from "./audioFxWorklets.js";
+
+export interface Processor {
+  port: { postMessage(data: unknown): void };
+  process(inputs: Float32Array[][], outputs: Float32Array[][]): boolean;
+}
+export type ProcessorClass = new (o: unknown) => Processor;
+
+/** The registered processors, evaluated from the module `addModule` is handed. */
+export async function loadProcessors(sampleRate: number): Promise<Map<string, ProcessorClass>> {
+  let moduleSource = "";
+  await ensureAudioFxWorklets({
+    audioWorklet: {
+      addModule: async (url: string) => {
+        moduleSource = atob(url.replace("data:text/javascript;base64,", ""));
+      },
+    },
+  } as unknown as BaseAudioContext);
+  const made = new Map<string, ProcessorClass>();
+  class Base {
+    port = {
+      onmessage: null as ((e: { data: unknown }) => void) | null,
+      postMessage: (data: unknown) => this.port.onmessage?.({ data }),
+    };
+  }
+  new Function("AudioWorkletProcessor", "registerProcessor", "sampleRate", moduleSource)(
+    Base,
+    (name: string, cls: ProcessorClass) => made.set(name, cls),
+    sampleRate,
+  );
+  return made;
+}

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

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
-import { chainTailSeconds, MAX_FX_TAIL_SECONDS } from "./audioFxTail.js";
+import { chainLatencySamples, chainTailSeconds, MAX_FX_TAIL_SECONDS } from "./audioFxTail.js";
+import { truePeakLatencySamples } from "./audioFxTruePeak.js";
 import { synthesizeReverbImpulse } from "./audioFxGraph.js";
 import type { HfAudioFxChain } from "../audioFx.js";
 import type { HfAutomation } from "../audioAutomation.js";
@@ -101,3 +102,31 @@ describe("chainTailSeconds", () => {
     expect(chainTailSeconds(withLane, automation)).toBeCloseTo(0.6 + 0.5 * 2.6, 5);
   });
 });
+
+describe("chainLatencySamples", () => {
+  it("is zero for a chain with no lookahead", () => {
+    expect(
+      chainLatencySamples(
+        chain([{ type: "limiter", id: "l", params: { limit: -1, attack: 5, release: 50 } }]),
+        48000,
+      ),
+    ).toBe(0);
+  });
+
+  it("sums each enabled true-peak limiter's lookahead plus detector delay", () => {
+    const nodes: HfAudioFxChain["nodes"] = [
+      { type: "truepeak", id: "a", params: { ceiling: -1, lookahead: 3, release: 80 } },
+      { type: "truepeak", id: "b", params: { ceiling: -1, lookahead: 1.5, release: 80 } },
+      { type: "truepeak", id: "c", enabled: false, params: { ceiling: -1, lookahead: 9 } },
+    ];
+    expect(chainLatencySamples(chain(nodes), 48000)).toBe(
+      truePeakLatencySamples(3, 48000) + truePeakLatencySamples(1.5, 48000),
+    );
+  });
+
+  it("reads the registry default when the attribute omits the lookahead", () => {
+    expect(chainLatencySamples(chain([{ type: "truepeak", id: "a", params: {} }]), 48000)).toBe(
+      truePeakLatencySamples(3, 48000),
+    );
+  });
+});

packages/core/src/audio/audioFxTail.ts

@@ -9,7 +9,13 @@
  */
 
 import { fxAutomationTarget, type HfAutomation } from "../audioAutomation.js";
-import { normalizeAudioFxParams, type HfAudioFxChain, type HfAudioFxNode } from "../audioFx.js";
+import {
+  enabledAudioFxNodes,
+  normalizeAudioFxParams,
+  type HfAudioFxChain,
+  type HfAudioFxNode,
+} from "../audioFx.js";
+import { truePeakLatencySamples } from "./audioFxTruePeak.js";
 
 /**
  * Ceiling on the extension, in seconds.
@@ -113,3 +119,13 @@ export function chainTailSeconds(chain: HfAudioFxChain, automation?: HfAutomatio
   const total = chain.nodes.reduce((sum, node) => sum + nodeTail(node, automation), 0);
   return Math.min(MAX_FX_TAIL_SECONDS, total);
 }
+
+/** Samples the offline render trims so a lookahead limiter does not shift a clip. */
+export function chainLatencySamples(chain: HfAudioFxChain, sampleRate: number): number {
+  return enabledAudioFxNodes(chain)
+    .filter((node) => node.type === "truepeak")
+    .reduce((sum, node) => {
+      const { lookahead } = normalizeAudioFxParams(node.type, node.params);
+      return sum + truePeakLatencySamples(Number(lookahead), sampleRate);
+    }, 0);
+}