@hyperframes/core 0.8.145 → 0.8.146

package/dist/adapters/gsap.d.ts

@@ -11,4 +11,3 @@ export interface CreateGSAPFrameAdapterOptions {
     timeline: GSAPTimelineLike;
 }
 export declare function createGSAPFrameAdapter(options: CreateGSAPFrameAdapterOptions): FrameAdapter;
-//# sourceMappingURL=gsap.d.ts.map

package/dist/adapters/gsap.js

@@ -22,4 +22,3 @@ export function createGSAPFrameAdapter(options) {
         },
     };
 }
-//# sourceMappingURL=gsap.js.map

package/dist/adapters/index.d.ts

@@ -1,4 +1,3 @@
 export type { FrameAdapter, FrameAdapterContext } from "./types";
 export type { GSAPTimelineLike, CreateGSAPFrameAdapterOptions } from "./gsap";
 export { createGSAPFrameAdapter } from "./gsap";
-//# sourceMappingURL=index.d.ts.map

package/dist/adapters/index.js

@@ -1,2 +1 @@
 export { createGSAPFrameAdapter } from "./gsap.js";
-//# sourceMappingURL=index.js.map

package/dist/adapters/types.d.ts

@@ -12,4 +12,3 @@ export interface FrameAdapter {
     seekFrame: (frame: number) => Promise<void> | void;
     destroy?: () => Promise<void> | void;
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/adapters/types.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=types.js.map

package/dist/atomicFile.d.ts

@@ -11,4 +11,3 @@ export declare function createFileAtomically(filePath: string, content: string |
 /** The file a write to `filePath` lands on: folder links and file links followed as the system does. */
 export declare function resolveWritePath(filePath: string): string;
 export {};
-//# sourceMappingURL=atomicFile.d.ts.map

package/dist/atomicFile.js

@@ -150,4 +150,3 @@ function renameWithRetry(operations, from, to) {
 function errorCode(error) {
     return String(error?.code);
 }
-//# sourceMappingURL=atomicFile.js.map

package/dist/audibleVideo.d.ts

@@ -11,4 +11,3 @@ export declare function audibleVideoNeedsWebAudio(fields: {
     automation?: string | null;
     audioGroup?: string | null;
 }): boolean;
-//# sourceMappingURL=audibleVideo.d.ts.map

package/dist/audibleVideo.js

@@ -9,4 +9,3 @@ export function isAudibleVideoElement(el) {
 export function audibleVideoNeedsWebAudio(fields) {
     return ((fields.volume ?? 1) > 1 || Boolean(fields.fxChain || fields.automation || fields.audioGroup));
 }
-//# sourceMappingURL=audibleVideo.js.map

package/dist/audio/audioFxAutomation.d.ts

@@ -60,4 +60,3 @@ export declare function scheduleChainAutomation(automation: HfAutomation, chain:
 presets?: Record<string, FxParamTarget[]>): FxParamTarget[];
 /** The track's volume lane, if it has one. */
 export declare function volumeLane(automation: HfAutomation): HfAutomationLane | null;
-//# sourceMappingURL=audioFxAutomation.d.ts.map

package/dist/audio/audioFxAutomation.js

@@ -216,4 +216,3 @@ presets) {
 export function volumeLane(automation) {
     return automation.lanes.find((lane) => lane.target === VOLUME_TARGET) ?? null;
 }
-//# sourceMappingURL=audioFxAutomation.js.map

package/dist/audio/audioFxGraph.d.ts

@@ -36,6 +36,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;
 }
 /** Effect ids whose Web Audio node needs a worklet module registered first. */
@@ -58,6 +60,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;
 }
 /**
@@ -70,4 +74,3 @@ export interface FxChainHandle {
  */
 export declare function buildFxChain(ctx: BaseAudioContext, chain: HfAudioFxChain, elapsed?: number): FxChainHandle;
 export { audioFxWorkletsReady, ensureAudioFxWorklets };
-//# sourceMappingURL=audioFxGraph.d.ts.map

package/dist/audio/audioFxGraph.js

@@ -183,13 +183,14 @@ function onePoleBuilder(kind) {
         return simple(node, () => { });
     };
 }
-function workletBuilder(processor) {
+function workletBuilder(processor, resettable = false) {
     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
@@ -429,6 +430,7 @@ const BUILDERS = {
     "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"),
@@ -511,7 +513,8 @@ function shapeOf(chain) {
         // 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("|");
 }
@@ -629,6 +632,10 @@ export function buildFxChain(ctx, chain, elapsed = 0) {
             // 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();
@@ -647,4 +654,3 @@ export function buildFxChain(ctx, chain, elapsed = 0) {
     };
 }
 export { audioFxWorkletsReady, ensureAudioFxWorklets };
-//# sourceMappingURL=audioFxGraph.js.map

package/dist/audio/audioFxTail.d.ts

@@ -25,4 +25,5 @@ export declare const MAX_FX_TAIL_SECONDS = 5;
  * each of its repeats to the room and the last one still gets a full tail.
  */
 export declare function chainTailSeconds(chain: HfAudioFxChain, automation?: HfAutomation): number;
-//# sourceMappingURL=audioFxTail.d.ts.map
+/** Samples the offline render trims so a lookahead limiter does not shift a clip. */
+export declare function chainLatencySamples(chain: HfAudioFxChain, sampleRate: number): number;

package/dist/audio/audioFxTail.js

@@ -8,7 +8,8 @@
  * the room it needs.
  */
 import { fxAutomationTarget } from "../audioAutomation.js";
-import { normalizeAudioFxParams } from "../audioFx.js";
+import { enabledAudioFxNodes, normalizeAudioFxParams, } from "../audioFx.js";
+import { truePeakLatencySamples } from "./audioFxTruePeak.js";
 /**
  * Ceiling on the extension, in seconds.
  *
@@ -107,4 +108,12 @@ export function chainTailSeconds(chain, automation) {
     const total = chain.nodes.reduce((sum, node) => sum + nodeTail(node, automation), 0);
     return Math.min(MAX_FX_TAIL_SECONDS, total);
 }
-//# sourceMappingURL=audioFxTail.js.map
+/** Samples the offline render trims so a lookahead limiter does not shift a clip. */
+export function chainLatencySamples(chain, sampleRate) {
+    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);
+}

package/dist/audio/audioFxTruePeak.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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.
+ */
+/** Samples between a sample entering the limiter and leaving it. */
+export declare function truePeakLatencySamples(lookaheadMs: number, sampleRate: number): number;
+export declare const TRUE_PEAK_WORKLET_SOURCE = "\nconst TP_OS = 4;\nconst TP_HALF = 64;\nconst TP_BRANCH = 33;\nconst TP_DELAY = 16;\n\nfunction besselI0(x) {\n  let sum = 1, term = 1;\n  for (let k = 1; k < 40; k++) {\n    term *= (x / (2 * k)) * (x / (2 * k));\n    sum += term;\n  }\n  return sum;\n}\n\n/** Kaiser-windowed sinc, one array per polyphase branch, newest tap first. */\nfunction tpBranches() {\n  const beta = 6;\n  const norm = besselI0(beta);\n  const branches = [];\n  for (let p = 0; p < TP_OS; p++) {\n    const taps = new Float64Array(TP_BRANCH);\n    let sum = 0;\n    for (let j = 0; j < TP_BRANCH; j++) {\n      const k = p + TP_OS * j;\n      if (k > 2 * TP_HALF) continue;\n      const t = (k - TP_HALF) / TP_OS;\n      const sinc = t === 0 ? 1 : Math.sin(Math.PI * t) / (Math.PI * t);\n      const r = (k - TP_HALF) / TP_HALF;\n      taps[j] = sinc * (besselI0(beta * Math.sqrt(Math.max(0, 1 - r * r))) / norm);\n      sum += taps[j];\n    }\n    // Unity gain at DC on every branch, so a steady level reads as itself.\n    for (let j = 0; j < TP_BRANCH; j++) taps[j] /= sum;\n    branches.push(taps);\n  }\n  return branches;\n}\n\nclass HfTruePeak extends AudioWorkletProcessor {\n  constructor(o) {\n    super();\n    this.p = o.processorOptions || {};\n    this.look = Math.max(1, Math.round((this.p.lookahead ?? 3) * sampleRate / 1000));\n    this.delayLen = this.look + TP_DELAY;\n    this.branches = tpBranches();\n    this.setLevels();\n    this.clear();\n    this.port.onmessage = (e) => {\n      if (e.data && e.data.__hfDispose) { this.dead = true; return; }\n      if (e.data && e.data.__hfReset) { this.clear(); return; }\n      this.p = { ...this.p, ...e.data };\n      this.setLevels();\n    };\n  }\n  /** Back to the state of a fresh processor: no audio in the delay line, no gain reduction. */\n  clear() {\n    this.ch = [];\n    this.rel = 1;\n    this.dqIdx = new Int32Array(this.look + 2);\n    this.dqVal = new Float64Array(this.look + 2);\n    this.dqHead = 0;\n    this.dqTail = 0;\n    this.t = 0;\n    this.avgRing = new Float64Array(this.look + 1).fill(1);\n    this.avgPos = 0;\n    this.avgSum = this.look + 1;\n  }\n  setLevels() {\n    this.ceiling = Math.pow(10, (this.p.ceiling ?? -1) / 20);\n    this.relCoef = 1 - Math.exp(-1 / (sampleRate * Math.max(1e-4, (this.p.release ?? 80) / 1000)));\n  }\n  channel(c) {\n    if (!this.ch[c]) {\n      this.ch[c] = {\n        delay: new Float32Array(this.delayLen),\n        w: 0,\n        hist: new Float32Array(TP_BRANCH * 2),\n        pos: 0,\n      };\n    }\n    return this.ch[c];\n  }\n  /** Largest interpolated magnitude across channels for the newest sample. */\n  peak(chans, inputs, n) {\n    let peak = 0;\n    for (let c = 0; c < chans; c++) {\n      const s = this.channel(c);\n      const x = inputs[c][n];\n      s.pos = (s.pos + 1) % TP_BRANCH;\n      s.hist[s.pos] = x;\n      s.hist[s.pos + TP_BRANCH] = x;\n      const base = s.pos + TP_BRANCH;\n      for (let p = 0; p < TP_OS; p++) {\n        const taps = this.branches[p];\n        let acc = 0;\n        for (let j = 0; j < TP_BRANCH; j++) acc += taps[j] * s.hist[base - j];\n        const a = acc < 0 ? -acc : acc;\n        if (a > peak) peak = a;\n      }\n    }\n    return peak;\n  }\n  /** Windowed minimum of the required gain over the last look + 1 values. */\n  windowMin(v) {\n    const cap = this.dqIdx.length;\n    while (this.dqTail !== this.dqHead && this.dqVal[(this.dqTail + cap - 1) % cap] >= v) {\n      this.dqTail = (this.dqTail + cap - 1) % cap;\n    }\n    this.dqIdx[this.dqTail] = this.t;\n    this.dqVal[this.dqTail] = v;\n    this.dqTail = (this.dqTail + 1) % cap;\n    while (this.dqIdx[this.dqHead] <= this.t - (this.look + 1)) {\n      this.dqHead = (this.dqHead + 1) % cap;\n    }\n    this.t++;\n    return this.dqVal[this.dqHead];\n  }\n  process(inputs, outputs) {\n    if (this.dead) return false;\n    const i = inputs[0], o = outputs[0];\n    if (!i || !i.length) return true;\n    const chans = i.length;\n    const frames = i[0].length;\n    for (let n = 0; n < frames; n++) {\n      const peak = this.peak(chans, i, n);\n      const need = peak > this.ceiling ? this.ceiling / peak : 1;\n      const m = this.windowMin(need);\n      this.avgSum += m - this.avgRing[this.avgPos];\n      this.avgRing[this.avgPos] = m;\n      this.avgPos = (this.avgPos + 1) % this.avgRing.length;\n      const target = Math.min(1, this.avgSum / this.avgRing.length);\n      const released = this.rel + (1 - this.rel) * this.relCoef;\n      this.rel = released < target ? released : target;\n      if (target >= 1 && this.rel > 0.9999999) this.rel = 1;\n      for (let c = 0; c < chans; c++) {\n        const s = this.channel(c);\n        o[c][n] = s.delay[s.w] * this.rel;\n        s.delay[s.w] = i[c][n];\n        s.w = (s.w + 1) % this.delayLen;\n      }\n    }\n    return true;\n  }\n}\nregisterProcessor(\"hf-truepeak\", HfTruePeak);\n";

package/dist/audio/audioFxTruePeak.js

@@ -0,0 +1,164 @@
+/**
+ * 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, sampleRate) {
+    return Math.max(1, Math.round((lookaheadMs * sampleRate) / 1000));
+}
+/** Samples between a sample entering the limiter and leaving it. */
+export function truePeakLatencySamples(lookaheadMs, sampleRate) {
+    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);
+`;

package/dist/audio/audioFxWorklets.d.ts

@@ -5,4 +5,3 @@ export declare function audioFxWorkletsReady(ctx: BaseAudioContext): boolean;
  * addModule throws if the same processor name is registered twice.
  */
 export declare function ensureAudioFxWorklets(ctx: BaseAudioContext): Promise<void>;
-//# sourceMappingURL=audioFxWorklets.d.ts.map

package/dist/audio/audioFxWorklets.js

@@ -1,3 +1,4 @@
+import { TRUE_PEAK_WORKLET_SOURCE } from "./audioFxTruePeak.js";
 /**
  * AudioWorklet processors for the effects Web Audio has no native node for.
  *
@@ -18,7 +19,7 @@ const dbToLin = (db) => Math.pow(10, db / 20);
  * Per channel matters: the followers advance once per sample, so a single shared
  * follower stepped once per channel per sample. On stereo that ran a 20 ms attack
  * as 10 ms, and gave the right channel a gain computed from an envelope that had
- * already traversed the left — so the two channels ducked by different amounts
+ * already traversed the left, so the two channels ducked by different amounts
  * from the same input and the image pumped.
  */
 class EnvBank {
@@ -230,7 +231,7 @@ function readTap(ring, write, delaySamples) {
   return ring[i0] * (1 - frac) + ring[i1] * frac;
 }
 
-/** Equal-power-ish crossfade, zero at a tap's reset point — hides the splice. */
+/** Equal-power-ish crossfade, zero at a tap's reset point, which hides the splice. */
 function xfade(phase) {
   return Math.sin(Math.PI * phase);
 }
@@ -242,7 +243,7 @@ function xfade(phase) {
  * out, which hides the splice each tap makes when it wraps.
  *
  * write/phase are block-level state, advanced once per SAMPLE across all
- * channels together (not once per channel) — advancing them inside the
+ * channels together (not once per channel). Advancing them inside the
  * per-channel loop would move the tap 2x/4x too fast on a stereo/quad input.
  */
 class HfPitchshift extends AudioWorkletProcessor {
@@ -255,13 +256,13 @@ class HfPitchshift extends AudioWorkletProcessor {
     this.phase = 0;
     // Samples written so far, capped at one grain. The taps read up to a grain
     // behind the write head, so until this fills they would read the ring's
-    // zeros — the head of every clip came out attenuated or silent.
+    // zeros, so the head of every clip came out attenuated or silent.
     this.filled = 0;
     // How much of the wet (pitch-shifted) path is currently in the output, and
     // where it is heading. Crossing between dry and wet is a ~50 ms jump in the
     // signal, so it is RAMPED rather than switched: a hard swap either way is a
     // click. Ramping in both directions is also what lets a node return to true
-    // bypass at semitones 0 — a one-way latch left preview stuck with the delay
+    // bypass at semitones 0. A one-way latch left preview stuck with the delay
     // that the render, building a fresh node from the attribute, does not have.
     this.wet = 0;
     this.wetTarget = 0;
@@ -289,7 +290,7 @@ class HfPitchshift extends AudioWorkletProcessor {
 
     // Nothing to shift, or mixed fully out. The grain delay is ~grain/2
     // whatever the ratio, so at semitones=0 this degenerated into a pure 50 ms
-    // delay of the signal — while the copy for that exact setting reads
+    // delay of the signal, while the copy for that exact setting reads
     // "Unchanged pitch".
     this.wetTarget = semitones === 0 ? 0 : mix;
 
@@ -345,7 +346,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 made
 // every context after the first believe it was ready when it was not.
@@ -364,7 +365,7 @@ export function ensureAudioFxWorklets(ctx) {
     if (!modulePromise) {
         modulePromise = (async () => {
             if (!ctx.audioWorklet) {
-                throw new Error("AudioWorklet is unavailable — the page needs a secure context (https, localhost or file://)");
+                throw new Error("AudioWorklet is unavailable: the page needs a secure context (https, localhost or file://)");
             }
             // A data: URL rather than a blob:, because a blob inherits the page origin
             // and is treated as opaque on a file:// page, where the module then fails
@@ -386,4 +387,3 @@ export function ensureAudioFxWorklets(ctx) {
     }
     return modulePromise;
 }
-//# sourceMappingURL=audioFxWorklets.js.map

package/dist/audioAutomation.d.ts

@@ -200,4 +200,3 @@ export declare function isConstantLane(lane: HfAutomationLane): boolean;
  * volume envelope, and the lane's own drawing code.
  */
 export declare function sampleAutomationCurve(lane: HfAutomationLane, from: number, to: number, count: number, scale?: "linear" | "log"): Float32Array;
-//# sourceMappingURL=audioAutomation.d.ts.map

package/dist/audioAutomation.js

@@ -512,4 +512,3 @@ export function sampleAutomationCurve(lane, from, to, count, scale = "linear") {
     }
     return out;
 }
-//# sourceMappingURL=audioAutomation.js.map

package/dist/audioCarve.d.ts

@@ -240,4 +240,3 @@ export declare function analyseCarveDuck(voice: Float32Array, bed: Float32Array,
 }[];
 /** Carve bands as an ordinary FX chain of peaking filters. */
 export declare function carveBandsToChain(bands: HfCarveBand[]): HfAudioFxChain;
-//# sourceMappingURL=audioCarve.d.ts.map

package/dist/audioCarve.js

@@ -638,4 +638,3 @@ export function carveBandsToChain(bands) {
     }));
     return { version: HF_AUDIO_FX_CHAIN_VERSION, nodes };
 }
-//# sourceMappingURL=audioCarve.js.map

package/dist/audioFade.d.ts

@@ -21,4 +21,3 @@ export declare function clampFadesToDuration(fades: AudioFades, duration: number
 export declare function fadeGain(elapsed: number, duration: number, fades: AudioFades): number;
 /** Attribute text Studio writes: up to 2 decimals, no trailing zeros. */
 export declare function formatFadeSeconds(seconds: number): string;
-//# sourceMappingURL=audioFade.d.ts.map

package/dist/audioFade.js

@@ -53,4 +53,3 @@ function clamp01(value) {
         return 0;
     return value > 1 ? 1 : value;
 }
-//# sourceMappingURL=audioFade.js.map

package/dist/audioFx.d.ts

@@ -179,4 +179,3 @@ export declare function serializeAudioFxChain(chain: HfAudioFxChain): string;
  * compositions require.
  */
 export declare function mintAudioFxNodeId(chain: HfAudioFxChain): string;
-//# sourceMappingURL=audioFx.d.ts.map

package/dist/audioFx.js

@@ -37,7 +37,7 @@ const freq = (key = "frequency", label = "Frequency", def = 1000, min = 20, max
     scale: "log",
     automatable: true,
 });
-const qParam = (def = 0.707, hint = "Bandwidth — higher is narrower.") => ({
+const qParam = (def = 0.707, hint = "Bandwidth: higher is narrower.") => ({
     kind: "number",
     key: "q",
     label: "Q",
@@ -118,7 +118,7 @@ export const HF_AUDIO_FX = [
         id: "highpass",
         label: "High-pass",
         group: "filter",
-        description: "Remove low frequencies — the usual fix for rumble on a voice.",
+        description: "Remove low frequencies: the usual fix for rumble on a voice.",
         params: [freq("frequency", "Cutoff", 300, 20, 20000), qParam(0.707), poles],
         web: "biquad-highpass",
     },
@@ -126,7 +126,7 @@ export const HF_AUDIO_FX = [
         id: "lowpass",
         label: "Low-pass",
         group: "filter",
-        description: "Remove high frequencies — darkens or muffles a track.",
+        description: "Remove high frequencies, which darkens or muffles a track.",
         params: [freq("frequency", "Cutoff", 8000, 100, 20000), qParam(0.707), poles],
         web: "biquad-lowpass",
     },
@@ -218,7 +218,7 @@ export const HF_AUDIO_FX = [
         id: "limiter",
         label: "Limiter",
         group: "dynamics",
-        description: "Hard ceiling — nothing gets past the limit.",
+        description: "Hard ceiling: nothing gets past the limit.",
         params: [
             {
                 kind: "number",
@@ -264,6 +264,48 @@ export const HF_AUDIO_FX = [
         ],
         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",
@@ -419,7 +461,7 @@ export const HF_AUDIO_FX = [
                 max: 250,
                 step: 1,
                 default: 1,
-                hint: "Repeats each sample N times — a crude downsample.",
+                hint: "Repeats each sample N times, a crude downsample.",
             },
             {
                 kind: "number",
@@ -878,4 +920,3 @@ function withoutUndefined(obj) {
     }
     return obj;
 }
-//# sourceMappingURL=audioFx.js.map

package/dist/audioFxCopy.d.ts

@@ -86,4 +86,3 @@ export declare const PRESET_PROBLEM: Record<string, string>;
 type P = Record<string, unknown>;
 export declare const SUMMARY: Record<string, (p: P) => string>;
 export {};
-//# sourceMappingURL=audioFxCopy.d.ts.map