Skip to content

Open source CapCut alternative.

TypeScript
11.5 KB
Raw Blame
import { describe, expect, test } from "bun:test";
import {
  integratedFrom,
  kWeighting,
  LoudnessMeter,
  masterInPlace,
  masterPlan,
  measureLoudness,
  measureLoudnessSliced,
  TruePeakLimiter,
} from "./loudness";

const RATE = 48000;

/** A sine at `dbfs` peak, `seconds` long. */
const sine = (hz: number, dbfs: number, seconds: number, rate = RATE, phase = 0) => {
  const a = 10 ** (dbfs / 20);
  const n = Math.round(seconds * rate);
  const x = new Float32Array(n);
  for (let i = 0; i < n; i++) x[i] = a * Math.sin((2 * Math.PI * hz * i) / rate + phase);
  return x;
};
const concat = (...parts: Float32Array[]) => {
  const out = new Float32Array(parts.reduce((s, p) => s + p.length, 0));
  let at = 0;
  for (const p of parts) {
    out.set(p, at);
    at += p.length;
  }
  return out;
};
const stereo = (x: Float32Array) => [x, x.slice()];

/** The magnitude response of the two K-weighting stages at `hz`, in dB. */
const responseDb = (hz: number, rate: number) => {
  const w = (2 * Math.PI * hz) / rate;
  let mag = 1;
  for (const { b, a } of kWeighting(rate)) {
    const re = (c: number[]) => c[0] + c[1] * Math.cos(-w) + c[2] * Math.cos(-2 * w);
    const im = (c: number[]) => c[1] * Math.sin(-w) + c[2] * Math.sin(-2 * w);
    mag *= Math.hypot(re(b), im(b)) / Math.hypot(re(a), im(a));
  }
  return 20 * Math.log10(mag);
};

describe("K-weighting", () => {
  test("reproduces the coefficients BS.1770 prints for 48 kHz", () => {
    const [shelf, hp] = kWeighting(48000);
    const close = (got: number[], want: number[]) =>
      got.forEach((v, i) => expect(Math.abs(v - want[i])).toBeLessThan(1e-8));
    close(shelf.b, [1.53512485958697, -2.69169618940638, 1.19839281085285]);
    close(shelf.a, [1, -1.69065929318241, 0.73248077421585]);
    close(hp.b, [1, -2, 1]);
    close(hp.a, [1, -1.99004745483398, 0.99007225036621]);
  });

  test("has the curve's shape at any rate: flat-ish at 1 kHz, +4 dB high, rolled off low", () => {
    for (const rate of [44100, 48000, 96000]) {
      // −0.691 in the loudness formula cancels this gain.
      expect(Math.abs(responseDb(997, rate) - 0.691)).toBeLessThan(0.02);
      expect(Math.abs(responseDb(10000, rate) - 4)).toBeLessThan(0.3);
      expect(responseDb(20, rate)).toBeLessThan(-10);
    }
  });
});

