Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
feat(core): truepeak, a lookahead true-peak limiter FX (#5419)
Jerrai3746703ea77f
diff --git a/docs/reference/audio-effects.mdx b/docs/reference/audio-effects.mdxindex 428895e63f..910724a745 100644--- a/docs/reference/audio-effects.mdx+++ b/docs/reference/audio-effects.mdx@@ -207,6 +207,7 @@ 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@@ -214,6 +215,26 @@ 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 |diff --git a/packages/core/src/audio/audioFxGraph.test.ts b/packages/core/src/audio/audioFxGraph.test.tsindex dff211cfab..4ef6588e32 100644--- a/packages/core/src/audio/audioFxGraph.test.ts+++ b/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.diff --git a/packages/core/src/audio/audioFxGraph.ts b/packages/core/src/audio/audioFxGraph.tsindex 1887705eeb..3d0a03b08f 100644--- a/packages/core/src/audio/audioFxGraph.ts+++ b/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 thandiff --git a/packages/core/src/audio/audioFxProcessors.test-helpers.ts b/packages/core/src/audio/audioFxProcessors.test-helpers.tsnew file mode 100644index 0000000000..5fdcefeb0c--- /dev/null+++ b/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;+}diff --git a/packages/core/src/audio/audioFxTail.test.ts b/packages/core/src/audio/audioFxTail.test.tsindex 537f7f774a..562c18bd35 100644--- a/packages/core/src/audio/audioFxTail.test.ts+++ b/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),+ );+ });+});diff --git a/packages/core/src/audio/audioFxTail.ts b/packages/core/src/audio/audioFxTail.tsindex 432ec3578b..963664e481 100644--- a/packages/core/src/audio/audioFxTail.ts+++ b/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?: HfAutomatioconst 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);+}diff --git a/packages/core/src/audio/audioFxTruePeak.test.ts b/packages/core/src/audio/audioFxTruePeak.test.tsnew file mode 100644index 0000000000..85dcf0adb7--- /dev/null+++ b/packages/core/src/audio/audioFxTruePeak.test.ts@@ -0,0 +1,356 @@+import { describe, expect, it } from "vitest";+import { loadProcessors, type Processor } from "./audioFxProcessors.test-helpers.js";+import { truePeakLatencySamples } from "./audioFxTruePeak.js";++const SR = 48000;+const BLOCK = 128;++const processors = await loadProcessors(SR);++function makeProcessor(name: string, options: Record<string, number>): Processor {+ const Cls = processors.get(name);+ if (!Cls) throw new Error(`no processor ${name}`);+ return new Cls({ processorOptions: options });+}++/** Run planes through a processor in render quanta, returning planes of the same length. */+function run(p: Processor, planes: Float32Array[]): Float32Array[] {+ const frames = planes[0]?.length ?? 0;+ const out = planes.map(() => new Float32Array(frames));+ for (let at = 0; at < frames; at += BLOCK) {+ const n = Math.min(BLOCK, frames - at);+ const inBlock = planes.map((pl) => {+ const b = new Float32Array(BLOCK);+ b.set(pl.subarray(at, at + n));+ return b;+ });+ const outBlock = planes.map(() => new Float32Array(BLOCK));+ p.process([inBlock], [outBlock]);+ outBlock.forEach((b, c) => out[c]?.set(b.subarray(0, n), at));+ }+ return out;+}++const sampleOf = (plane: Float32Array | undefined, i: number): number => plane?.[i] ?? 0;+const dbToLin = (db: number): number => Math.pow(10, db / 20);+const linToDb = (lin: number): number => 20 * Math.log10(Math.max(lin, 1e-12));++/** In-place radix-2 FFT; the inverse leaves the 1/n scale to the caller. */+function fft(re: Float64Array, im: Float64Array, inverse: boolean): void {+ const n = re.length;+ const bits = Math.log2(n);+ for (let i = 0; i < n; i++) {+ let j = 0;+ for (let b = 0; b < bits; b++) j |= ((i >> b) & 1) << (bits - 1 - b);+ if (j > i) {+ [re[i], re[j]] = [re[j] as number, re[i] as number];+ [im[i], im[j]] = [im[j] as number, im[i] as number];+ }+ }+ for (let len = 2; len <= n; len <<= 1) {+ const half = len >> 1;+ const angle = ((inverse ? 2 : -2) * Math.PI) / len;+ const stepRe = Math.cos(angle);+ const stepIm = Math.sin(angle);+ for (let at = 0; at < n; at += len) {+ let wr = 1;+ let wi = 0;+ for (let k = 0; k < half; k++) {+ const a = at + k;+ const b = a + half;+ const tr = (re[b] as number) * wr - (im[b] as number) * wi;+ const ti = (re[b] as number) * wi + (im[b] as number) * wr;+ re[b] = (re[a] as number) - tr;+ im[b] = (im[a] as number) - ti;+ re[a] = (re[a] as number) + tr;+ im[a] = (im[a] as number) + ti;+ const next = wr * stepRe - wi * stepIm;+ wi = wr * stepIm + wi * stepRe;+ wr = next;+ }+ }+ }+}++/** Samples at each end left out of the peak search: the zero padding rings there. */+const METER_EDGE = 512;+const METER_OVERSAMPLE = 16;++/**+ * True peak in dBFS from an ideal 16x interpolation (zero-padded FFT), not the+ * limiter's 4x detector: a finite FIR meter reads full-band noise about 0.5 dB low.+ */+function truePeakDb(x: Float32Array): number {+ let n = 1;+ while (n < x.length) n <<= 1;+ const re = new Float64Array(n);+ const im = new Float64Array(n);+ re.set(x);+ fft(re, im, false);+ const m = n * METER_OVERSAMPLE;+ const upRe = new Float64Array(m);+ const upIm = new Float64Array(m);+ const half = n >> 1;+ for (let k = 0; k < half; k++) {+ upRe[k] = re[k] as number;+ upIm[k] = im[k] as number;+ if (k > 0) {+ upRe[m - k] = re[n - k] as number;+ upIm[m - k] = im[n - k] as number;+ }+ }+ // The Nyquist bin is real and belongs to both sides of the wider spectrum.+ upRe[half] = (re[half] as number) / 2;+ upRe[m - half] = (re[half] as number) / 2;+ fft(upRe, upIm, true);+ let peak = 0;+ const from = METER_EDGE * METER_OVERSAMPLE;+ const to = (x.length - METER_EDGE) * METER_OVERSAMPLE;+ for (let i = from; i < to; i++) peak = Math.max(peak, Math.abs(upRe[i] as number) / n);+ return linToDb(peak);+}++const sine = (freq: number, amp: number, seconds: number, phase = 0): Float32Array => {+ const out = new Float32Array(Math.round(seconds * SR));+ for (let i = 0; i < out.length; i++)+ out[i] = amp * Math.sin(2 * Math.PI * freq * (i / SR) + phase);+ return out;+};++/** What the ideal-interpolation meter reads on tones, rounded up: they land on the ceiling. */+const TOLERANCE_DB = 0.01;+/** A dense program of tones and low-passed noise bursts reads 0.445 dB over. */+const BROADBAND_TOLERANCE_DB = 0.5;+/** This 2 s hot Gaussian noise reads 1.09 to 1.31 dB over; across 28 longer runs the worst was 1.67. */+const FULL_BAND_NOISE_TOLERANCE_DB = 1.35;++describe("hf-truepeak", () => {+ it("holds an inter-sample peak that the sample peak hides under the ceiling", () => {+ // fs/4 at 45 degrees: every sample is +-0.707 but the waveform between them+ // reaches 1.0, a +3 dB overshoot no sample-peak detector can see.+ const input = sine(SR / 4, 1, 0.5, Math.PI / 4);+ expect(linToDb(Math.max(...input.map(Math.abs)))).toBeCloseTo(-3.01, 1);+ expect(truePeakDb(input)).toBeGreaterThan(-0.2);++ const ceiling = -6;+ const [out] = run(makeProcessor("hf-truepeak", { ceiling, lookahead: 3, release: 80 }), [+ input,+ ]);+ expect(truePeakDb(out as Float32Array)).toBeLessThanOrEqual(ceiling + TOLERANCE_DB);+ });++ it("does not let the envelope limiter's miss through: same signal, same ceiling", () => {+ const input = sine(SR / 4, 1, 0.5, Math.PI / 4);+ const ceiling = -6;+ const [old] = run(makeProcessor("hf-limiter", { limit: ceiling, attack: 5, release: 50 }), [+ input,+ ]);+ const [next] = run(makeProcessor("hf-truepeak", { ceiling, lookahead: 3, release: 80 }), [+ input,+ ]);+ expect(truePeakDb(old as Float32Array)).toBeGreaterThan(ceiling + 1);+ expect(truePeakDb(next as Float32Array)).toBeLessThanOrEqual(ceiling + TOLERANCE_DB);+ });++ it("is in place before an abrupt onset reaches the output", () => {+ const quiet = sine(997, 0.1, 0.2);+ const loud = sine(997, 1.4, 0.2);+ const input = new Float32Array(quiet.length + loud.length);+ input.set(quiet);+ input.set(loud, quiet.length);+ const ceiling = -3;+ const [out] = run(makeProcessor("hf-truepeak", { ceiling, lookahead: 1.5, release: 120 }), [+ input,+ ]);+ expect(truePeakDb(out as Float32Array)).toBeLessThanOrEqual(ceiling + TOLERANCE_DB);+ });++ it("keeps a dense program with random peaks and broadband noise under the ceiling", () => {+ let seed = 12345;+ const rand = (): number => {+ seed = (seed * 1664525 + 1013904223) >>> 0;+ return seed / 0xffffffff - 0.5;+ };+ const input = new Float32Array(SR);+ const tones = [220, 1450, 5200, 11800];+ let smooth = 0;+ for (let i = 0; i < input.length; i++) {+ let v = 0;+ for (const f of tones) v += 0.35 * Math.sin(2 * Math.PI * f * (i / SR) + f);+ // Noise through a one-pole lowpass near 6 kHz, gated into bursts.+ smooth += 0.5 * (rand() - smooth);+ input[i] = v + 3 * smooth * (Math.sin(2 * Math.PI * 3 * (i / SR)) > 0.7 ? 1 : 0.1);+ }+ expect(truePeakDb(input)).toBeGreaterThan(3);+ const ceiling = -14;+ const [out] = run(makeProcessor("hf-truepeak", { ceiling, lookahead: 3, release: 80 }), [+ input,+ ]);+ expect(truePeakDb(out as Float32Array)).toBeLessThanOrEqual(ceiling + BROADBAND_TOLERANCE_DB);+ });++ it("lets full-band noise end up over the ceiling by the measured distance, no further", () => {+ let seed = 99;+ const uniform = (): number => {+ seed = (seed * 1664525 + 1013904223) >>> 0;+ return (seed + 0.5) / 4294967296;+ };+ const input = new Float32Array(SR * 2);+ for (let i = 0; i < input.length; i++) {+ input[i] = 0.5 * Math.sqrt(-2 * Math.log(uniform())) * Math.cos(2 * Math.PI * uniform());+ }+ expect(truePeakDb(input)).toBeGreaterThan(6);+ for (const ceiling of [-1, -6, -14]) {+ const [out] = run(makeProcessor("hf-truepeak", { ceiling, lookahead: 3, release: 80 }), [+ input,+ ]);+ const over = truePeakDb(out as Float32Array) - ceiling;+ expect(over).toBeLessThanOrEqual(FULL_BAND_NOISE_TOLERANCE_DB);+ }+ }, 30_000);++ it("passes a signal under the ceiling unchanged, delayed by exactly its latency", () => {+ const input = sine(440, 0.1, 0.3);+ const lookahead = 3;+ const latency = truePeakLatencySamples(lookahead, SR);+ const [out] = run(makeProcessor("hf-truepeak", { ceiling: -1, lookahead, release: 80 }), [+ input,+ ]);+ for (let i = latency; i < input.length; i++) {+ expect(out?.[i]).toBeCloseTo(input[i - latency] ?? 0, 6);+ }+ });++ it("delays an impulse by truePeakLatencySamples and by nothing else", () => {+ for (const lookahead of [0.5, 1.5, 3, 10]) {+ const input = new Float32Array(2400);+ input[100] = 0.1;+ const [out] = run(makeProcessor("hf-truepeak", { ceiling: -1, lookahead, release: 80 }), [+ input,+ ]);+ const at = (out as Float32Array).findIndex((v) => Math.abs(v) > 1e-6);+ expect(at).toBe(100 + truePeakLatencySamples(lookahead, SR));+ expect(out?.[at]).toBeCloseTo(0.1, 6);+ }+ });++ describe("release", () => {+ /** Output peak over input peak, in 1 ms windows, aligned for the latency. */+ function gainAt(input: Float32Array, out: Float32Array, latency: number, t: number): number {+ const win = Math.round(0.001 * SR);+ const start = Math.round(t * SR);+ let a = 0;+ let b = 0;+ for (let i = start; i < start + win; i++) {+ a = Math.max(a, Math.abs(input[i] ?? 0));+ b = Math.max(b, Math.abs(out[i + latency] ?? 0));+ }+ return b / a;+ }++ function burst(): { input: Float32Array; endsAt: number } {+ const bed = sine(1000, 0.25, 0.3);+ const hit = sine(1000, 1, 0.05);+ const tail = sine(1000, 0.25, 1.2);+ const input = new Float32Array(bed.length + hit.length + tail.length);+ input.set(bed);+ input.set(hit, bed.length);+ input.set(tail, bed.length + hit.length);+ return { input, endsAt: (bed.length + hit.length) / SR };+ }++ it("recovers along the release time constant after the peak has passed", () => {+ const { input, endsAt } = burst();+ const lookahead = 3;+ const latency = truePeakLatencySamples(lookahead, SR);+ const ceiling = -6;+ const [out] = run(makeProcessor("hf-truepeak", { ceiling, lookahead, release: 100 }), [+ input,+ ]);+ const held = gainAt(input, out as Float32Array, latency, endsAt - 0.01);+ expect(held).toBeCloseTo(dbToLin(ceiling), 1);+ // One time constant after the hit: a one-pole has closed 63% of the gap.+ const after = gainAt(input, out as Float32Array, latency, endsAt + 0.1);+ const expected = 1 - (1 - held) * Math.exp(-1);+ expect(after).toBeGreaterThan(expected - 0.03);+ expect(after).toBeLessThan(expected + 0.03);+ expect(gainAt(input, out as Float32Array, latency, endsAt + 1)).toBeGreaterThan(0.995);+ });++ it("recovers more slowly with a longer release", () => {+ const { input, endsAt } = burst();+ const latency = truePeakLatencySamples(3, SR);+ const quick = run(makeProcessor("hf-truepeak", { ceiling: -6, lookahead: 3, release: 50 }), [+ input,+ ])[0] as Float32Array;+ const slow = run(makeProcessor("hf-truepeak", { ceiling: -6, lookahead: 3, release: 400 }), [+ input,+ ])[0] as Float32Array;+ const t = endsAt + 0.15;+ expect(gainAt(input, quick, latency, t)).toBeGreaterThan(+ gainAt(input, slow, latency, t) + 0.15,+ );+ });+ });++ it("applies one gain to every channel so the image does not move", () => {+ const loud = sine(SR / 4, 1, 0.3, Math.PI / 4);+ const quiet = sine(330, 0.05, 0.3);+ const latency = truePeakLatencySamples(3, SR);+ const [l, r] = run(makeProcessor("hf-truepeak", { ceiling: -6, lookahead: 3, release: 80 }), [+ loud,+ quiet,+ ]);+ // The quiet channel is far under the ceiling on its own, yet it ducks with the loud one.+ const gains: [number, number][] = [];+ for (let k = Math.round(0.2 * SR); k < Math.round(0.25 * SR); k++) {+ const inL = sampleOf(loud, k);+ const inR = sampleOf(quiet, k);+ if (Math.abs(inL) >= 0.3 && Math.abs(inR) >= 0.02) {+ gains.push([sampleOf(l, k + latency) / inL, sampleOf(r, k + latency) / inR]);+ }+ }+ expect(gains.length).toBeGreaterThan(100);+ for (const [gainL, gainR] of gains) {+ expect(gainL).toBeLessThan(0.9);+ expect(gainR).toBeCloseTo(gainL, 3);+ }+ });++ it("forgets its delay line and held gain when told the signal jumped", () => {+ const loud = sine(SR / 4, 1, 0.1, Math.PI / 4);+ const quiet = sine(440, 0.05, 0.1);+ const p = makeProcessor("hf-truepeak", { ceiling: -6, lookahead: 3, release: 2000 });+ run(p, [loud]);+ p.port.postMessage({ __hfReset: true });+ const [out] = run(p, [quiet]);+ const latency = truePeakLatencySamples(3, SR);+ expect(Math.max(...(out as Float32Array).subarray(0, latency).map(Math.abs))).toBe(0);+ for (let i = latency; i < quiet.length; i++) {+ expect(out?.[i]).toBeCloseTo(quiet[i - latency] ?? 0, 6);+ }+ const kept = makeProcessor("hf-truepeak", { ceiling: -6, lookahead: 3, release: 2000 });+ run(kept, [loud]);+ const [carried] = run(kept, [quiet]);+ expect(+ Math.max(...(carried as Float32Array).subarray(0, latency).map(Math.abs)),+ ).toBeGreaterThan(0);+ expect(Math.abs((carried?.[latency + 200] ?? 0) / (quiet[200] ?? 1))).toBeLessThan(0.9);+ });++ it("takes ceiling and release live but keeps the lookahead it was built with", () => {+ const p = makeProcessor("hf-truepeak", { ceiling: 0, lookahead: 3, release: 80 });+ const input = sine(SR / 4, 1, 0.3, Math.PI / 4);+ p.port.postMessage({ ceiling: -6, lookahead: 10 });+ const [out] = run(p, [input]);+ expect(truePeakDb(out as Float32Array)).toBeLessThanOrEqual(-6 + TOLERANCE_DB);+ const impulse = new Float32Array(2400);+ impulse[50] = 0.05;+ const q = makeProcessor("hf-truepeak", { ceiling: -1, lookahead: 3, release: 80 });+ q.port.postMessage({ lookahead: 10 });+ const [o2] = run(q, [impulse]);+ expect((o2 as Float32Array).findIndex((v) => Math.abs(v) > 1e-6)).toBe(+ 50 + truePeakLatencySamples(3, SR),+ );+ });+});diff --git a/packages/core/src/audio/audioFxTruePeak.ts b/packages/core/src/audio/audioFxTruePeak.tsnew file mode 100644index 0000000000..690816dc61--- /dev/null+++ b/packages/core/src/audio/audioFxTruePeak.ts@@ -0,0 +1,169 @@+/**+ * The `hf-truepeak` worklet: a lookahead limiter that holds a 4x estimate of the+ * true peak at a ceiling in dBTP; full-band noise can end up to 1.7 dB over.+ */++const TRUE_PEAK_OVERSAMPLE = 4;+/** Group delay of the interpolator, in input samples. */+const TRUE_PEAK_DETECTOR_DELAY = 16;++const KERNEL_HALF = TRUE_PEAK_OVERSAMPLE * TRUE_PEAK_DETECTOR_DELAY;+/** Taps per polyphase branch: the longest branch of a 2 * KERNEL_HALF + 1 kernel. */+const BRANCH_TAPS = 2 * TRUE_PEAK_DETECTOR_DELAY + 1;++function truePeakLookaheadSamples(lookaheadMs: number, sampleRate: number): number {+ return Math.max(1, Math.round((lookaheadMs * sampleRate) / 1000));+}++/** Samples between a sample entering the limiter and leaving it. */+export function truePeakLatencySamples(lookaheadMs: number, sampleRate: number): number {+ return truePeakLookaheadSamples(lookaheadMs, sampleRate) + TRUE_PEAK_DETECTOR_DELAY;+}++export const TRUE_PEAK_WORKLET_SOURCE = `+const TP_OS = ${TRUE_PEAK_OVERSAMPLE};+const TP_HALF = ${KERNEL_HALF};+const TP_BRANCH = ${BRANCH_TAPS};+const TP_DELAY = ${TRUE_PEAK_DETECTOR_DELAY};++function besselI0(x) {+ let sum = 1, term = 1;+ for (let k = 1; k < 40; k++) {+ term *= (x / (2 * k)) * (x / (2 * k));+ sum += term;+ }+ return sum;+}++/** Kaiser-windowed sinc, one array per polyphase branch, newest tap first. */+function tpBranches() {+ const beta = 6;+ const norm = besselI0(beta);+ const branches = [];+ for (let p = 0; p < TP_OS; p++) {+ const taps = new Float64Array(TP_BRANCH);+ let sum = 0;+ for (let j = 0; j < TP_BRANCH; j++) {+ const k = p + TP_OS * j;+ if (k > 2 * TP_HALF) continue;+ const t = (k - TP_HALF) / TP_OS;+ const sinc = t === 0 ? 1 : Math.sin(Math.PI * t) / (Math.PI * t);+ const r = (k - TP_HALF) / TP_HALF;+ taps[j] = sinc * (besselI0(beta * Math.sqrt(Math.max(0, 1 - r * r))) / norm);+ sum += taps[j];+ }+ // Unity gain at DC on every branch, so a steady level reads as itself.+ for (let j = 0; j < TP_BRANCH; j++) taps[j] /= sum;+ branches.push(taps);+ }+ return branches;+}++class HfTruePeak extends AudioWorkletProcessor {+ constructor(o) {+ super();+ this.p = o.processorOptions || {};+ this.look = Math.max(1, Math.round((this.p.lookahead ?? 3) * sampleRate / 1000));+ this.delayLen = this.look + TP_DELAY;+ this.branches = tpBranches();+ this.setLevels();+ this.clear();+ this.port.onmessage = (e) => {+ if (e.data && e.data.__hfDispose) { this.dead = true; return; }+ if (e.data && e.data.__hfReset) { this.clear(); return; }+ this.p = { ...this.p, ...e.data };+ this.setLevels();+ };+ }+ /** Back to the state of a fresh processor: no audio in the delay line, no gain reduction. */+ clear() {+ this.ch = [];+ this.rel = 1;+ this.dqIdx = new Int32Array(this.look + 2);+ this.dqVal = new Float64Array(this.look + 2);+ this.dqHead = 0;+ this.dqTail = 0;+ this.t = 0;+ this.avgRing = new Float64Array(this.look + 1).fill(1);+ this.avgPos = 0;+ this.avgSum = this.look + 1;+ }+ setLevels() {+ this.ceiling = Math.pow(10, (this.p.ceiling ?? -1) / 20);+ this.relCoef = 1 - Math.exp(-1 / (sampleRate * Math.max(1e-4, (this.p.release ?? 80) / 1000)));+ }+ channel(c) {+ if (!this.ch[c]) {+ this.ch[c] = {+ delay: new Float32Array(this.delayLen),+ w: 0,+ hist: new Float32Array(TP_BRANCH * 2),+ pos: 0,+ };+ }+ return this.ch[c];+ }+ /** Largest interpolated magnitude across channels for the newest sample. */+ peak(chans, inputs, n) {+ let peak = 0;+ for (let c = 0; c < chans; c++) {+ const s = this.channel(c);+ const x = inputs[c][n];+ s.pos = (s.pos + 1) % TP_BRANCH;+ s.hist[s.pos] = x;+ s.hist[s.pos + TP_BRANCH] = x;+ const base = s.pos + TP_BRANCH;+ for (let p = 0; p < TP_OS; p++) {+ const taps = this.branches[p];+ let acc = 0;+ for (let j = 0; j < TP_BRANCH; j++) acc += taps[j] * s.hist[base - j];+ const a = acc < 0 ? -acc : acc;+ if (a > peak) peak = a;+ }+ }+ return peak;+ }+ /** Windowed minimum of the required gain over the last look + 1 values. */+ windowMin(v) {+ const cap = this.dqIdx.length;+ while (this.dqTail !== this.dqHead && this.dqVal[(this.dqTail + cap - 1) % cap] >= v) {+ this.dqTail = (this.dqTail + cap - 1) % cap;+ }+ this.dqIdx[this.dqTail] = this.t;+ this.dqVal[this.dqTail] = v;+ this.dqTail = (this.dqTail + 1) % cap;+ while (this.dqIdx[this.dqHead] <= this.t - (this.look + 1)) {+ this.dqHead = (this.dqHead + 1) % cap;+ }+ this.t++;+ return this.dqVal[this.dqHead];+ }+ process(inputs, outputs) {+ if (this.dead) return false;+ const i = inputs[0], o = outputs[0];+ if (!i || !i.length) return true;+ const chans = i.length;+ const frames = i[0].length;+ for (let n = 0; n < frames; n++) {+ const peak = this.peak(chans, i, n);+ const need = peak > this.ceiling ? this.ceiling / peak : 1;+ const m = this.windowMin(need);+ this.avgSum += m - this.avgRing[this.avgPos];+ this.avgRing[this.avgPos] = m;+ this.avgPos = (this.avgPos + 1) % this.avgRing.length;+ const target = Math.min(1, this.avgSum / this.avgRing.length);+ const released = this.rel + (1 - this.rel) * this.relCoef;+ this.rel = released < target ? released : target;+ if (target >= 1 && this.rel > 0.9999999) this.rel = 1;+ for (let c = 0; c < chans; c++) {+ const s = this.channel(c);+ o[c][n] = s.delay[s.w] * this.rel;+ s.delay[s.w] = i[c][n];+ s.w = (s.w + 1) % this.delayLen;+ }+ }+ return true;+ }+}+registerProcessor("hf-truepeak", HfTruePeak);+`;diff --git a/packages/core/src/audio/audioFxWorklets.test.ts b/packages/core/src/audio/audioFxWorklets.test.tsindex 2f342f6669..c6353f9cae 100644--- a/packages/core/src/audio/audioFxWorklets.test.ts+++ b/packages/core/src/audio/audioFxWorklets.test.ts@@ -1,5 +1,9 @@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 =>@@ -51,33 +55,7 @@ describe("ensureAudioFxWorklets", () => {* `addModule`, so this also proves the URL carries what it claims to.*/describe("the worklet processors themselves", () => {- /** Evaluate the registered module and hand back the processor classes by name. */- async function loadProcessors(): Promise<Map<string, new (o: unknown) => Processor>> {- let moduleSource = "";- await ensureAudioFxWorklets(- contextWith(async (url: string) => {- moduleSource = atob(url.replace("data:text/javascript;base64,", ""));- }),- );- const made = new Map<string, new (o: unknown) => Processor>();- 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: new (o: unknown) => Processor) => made.set(name, cls),- 48000,- );- return made;- }-- interface Processor {- port: { postMessage(data: unknown): void };- process(inputs: Float32Array[][], outputs: Float32Array[][]): boolean;- }+ const loadProcessors = () => loadProcessorsAt(48000);const block = (): Float32Array[][] => [[new Float32Array(128)]];@@ -89,6 +67,7 @@ describe("the worklet processors themselves", () => {"hf-gate","hf-bitcrush","hf-pitchshift",+ "hf-truepeak",]);for (const [name, Cls] of processors) {diff --git a/packages/core/src/audio/audioFxWorklets.ts b/packages/core/src/audio/audioFxWorklets.tsindex 5aa3d9fc16..1e4e3c7b07 100644--- a/packages/core/src/audio/audioFxWorklets.ts+++ b/packages/core/src/audio/audioFxWorklets.ts@@ -1,3 +1,5 @@+import { TRUE_PEAK_WORKLET_SOURCE } from "./audioFxTruePeak.js";+/*** AudioWorklet processors for the effects Web Audio has no native node for.*@@ -9,7 +11,8 @@* Kept as a source string so it can be registered from a Blob URL without a* separate bundled asset, which keeps the studio's build unchanged.*/-const AUDIO_FX_WORKLET_SOURCE = `+const AUDIO_FX_WORKLET_SOURCE =+ `const dbToLin = (db) => Math.pow(10, db / 20);/**@@ -345,7 +348,7 @@ class HfPitchshift extends AudioWorkletProcessor {}}registerProcessor("hf-pitchshift", HfPitchshift);-`;+` + TRUE_PEAK_WORKLET_SOURCE;// Registration is per context, not per module: a processor registered on one// AudioContext does not exist on another, so caching a single promise madediff --git a/packages/core/src/audioFx.ts b/packages/core/src/audioFx.tsindex 181ddb67c6..60a57e52a6 100644--- a/packages/core/src/audioFx.ts+++ b/packages/core/src/audioFx.ts@@ -334,6 +334,49 @@ export const HF_AUDIO_FX: readonly HfAudioFxDef[] = [],web: "worklet-limiter",},+ {+ id: "truepeak",+ label: "True-peak limiter",+ group: "dynamics",+ description:+ "Lookahead limiter that holds a 4x estimate of the inter-sample peak at a dBTP ceiling; full-band noise can land up to about 1.7 dB above it. Adds lookahead plus about 0.3 ms of latency.",+ params: [+ {+ kind: "number",+ key: "ceiling",+ label: "Ceiling",+ unit: "dBTP",+ min: -24,+ max: 0,+ step: 0.1,+ default: -1,+ hint: "Target true peak, measured on a 4x oversampled signal. Dense full-band sound can end up to about 1.7 dB above it.",+ },+ {+ kind: "number",+ key: "lookahead",+ label: "Lookahead",+ unit: "ms",+ min: 0.5,+ max: 10,+ step: 0.1,+ default: 3,+ hint: "How far ahead the gain starts falling. Longer is smoother and adds the same latency.",+ },+ {+ kind: "number",+ key: "release",+ label: "Release",+ unit: "ms",+ min: 10,+ max: 2000,+ step: 1,+ default: 80,+ scale: "log",+ },+ ],+ web: "worklet-truepeak",+ },{id: "gate",label: "Noise Gate",diff --git a/packages/core/src/audioFxCopy.test.ts b/packages/core/src/audioFxCopy.test.tsindex dc48a3752c..ad974b505b 100644--- a/packages/core/src/audioFxCopy.test.ts+++ b/packages/core/src/audioFxCopy.test.ts@@ -174,3 +174,26 @@ describe("no copy assumes the track is a voice", () => {expect(voiced.some(([, text]) => SPEECH.test(text))).toBe(true);});});++/** Everything Studio shows for the true-peak limiter, and the ceiling knob's hint. */+function truePeakCopy(): { shown: string; hint: string } {+ const copy = EFFECT_COPY.truepeak;+ const ceiling = copy?.params.ceiling;+ const summary = SUMMARY.truepeak;+ if (!copy || !ceiling?.hint || !summary) throw new Error("truepeak copy is missing");+ const shown = [copy.does, copy.reachFor, ceiling.label, ceiling.hint, summary({})];+ return { shown: shown.join("\n"), hint: ceiling.hint };+}++describe("the true-peak copy does not promise a hard ceiling", () => {+ it("never says never or must-not-clip", () => {+ expect(truePeakCopy().shown).not.toMatch(/never exceed|must not clip|never above|guarantee/i);+ });++ it("tells the author about the 4x estimate and the headroom to leave", () => {+ const { hint } = truePeakCopy();+ expect(hint).toMatch(/4x/);+ expect(hint).toMatch(/1\.7 dB/);+ expect(hint).toMatch(/headroom/);+ });+});diff --git a/packages/core/src/audioFxCopy.ts b/packages/core/src/audioFxCopy.tsindex cc3a775943..3490a840fa 100644--- a/packages/core/src/audioFxCopy.ts+++ b/packages/core/src/audioFxCopy.ts@@ -166,6 +166,22 @@ export const EFFECT_COPY: Record<string, EffectCopy> = {level_out: { label: "Level after" },},},+ truepeak: {+ title: "True-Peak Ceiling",+ does: "Pulls the loudest moments, including the ones between samples, down toward a target ceiling.",+ reachFor: "Peaks need to stay under a delivery limit.",+ primary: "ceiling",+ primaryEnds: { low: "A lot of headroom", high: "Little headroom" },+ params: {+ ceiling: {+ label: "Target ceiling",+ hint: "Measured with a 4x estimate. Dense full-band sound can end up to about 1.7 dB above it, so leave headroom: -3 for a -1 dBTP limit.",+ ends: { low: "A lot of headroom", high: "Little headroom" },+ },+ lookahead: { label: "How far ahead it looks" },+ release: { label: "How fast it recovers" },+ },+ },gate: {title: "Silence the Gaps",does: "Mutes the pauses. Whatever sits underneath stays — this closes the gaps, it does not remove noise.",@@ -396,6 +412,7 @@ export const SUMMARY: Record<string, (p: P) => string> = {compressor: (p) =>`Evening out — ${strength(Math.min(1, (n(p.ratio, 3) - 1) / 7), ["gentle", "moderate", "firm"])}`,limiter: (p) => `Nothing louder than ${n(p.limit, -1)} dB`,+ truepeak: (p) => `Peaks pulled down toward ${n(p.ceiling, -1)} dBTP`,gate: (p) => `Closing gaps quieter than ${n(p.threshold, -45)} dB`,saturate: (p) =>`${strength(Math.min(1, Math.abs(n(p.threshold, -6)) / 30), ["A little", "Some", "Heavy"])} warmth`,diff --git a/packages/core/src/runtime/audioFx.test.ts b/packages/core/src/runtime/audioFx.test.tsindex ef8babcb60..6820a4bdc3 100644--- a/packages/core/src/runtime/audioFx.test.ts+++ b/packages/core/src/runtime/audioFx.test.ts@@ -647,6 +647,37 @@ describe("attachElementFxChain", () => {}});+ it("clears a limiter's state when a persistent chain is re-anchored for a new pass", async () => {+ const messages: unknown[] = [];+ class RecordingWorkletStub extends WorkletNodeStub {+ override port = { postMessage: (...sent: unknown[]) => void messages.push(...sent) };+ }+ const original = (globalThis as { AudioWorkletNode?: unknown }).AudioWorkletNode;+ (globalThis as { AudioWorkletNode?: unknown }).AudioWorkletNode = RecordingWorkletStub;+ try {+ const node = document.createElement("audio");+ node.setAttribute(+ "data-fx-chain",+ JSON.stringify({ version: 1, nodes: [{ type: "truepeak", id: "n1", params: {} }] }),+ );+ document.body.append(node);+ const timing = { scheduledAt: 0, elapsed: 0, rate: 1 };+ const fx = attachElementFxChain(+ new WorkletCtx() as unknown as BaseAudioContext,+ node,+ new Node() as never,+ new Node() as never,+ timing,+ );+ await settle();+ expect(messages).not.toContainEqual({ __hfReset: true });+ fx?.reanchor(timing);+ expect(messages).toContainEqual({ __hfReset: true });+ } finally {+ (globalThis as { AudioWorkletNode?: unknown }).AudioWorkletNode = original;+ }+ });+it("keeps the carve alive when a compressor is added to a playing track", async () => {// The reported case, and the worse of the two paths: adding a worklet effect// to an already-attached chain rebuilt it, the build threw because nothingdiff --git a/packages/core/src/runtime/audioFx.ts b/packages/core/src/runtime/audioFx.tsindex bd459af013..085f10a152 100644--- a/packages/core/src/runtime/audioFx.ts+++ b/packages/core/src/runtime/audioFx.ts@@ -292,6 +292,7 @@ export function attachElementFxChain(const at = timingNow();if (at) cancelParamLane(automated, at.scheduledAt);frame = { ...next };+ handle?.reset();scheduleFor(readChain(el).chain, frame);},setRate: (rate: number) => {diff --git a/packages/core/stubs/audio-fx-runtime-entry.ts b/packages/core/stubs/audio-fx-runtime-entry.tsindex b8ed1e8e16..786122a325 100644--- a/packages/core/stubs/audio-fx-runtime-entry.ts+++ b/packages/core/stubs/audio-fx-runtime-entry.ts@@ -19,7 +19,7 @@ import {import { scheduleChainAutomation } from "../src/audio/audioFxAutomation.js";import { parseAutomation, resolveAutomation } from "../src/audioAutomation.js";import { parseAudioFxChain, type HfAudioFxChain } from "../src/audioFx.js";-import { chainTailSeconds } from "../src/audio/audioFxTail.js";+import { chainLatencySamples, chainTailSeconds } from "../src/audio/audioFxTail.js";declare global {interface Window {@@ -63,11 +63,11 @@ function toBuffer(return buffer;}-/** Every rendered channel, copied out of the result buffer. */-function toPlanes(rendered: AudioBuffer): Float32Array[] {+/** Every rendered channel past `skip` leading samples, copied out of the result buffer. */+function toPlanes(rendered: AudioBuffer, skip: number): Float32Array[] {const out: Float32Array[] = [];for (let c = 0; c < rendered.numberOfChannels; c++) {- out.push(new Float32Array(rendered.getChannelData(c)));+ out.push(new Float32Array(rendered.getChannelData(c).subarray(skip)));}return out;}@@ -90,7 +90,10 @@ async function render(? resolveAutomation(parseAutomation(automationJson), chain): null;const tail = Math.ceil(chainTailSeconds(chain, parsedAutomation ?? undefined) * sampleRate);- const ctx = new OfflineAudioContext(channels, frames + tail, sampleRate);+ // A lookahead limiter delays its output; render that much longer and drop the+ // lead-in so the clip stays sample-aligned with its source.+ const latency = chainLatencySamples(chain, sampleRate);+ const ctx = new OfflineAudioContext(channels, frames + tail + latency, sampleRate);if (chainNeedsWorklets(chain)) await ensureAudioFxWorklets(ctx);@@ -116,7 +119,7 @@ async function render(fx.output.connect(ctx.destination);source.start();- return toPlanes(await ctx.startRendering());+ return toPlanes(await ctx.startRendering(), latency);}window.__HF_AUDIO_FX = { render };diff --git a/packages/core/tsconfig.json b/packages/core/tsconfig.jsonindex 487985d2ff..26db66a080 100644--- a/packages/core/tsconfig.json+++ b/packages/core/tsconfig.json@@ -30,6 +30,7 @@"src/tests","src/runtime","**/*.test.ts",+ "**/*.test-helpers.ts","src/parsers/test-utils.ts"]}diff --git a/packages/engine/src/services/audioFxRender.test.ts b/packages/engine/src/services/audioFxRender.test.tsindex 213846e831..be5b6ca67c 100644--- a/packages/engine/src/services/audioFxRender.test.ts+++ b/packages/engine/src/services/audioFxRender.test.ts@@ -289,6 +289,43 @@ describe.skipIf(!HAS_BROWSER)("browser render", () => {expect(freq).toBeLessThan(220 * 2.3);}, 180_000);+ it("holds a true peak under the ceiling and trims its own lookahead", async () => {+ // fs/4 at 45 degrees: samples of +-0.707 whose waveform reaches 1.0. Preceded+ // by a quiet impulse so the output position proves the latency was trimmed.+ const input = join(dir, "isp-in.wav");+ const n = Math.floor(SR * 0.4);+ const samples = new Float32Array(n);+ samples[100] = 0.1;+ for (let i = 4800; i < n; i++) samples[i] = Math.sin((Math.PI / 2) * i + Math.PI / 4);+ writeWav(input, samples, SR, 1, true);+ const outPath = join(dir, "isp-out.wav");+ const ceiling = -6;+ await applyAudioFxChain(+ input,+ {+ version: 1,+ nodes: [+ {+ type: "truepeak",+ id: "n1",+ enabled: true,+ params: { ceiling, lookahead: 3, release: 80 },+ },+ ],+ },+ outPath,+ { trackId: "t" },+ );+ const out = readWav(outPath).samples;+ expect(out.length).toBe(n);+ expect(out[100]).toBeCloseTo(0.1, 3);+ // Sample peak of the steady part is 0.707 * gain; the gain that holds the+ // 1.0 true peak at -6 dBTP leaves it at -9 dBFS.+ let peak = 0;+ for (let i = 9600; i < n; i++) peak = Math.max(peak, Math.abs(out[i] ?? 0));+ expect(db(peak)).toBeCloseTo(-9.03, 0);+ }, 180_000);+it("sweeps a filter across the clip when a lane automates it", async () => {// A 2 kHz tone under a lowpass whose cutoff rises from below it to well// above: the start should be attenuated and the end should not. This isdiff --git a/skills-manifest.json b/skills-manifest.jsonindex 8bc3b14675..e3fcf72bd0 100644--- a/skills-manifest.json+++ b/skills-manifest.json@@ -26,7 +26,7 @@"files": 122},"hyperframes-audio": {- "hash": "e815fcede8a676b9",+ "hash": "5dce20c2722a7af2","files": 8},"hyperframes-cli": {diff --git a/skills/hyperframes-audio/SKILL.md b/skills/hyperframes-audio/SKILL.mdindex 8a15517ab2..a560e7baa6 100644--- a/skills/hyperframes-audio/SKILL.md+++ b/skills/hyperframes-audio/SKILL.md@@ -52,7 +52,7 @@ the first two, on an `<hf-audio-group>` bus (see "One bus for many tracks"):| `data-fx-carve` | the carve's own settings, so it can be re-derived |The shipped effect families are gain, EQ (highpass, lowpass, peaking, shelves),-compressor, limiter, gate, saturate, delay, reverb, chorus, phaser, and bitcrush.+compressor, limiter, truepeak (lookahead true-peak limiter), gate, saturate, delay, reverb, chorus, phaser, and bitcrush.Exact JSON for each, and the rules a lane must satisfy: `references/attributes.md`.Every effect with its parameters, ranges and units: `references/fx-registry.md`.@@ -195,10 +195,14 @@ want 1–3 kHz, and taking that from the bed costs the bed far less than turningthe whole thing down costs the mix. A high-pass on a voice is the standard fixfor rumble; a low-pass darkens or muffles deliberately.-**Dynamics** (`gain`, `compressor`, `limiter`, `gate`) decide how a track's level+**Dynamics** (`gain`, `compressor`, `limiter`, `truepeak`, `gate`) decide how a track's levelbehaves over time. Compression narrows the distance between loud and quiet so thequiet parts can come up. A limiter is a ceiling — it does not shape anything, it-guarantees nothing gets past. A gate removes what is below a threshold, which is+guarantees nothing gets past. `limiter` follows the level, so for a delivery+ceiling use `truepeak`, which looks ahead and measures the inter-sample peak. It+holds a 4x estimate at the ceiling, not the waveform itself, so full-band noise can+end up to 1.7 dB over: under a hard delivery limit set the ceiling at least 2 dB+below it. A gate removes what is below a threshold, which ishow you silence room tone between phrases. `gain` is a plain level stage, and itis what an automation lane rides when a track has to move out of the way.@@ -440,8 +444,8 @@ and the parameter's own units. Targets are `volume` for the track's level, or`fx.<nodeId>.<param>` for an effect's knob.**Only some parameters can be automated, and a lane on the others is silently-inert.** A knob is automatable when a Web Audio `AudioParam` backs it. The four-worklet-based effects — `compressor`, `limiter`, `gate`, `bitcrush` — expose+inert.** A knob is automatable when a Web Audio `AudioParam` backs it. The+worklet-based effects — `compressor`, `limiter`, `truepeak`, `gate`, `bitcrush` — exposenone at all, so no lane on any of their parameters will ever move: to make acompressor's behaviour change over time, automate a `gain` stage before itinstead. `references/fx-registry.md` marks every parameter.diff --git a/skills/hyperframes-audio/references/attributes.md b/skills/hyperframes-audio/references/attributes.mdindex 224275a9d1..8be1d40f21 100644--- a/skills/hyperframes-audio/references/attributes.md+++ b/skills/hyperframes-audio/references/attributes.md@@ -107,8 +107,8 @@ escaping.**A lane on a non-automatable parameter is silently inert.** Automation isdelivered as native `AudioParam` scheduling, so a knob that no `AudioParam` backscannot move: worklet processor options, a WaveShaper curve and a convolution-impulse are all set wholesale. `fx-registry.md` marks each parameter; the four-worklet effects (`compressor`, `limiter`, `gate`, `bitcrush`) have none at all.+impulse are all set wholesale. `fx-registry.md` marks each parameter; the+worklet effects (`compressor`, `limiter`, `truepeak`, `gate`, `bitcrush`) have none at all.## `data-fx-carve` — the carve's settingsdiff --git a/skills/hyperframes-audio/references/fx-registry.md b/skills/hyperframes-audio/references/fx-registry.mdindex 5bfb37f1b6..4c159caf9f 100644--- a/skills/hyperframes-audio/references/fx-registry.md+++ b/skills/hyperframes-audio/references/fx-registry.md@@ -29,6 +29,7 @@ Web Audio spec leaves it unused for them, so a control would have moved nothing.| `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` go to −60 dB, boosts stop at +12: it is a level stage for making@@ -37,6 +38,19 @@ room, and a chain that could add 40 dB would clip long before that was useful.signal back in (parallel compression). `range` is how far down the gate pullswhen closed — a gate that pulls all the way to silence sounds like a switch.+`limiter` follows the signal's level and has no lookahead, so it does not+guarantee a peak ceiling. For a delivery ceiling use `truepeak`: it estimates the+inter-sample (true) peak at 4x, looks `lookahead` ms ahead, and holds that estimate+at `ceiling` dBTP. It delays its output by `lookahead` plus about 0.3 ms; the+render trims the delay, live preview plays it.++The ceiling is a 4x estimate, so the real true peak can end above it. 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). A 4x meter such as ffmpeg `ebur128=peak=true` reads that+noise about 0.1 dB over and will not show it. 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 | Parameter |@@ -70,7 +84,7 @@ curves, which is what keeps it sample-accurate and identical between preview andrender. A parameter can therefore only be automated if an `AudioParam` backs it.Three kinds do not:-- **worklet processor options** — `compressor`, `limiter`, `gate` and `bitcrush`+- **worklet processor options** — `compressor`, `limiter`, `truepeak`, `gate` and `bitcrush`are AudioWorklets configured wholesale, so **none of their parameters areautomatable at all**.- **a WaveShaper curve** — `saturate`'s `type`, `threshold` and `oversample`