feat(core): the levelling script — "Even Out Levels"

packages/core/package-subpaths.json

@@ -104,6 +104,12 @@
       "types": "./dist/audioFxEq.d.ts",
       "environments": ["browser", "bun", "node"]
     },
+    "./audio-leveller": {
+      "source": "./src/audioLeveller.ts",
+      "runtime": "./dist/audioLeveller.js",
+      "types": "./dist/audioLeveller.d.ts",
+      "environments": ["browser", "bun", "node"]
+    },
     "./audio-fx-presets": {
       "source": "./src/audioFxPresets.ts",
       "runtime": "./dist/audioFxPresets.js",

packages/core/package.json

@@ -118,6 +118,12 @@
       "import": "./src/audioFxEq.ts",
       "types": "./src/audioFxEq.ts"
     },
+    "./audio-leveller": {
+      "bun": "./src/audioLeveller.ts",
+      "node": "./dist/audioLeveller.js",
+      "import": "./src/audioLeveller.ts",
+      "types": "./src/audioLeveller.ts"
+    },
     "./audio-fx-presets": {
       "bun": "./src/audioFxPresets.ts",
       "node": "./dist/audioFxPresets.js",
@@ -418,6 +424,10 @@
         "import": "./dist/audioFxEq.js",
         "types": "./dist/audioFxEq.d.ts"
       },