describe("integrated loudness", () => {
  test("a full-scale 997 Hz sine in one channel reads −3.01 LUFS", () => {
    const x = sine(997, 0, 5);
    const m = measureLoudness([x, new Float32Array(x.length)], RATE);
    expect(Math.abs(m.integratedLufs - -3.01)).toBeLessThan(0.05);
  });

  test("a stereo 1 kHz sine at −23 dBFS reads −23 LUFS (EBU Tech 3341 case 1)", () => {
    const m = measureLoudness(stereo(sine(1000, -23, 20)), RATE);
    expect(Math.abs(m.integratedLufs - -23)).toBeLessThan(0.1);
  });

  test("a mono source weighted as the two channels it plays on reads as that stereo pair", () => {
    const x = sine(1000, -20, 10);
    const mono = new LoudnessMeter(RATE, 1);
    mono.push([x]);
    const pair = measureLoudness(stereo(x), RATE);
    expect(Math.abs(mono.result().integratedLufs - pair.integratedLufs)).toBeLessThan(0.01);
  });

  test("the sliced measurement matches the one-shot one", async () => {
    const x = stereo(concat(sine(1000, -18, 4), sine(440, -30, 3)));
    const whole = measureLoudness(x, RATE);
    const sliced = await measureLoudnessSliced(x, RATE);
    expect(sliced.integratedLufs).toBeCloseTo(whole.integratedLufs, 6);
    expect(sliced.truePeakDbtp).toBeCloseTo(whole.truePeakDbtp, 6);
  });

  test("reads the same at 44.1 kHz", () => {
    const m = measureLoudness(stereo(sine(1000, -33, 20, 44100)), 44100);
    expect(Math.abs(m.integratedLufs - -33)).toBeLessThan(0.1);
  });

  test("the relative gate drops the quiet passages (Tech 3341 case 3)", () => {
    const x = concat(sine(1000, -36, 10), sine(1000, -23, 60), sine(1000, -36, 10));
    expect(Math.abs(measureLoudness(stereo(x), RATE).integratedLufs - -23)).toBeLessThan(0.1);
  });

  test("both gates together (Tech 3341 case 4)", () => {
    const x = concat(
      sine(1000, -72, 10),
      sine(1000, -36, 10),
      sine(1000, -23, 60),
      sine(1000, -36, 10),
      sine(1000, -72, 10)
    );
    expect(Math.abs(measureLoudness(stereo(x), RATE).integratedLufs - -23)).toBeLessThan(0.1);
  });

  test("silence has no integrated loudness", () => {
    const m = measureLoudness(stereo(new Float32Array(RATE * 3)), RATE);
    expect(m.integratedLufs).toBe(-Infinity);
  });

  test("gating keeps blocks over the absolute gate and within 10 LU of their mean", () => {
    const p = (l: number) => 10 ** ((l + 0.691) / 10);
    // −80 is silence; −35 is 15 LU under the −20 block's mean; the mean of
    // what remains is the two −20 blocks.
    expect(integratedFrom([p(-80), p(-20), p(-35), p(-20)])).toBeCloseTo(-20, 6);
  });

  test("the answer does not depend on how the audio was chunked", () => {
    const x = concat(sine(440, -18, 3), sine(3000, -30, 2));
    const whole = measureLoudness(stereo(x), RATE);
    const meter = new LoudnessMeter(RATE, 2);
    for (let i = 0; i < x.length; i += 1013) meter.push(stereo(x.subarray(i, i + 1013)));
    const chunked = meter.result();
    expect(chunked.integratedLufs).toBeCloseTo(whole.integratedLufs, 9);
    expect(chunked.truePeakDbtp).toBeCloseTo(whole.truePeakDbtp, 9);
  });
});

describe("loudness range", () => {
  test("two halves 10 LU apart read about 10 LU (Tech 3342 case 1)", () => {
    const x = concat(sine(1000, -20, 20), sine(1000, -30, 20));
    expect(Math.abs(measureLoudness(stereo(x), RATE).loudnessRangeLu - 10)).toBeLessThan(1);
  });

  test("halves 20 LU apart read about 20 LU (Tech 3342 case 3)", () => {
    const x = concat(sine(1000, -40, 20), sine(1000, -20, 20));
    expect(Math.abs(measureLoudness(stereo(x), RATE).loudnessRangeLu - 20)).toBeLessThan(1);
  });
});

describe("true peak", () => {
  test("finds the peak between samples: a quarter-rate sine sampled at ±45°", () => {
    // Every sample sits at 0.707 of the waveform's peak, so the samples read
    // −3.01 dBFS while the signal reaches 0 dBTP.
    const x = sine(RATE / 4, -1, 1, RATE, Math.PI / 4);
    const m = measureLoudness(stereo(x), RATE);
    expect(m.samplePeakDbfs).toBeCloseTo(-4.01, 1);
    expect(m.truePeakDbtp).toBeGreaterThan(-1.2);
    expect(m.truePeakDbtp).toBeLessThan(-0.8);
  });

  test("equals the sample peak where the samples already carry it", () => {
    const m = measureLoudness(stereo(sine(997, -6, 1)), RATE);
    expect(Math.abs(m.truePeakDbtp - -6)).toBeLessThan(0.05);
  });

  test("catches a peak split across two chunks", () => {
    const x = sine(RATE / 4, 0, 0.01, RATE, Math.PI / 4);
    const meter = new LoudnessMeter(RATE, 1);
    meter.push([x.subarray(0, 241)]);
    meter.push([x.subarray(241)]);
    expect(meter.result().truePeakDbtp).toBeGreaterThan(-0.2);
  });
});

describe("mastering plan", () => {
  const measure = (integratedLufs: number, truePeakDbtp: number) => ({
    integratedLufs,
    truePeakDbtp,
    samplePeakDbfs: truePeakDbtp,
    loudnessRangeLu: 0,
    maxMomentaryLufs: integratedLufs,
    maxShortTermLufs: integratedLufs,
    seconds: 10,
  });

  test("one static gain to the target, no limiter when the peak stays under", () => {
    expect(masterPlan(measure(-20, -8), -14, -1)).toEqual({ gainDb: 6, limit: false, peakAfterGainDbtp: -2 });
  });

  test("limits only when the gained peak crosses the ceiling", () => {
    const plan = masterPlan(measure(-20, -4), -14, -1);
    expect(plan.gainDb).toBe(6);
    expect(plan.limit).toBe(true);
  });

  test("a mix that is too loud comes down, and needs no limiter", () => {
    const plan = masterPlan(measure(-9, 0.5), -14, -1);
    expect(plan.gainDb).toBe(-5);
    expect(plan.limit).toBe(false);
  });

  test("silence keeps its level", () => {
    expect(masterPlan(measure(-Infinity, -90), -14, -1).gainDb).toBe(0);
  });
});