+      "./audio-leveller": {
+        "import": "./dist/audioLeveller.js",
+        "types": "./dist/audioLeveller.d.ts"
+      },
       "./audio-fx-presets": {
         "import": "./dist/audioFxPresets.js",
         "types": "./dist/audioFxPresets.d.ts"

packages/core/src/audioFx.ts

@@ -832,6 +832,11 @@ export interface HfAudioFxNode {
    * effect type and its bands stay ordinary filters underneath.
    */
   fromEq?: string;
+  /**
+   * Set on the gain stage the leveller writes, so re-running replaces it rather
+   * than stacking a second one — the same contract `fromCarve` has.
+   */
+  fromLeveller?: boolean;
   /** Absent means enabled — chain files written before the field existed still load. */
   enabled?: boolean;
   params?: HfAudioFxParamValues;
@@ -884,6 +889,7 @@ export function parseAudioFxChain(json: string): HfAudioFxChain {
       fromPreset?: unknown;
       label?: unknown;
       fromEq?: unknown;
+      fromLeveller?: unknown;
     };
     if (typeof node.type !== "string" || !BY_ID.has(node.type)) {
       throw new AudioFxChainError(`Node ${i} has unknown effect type: ${String(node.type)}`);
@@ -900,6 +906,7 @@ export function parseAudioFxChain(json: string): HfAudioFxChain {
         : {}),
       ...(typeof node.label === "string" && node.label ? { label: node.label } : {}),
       ...(typeof node.fromEq === "string" && node.fromEq ? { fromEq: node.fromEq } : {}),
+      ...(node.fromLeveller === true ? { fromLeveller: true as const } : {}),
       enabled: node.enabled !== false,
       params: normalizeAudioFxParams(
         node.type,
@@ -926,6 +933,7 @@ export function serializeAudioFxChain(chain: HfAudioFxChain): string {
       ...(node.fromPreset ? { fromPreset: node.fromPreset } : {}),
       ...(node.label ? { label: node.label } : {}),
       ...(node.fromEq ? { fromEq: node.fromEq } : {}),
+      ...(node.fromLeveller === true ? { fromLeveller: true } : {}),
       ...(node.enabled === false ? { enabled: false } : {}),
       params: normalizeAudioFxParams(node.type, node.params),
     })),

packages/core/src/audioLeveller.test.ts

@@ -0,0 +1,266 @@
+import { describe, expect, it } from "vitest";
+import {
+  HF_AUDIO_FX_CHAIN_VERSION,
+  parseAudioFxChain,
+  serializeAudioFxChain,
+  type HfAudioFxChain,
+} from "./audioFx.js";
+import { sampleAutomationLane } from "./audioAutomation.js";
+import { applyAudioFxPreset, getAudioFxPreset } from "./audioFxPresets.js";
+import {
+  analyseLevelling,
+  levellerProfile,
+  levellingResult,
+  levellingSummary,
+  removeLevelling,
+} from "./audioLeveller.js";
+
+const SR = 48000;
+const empty = (): HfAudioFxChain => ({ version: HF_AUDIO_FX_CHAIN_VERSION, nodes: [] });
+
+/** A tone whose amplitude changes per section, so the levelling has real work. */
+function uneven(sections: { seconds: number; amp: number }[]): Float32Array {
+  const total = sections.reduce((n, s) => n + Math.floor(SR * s.seconds), 0);
+  const out = new Float32Array(total);
+  let at = 0;
+  for (const section of sections) {
+    const n = Math.floor(SR * section.seconds);
+    for (let i = 0; i < n; i += 1) {
+      out[at + i] = section.amp * Math.sin((2 * Math.PI * 300 * (at + i)) / SR);
+    }
+    at += n;
+  }
+  return out;
+}
+
+const at = (points: { t: number; v: number }[], t: number) =>
+  sampleAutomationLane({ target: "fx.n1.gain", points }, t);
+
+describe("measuring", () => {
+  it("lifts a quiet passage and leaves the loud one alone", () => {
+    // Loud, then 18 dB down, then loud again.
+    const points = analyseLevelling(
+      uneven([
+        { seconds: 3, amp: 0.5 },
+        { seconds: 3, amp: 0.06 },
+        { seconds: 3, amp: 0.5 },
+      ]),
+      SR,
+    );
+    expect(points.length).toBeGreaterThan(0);
+    // Mid-quiet-section, well past the attack.
+    expect(at(points, 5.5)).toBeGreaterThan(3);
+    // Mid-loud-section, well past the release.
+    expect(Math.abs(at(points, 2.5))).toBeLessThan(2);
+  });
+
+  it("finds nothing to do on a track that is already even", () => {
+    // A script that always writes something teaches an author it is doing
+    // nothing; saying "already even" is the useful answer.
+    expect(analyseLevelling(uneven([{ seconds: 6, amp: 0.4 }]), SR)).toEqual([]);
+  });
+
+  it("leaves room tone alone rather than lifting it into the mix", () => {
+    // Deliberately NOT digital silence: a real pause is quiet but finite, and
+    // that is the case the floor exists for. Absolute zero would be skipped by
+    // the isFinite check alone and prove nothing.
+    const points = analyseLevelling(
+      uneven([
+        { seconds: 3, amp: 0.5 },
+        { seconds: 3, amp: 0.0008 },
+        { seconds: 3, amp: 0.5 },
+      ]),
+      SR,
+      1,
+    );
+    // ~56 dB down: a pause with a noise floor, not a quiet passage. Gain
+    // applied here is gain applied to the room.
+    expect(Math.abs(at(points, 5.5))).toBeLessThan(1.5);
+  });
+
+  it("targets a level the track reaches, not its loudest instant", () => {
+    // Mostly quiet with one loud burst. Against the PEAK the whole body of the
+    // track reads as "quiet" and gets hauled up; against a level the track
+    // actually sustains, the body is already the target and barely moves.
+    const points = analyseLevelling(
+      uneven([
+        { seconds: 6, amp: 0.08 },
+        { seconds: 1, amp: 0.8 },
+        { seconds: 5, amp: 0.08 },
+      ]),
+      SR,
+      1,
+    );
+    expect(Math.abs(at(points, 3))).toBeLessThan(3);
+  });
+
+  it("never asks for more correction than it can justify", () => {
+    // ~30 dB below the loud section: still well above the silence floor, so it
+    // IS a passage to lift — and at full strength the raw ask is over 25 dB,
+    // which is more gain than any quiet passage should be given.
+    const points = analyseLevelling(
+      uneven([
+        { seconds: 3, amp: 0.6 },
+        { seconds: 4, amp: 0.019 },
+      ]),
+      SR,
+      1,
+    );
+    expect(points.some((p) => p.v > 6)).toBe(true);
+    for (const p of points) expect(Math.abs(p.v)).toBeLessThanOrEqual(12);
+  });
+
+  it("starts at the clip's start, so the lane does not slide in from nowhere", () => {
+    const points = analyseLevelling(
+      uneven([
+        { seconds: 3, amp: 0.5 },
+        { seconds: 3, amp: 0.06 },
+      ]),
+      SR,
+    );
+    expect(points[0]?.t).toBe(0);
+  });
+
+  it("handles an empty track without inventing a lane", () => {
+    expect(analyseLevelling(new Float32Array(0), SR)).toEqual([]);
+    expect(analyseLevelling(uneven([{ seconds: 1, amp: 0.4 }]), 0)).toEqual([]);
+  });
+});
+
+describe("strength", () => {
+  it("corrects more the further it is turned up", () => {
+    const track = uneven([
+      { seconds: 3, amp: 0.5 },
+      { seconds: 3, amp: 0.06 },
+    ]);
+    const gentle = at(analyseLevelling(track, SR, 0.1), 5.5);
+    const strong = at(analyseLevelling(track, SR, 1), 5.5);
+    expect(strong).toBeGreaterThan(gentle);
+  });
+
+  it("still leaves some of the performance in at full strength", () => {
+    // Driving a track to a flat line removes the performance along with the
+    // inconsistency, so even 1.0 corrects most rather than all of it.
+    expect(levellerProfile(1).correction).toBeLessThan(1);
+    expect(levellerProfile(0).correction).toBeGreaterThan(0);
+  });
+});
+
+describe("what it writes", () => {
+  it("rides a gain node, because a volume lane can only attenuate", () => {
+    // VOLUME_RANGE is 0..1 and normaliseEnvelope clamps into it, so a volume
+    // lane cannot lift a quiet passage at all. This is the whole reason the
+    // script writes a node instead of only a lane.
+    const result = levellingResult(
+      empty(),
+      uneven([
+        { seconds: 3, amp: 0.5 },
+        { seconds: 3, amp: 0.06 },
+      ]),
+      SR,
+    );
+    expect(result).not.toBeNull();
+    const node = result!.chain.nodes[0]!;
+    expect(node.type).toBe("gain");
+    expect(node.label).toBe("Even Out Levels");
+    expect(node.params?.gain).toBe(0);
+    expect(result!.automation.lanes[0]!.target).toBe(`fx.${node.id}.gain`);
+  });
+
+  it("returns nothing when there is nothing to correct", () => {
+    expect(levellingResult(empty(), uneven([{ seconds: 6, amp: 0.4 }]), SR)).toBeNull();
+  });
+
+  it("replaces its own stage instead of stacking a second one", () => {
+    const track = uneven([
+      { seconds: 3, amp: 0.5 },
+      { seconds: 3, amp: 0.06 },
+    ]);
+    const once = levellingResult(empty(), track, SR)!;
+    const twice = levellingResult(once.chain, track, SR)!;
+    expect(twice.chain.nodes.filter((n) => n.fromLeveller)).toHaveLength(1);
+    // Same node id, so the lane it already wrote still addresses the right stage.
+    expect(twice.chain.nodes[0]!.id).toBe(once.chain.nodes[0]!.id);
+  });
+
+  it("goes in FRONT of a trailing limiter, never after it", () => {
+    // The likely sequence: apply Clean Voice, then even out the levels. Clean
+    // Voice ends in a Peak Ceiling, and up to 12 dB of lift landing after that
+    // ceiling means loud material at -1 dBFS goes over full scale and the
+    // render shears it flat. A ceiling with something after it is not a ceiling.
+    const voiced = applyAudioFxPreset(empty(), getAudioFxPreset("voice-clean")!);
+    expect(voiced.nodes[voiced.nodes.length - 1]!.type).toBe("limiter");
+
+    const result = levellingResult(
+      voiced,
+      uneven([
+        { seconds: 3, amp: 0.5 },
+        { seconds: 3, amp: 0.06 },
+      ]),
+      SR,
+    )!;
+    const types = result.chain.nodes.map((n) => n.type);
+    expect(types[types.length - 1]).toBe("limiter");
+    expect(types[types.length - 2]).toBe("gain");
+    expect(result.chain.nodes.find((n) => n.fromLeveller)).toBeTruthy();
+  });
+
+  it("leaves hand-added effects alone", () => {
+    const chain: HfAudioFxChain = {
+      version: HF_AUDIO_FX_CHAIN_VERSION,
+      nodes: [{ type: "reverb", id: "mine", enabled: true }],
+    };
+    const result = levellingResult(
+      chain,
+      uneven([
+        { seconds: 3, amp: 0.5 },
+        { seconds: 3, amp: 0.06 },
+      ]),
+      SR,
+    )!;
+    expect(result.chain.nodes.map((n) => n.id)).toContain("mine");
+    expect(result.chain.nodes).toHaveLength(2);
+  });
+
+  it("survives the attribute round trip", () => {
+    const result = levellingResult(
+      empty(),
+      uneven([
+        { seconds: 3, amp: 0.5 },
+        { seconds: 3, amp: 0.06 },
+      ]),
+      SR,
+    )!;
+    const back = parseAudioFxChain(serializeAudioFxChain(result.chain));
+    // Without fromLeveller surviving, re-running stacks a second gain stage.
+    expect(back.nodes.filter((n) => n.fromLeveller)).toHaveLength(1);
+    expect(back.nodes[0]!.label).toBe("Even Out Levels");
+  });
+
+  it("names the lane it takes away with it", () => {
+    const result = levellingResult(
+      empty(),
+      uneven([
+        { seconds: 3, amp: 0.5 },
+        { seconds: 3, amp: 0.06 },
+      ]),
+      SR,
+    )!;
+    const removed = removeLevelling(result.chain);
+    expect(removed.chain.nodes).toHaveLength(0);
+    // An orphaned lane keeps driving a parameter that is no longer there.
+    expect(removed.removedTarget).toBe(result.automation.lanes[0]!.target);
+  });
+});
+
+describe("what it says", () => {
+  it("describes the moves rather than listing numbers", () => {
+    expect(
+      levellingSummary([
+        { t: 0, v: 0 },
+        { t: 1, v: 4.2 },
+      ]),
+    ).toMatch(/lifting quiet parts/);
+    expect(levellingSummary([])).toMatch(/Already even/);
+  });
+});