describe("true-peak limiter", () => {
  const run = (input: Float32Array[], ceiling: number) => {
    const lim = new TruePeakLimiter(RATE, input.length, ceiling);
    const parts: Float32Array[][] = [];
    for (let i = 0; i < input[0].length; i += 4096) parts.push(lim.process(input.map((c) => c.subarray(i, i + 4096))));
    parts.push(lim.flush());
    return input.map((_, c) => concat(...parts.map((p) => p[c])));
  };

  test("holds the true peak under the ceiling, inter-sample overs included", () => {
    // A loud tone with quarter-rate bursts whose peaks fall between samples.
    const tone = sine(220, 3, 2);
    const burst = sine(RATE / 4, 4, 2, RATE, Math.PI / 4);
    const x = tone.map((v, i) => v + (Math.floor(i / 4800) % 3 === 0 ? burst[i] : 0));
    const out = run(stereo(Float32Array.from(x)), -1);
    expect(out[0].length).toBe(x.length);
    expect(measureLoudness(out, RATE).truePeakDbtp).toBeLessThanOrEqual(-1);
  });

  test("passes audio under the ceiling through untouched and aligned", () => {
    const x = sine(1000, -12, 0.5);
    const [out] = run([x], -1);
    expect(out.length).toBe(x.length);
    let worst = 0;
    for (let i = 0; i < x.length; i++) worst = Math.max(worst, Math.abs(out[i] - x[i]));
    expect(worst).toBeLessThan(1e-6);
  });

  test("glides into a reduction instead of stepping: no sample changes gain abruptly", () => {
    const quiet = sine(100, -20, 0.5);
    const loud = sine(100, 0, 0.5);
    const x = concat(quiet, loud);
    const [out] = run([x], -6);
    // The gain at each pair of neighbouring samples, where it can be read
    // off the input.
    let jump = 0;
    for (let i = 1; i < x.length; i++) {
      if (Math.abs(x[i]) < 0.05 || Math.abs(x[i - 1]) < 0.05) continue;
      jump = Math.max(jump, Math.abs(out[i] / x[i] - out[i - 1] / x[i - 1]));
    }
    // A window of 5 ms at 48 kHz: the steepest step is the whole reduction
    // spread over 240 samples.
    expect(jump).toBeLessThan(0.005);
  });
});

describe("master in place", () => {
  test("lands a mix on the target with its true peak under the ceiling", async () => {
    // Speech-like: a tone that comes and goes, quiet overall with hot peaks.
    const x = new Float32Array(RATE * 6);
    for (let i = 0; i < x.length; i++) {
      const env = 0.5 + 0.5 * Math.sin((2 * Math.PI * i) / RATE);
      x[i] = 0.05 * env * Math.sin((2 * Math.PI * 300 * i) / RATE) + (i % 9600 < 200 ? 0.3 : 0) * Math.sin(i);
    }
    const channels = stereo(x);
    const report = await masterInPlace(channels, { sampleRate: RATE, targetLufs: -14, ceilingDbtp: -1 });
    const after = measureLoudness(channels, RATE);
    expect(report.plan.limit).toBe(true);
    expect(after.truePeakDbtp).toBeLessThanOrEqual(-1);
    // The limiter takes a little off the top of these hot bursts; the
    // integrated level lands within a unit of the target.
    expect(Math.abs(after.integratedLufs - -14)).toBeLessThan(1);
  });

  test("a mono delivery lands as loud as the stereo delivery of the same sound", async () => {
    const mono = [sine(1000, -30, 5)];
    const pair = stereo(sine(1000, -30, 5));
    const one = await masterInPlace(mono, { sampleRate: RATE, targetLufs: -14, ceilingDbtp: -1 });
    const two = await masterInPlace(pair, { sampleRate: RATE, targetLufs: -14, ceilingDbtp: -1 });
    expect(one.plan.gainDb).toBeCloseTo(two.plan.gainDb, 2);
  });

  test("a clean gain when no limiting is needed", async () => {
    const channels = stereo(sine(1000, -30, 5));
    const report = await masterInPlace(channels, { sampleRate: RATE, targetLufs: -23, ceilingDbtp: -1 });
    expect(report.plan.limit).toBe(false);
    expect(Math.abs(measureLoudness(channels, RATE).integratedLufs - -23)).toBeLessThan(0.05);
  });
});