Skip to content

Open source CapCut alternative.

TypeScript
27.9 KB
Raw Blame
/**
 * Loudness as ITU-R BS.1770-4 and EBU R128 define it, and the mastering that
 * reads it.
 *
 * A level in dBFS answers "how much signal is there". Loudness answers how
 * loud a listener hears it, and the two part ways wherever the energy sits in
 * the spectrum: a bass line and a voice at the same RMS do not sound equally
 * loud. BS.1770 closes that gap with a fixed pre-filter, the K-weighting — a
 * high shelf that lifts what the head boosts above 2 kHz and a high-pass that
 * drops the rumble the ear barely registers — and then measures power.
 *
 * Integrated loudness is the power over the whole programme, measured in
 * 400 ms blocks every 100 ms and gated twice: blocks under −70 LUFS are
 * silence, and blocks more than 10 LU under the loudness of what remains are
 * the pauses between things. What survives is what the listener actually
 * hears as the programme. Loudness range is the spread of the 3 s short-term
 * loudness between its 10th and 95th percentile, after its own gates.
 *
 * True peak is where the waveform goes between the samples. A converter
 * draws a smooth curve through them, and that curve can rise above every
 * sample it passes through; a lossy encoder adds its own overshoot on top. So
 * the peak is read on a 4× oversampled copy, and the limiter holds that peak
 * under its ceiling.
 *
 * Everything here works on plain sample arrays and keeps its state across
 * calls, so the tab can hand it a whole mix and the engine a file read a
 * second at a time, and both reach the same answer.
 */

/** Blocks under this are silence (EBU R128 absolute gate). */
const ABSOLUTE_GATE = -70;
/** Integrated loudness drops blocks this far under the ungated mean. */
const RELATIVE_GATE = -10;
/** Loudness range drops short-term values this far under their mean. */
const RANGE_GATE = -20;
/** The gating step: 100 ms, so a 400 ms block is four steps. */
const STEP_S = 0.1;
const BLOCK_STEPS = 4;
/** Short-term loudness reads 3 s. */
const SHORT_TERM_STEPS = 30;

/** One K-weighting biquad, as a/b with a0 = 1. */
interface Biquad {
  b: [number, number, number];
  a: [number, number, number];
}

/**
 * The K-weighting pre-filter at `sampleRate`: the high-shelf stage, then the
 * RLB high-pass stage.
 *
 * BS.1770 prints the coefficients for 48 kHz only. The analog prototypes
 * below are the ones those coefficients come from, so the bilinear
 * transform reproduces the printed values at 48 kHz and gives the same
 * response at 44.1 kHz or 96 kHz.
 */
export function kWeighting(sampleRate: number): [Biquad, Biquad] {
  // Stage 1: the high shelf, +4 dB above about 1.7 kHz.
  const f0 = 1681.974450955533;
  const gain = 3.999843853973347;
  const q = 0.7071752369554196;
  const k = Math.tan((Math.PI * f0) / sampleRate);
  const vh = 10 ** (gain / 20);
  const vb = vh ** 0.4996667741545416;
  const a0 = 1 + k / q + k * k;
  const shelf: Biquad = {
    b: [(vh + (vb * k) / q + k * k) / a0, (2 * (k * k - vh)) / a0, (vh - (vb * k) / q + k * k) / a0],
    a: [1, (2 * (k * k - 1)) / a0, (1 - k / q + k * k) / a0],
  };
  // Stage 2: the RLB high-pass at about 38 Hz.
  const f1 = 38.13547087602444;
  const q1 = 0.5003270373238773;
  const k1 = Math.tan((Math.PI * f1) / sampleRate);
  const d = 1 + k1 / q1 + k1 * k1;
  const highpass: Biquad = {
    b: [1, -2, 1],
    a: [1, (2 * (k1 * k1 - 1)) / d, (1 - k1 / q1 + k1 * k1) / d],
  };
  return [shelf, highpass];
}

/** Channel weights for a layout: front channels count once, the surrounds
 * 1.41 (+1.5 dB), and the LFE not at all. Mono counts as the two speakers
 * it plays on, so a mono file and the stereo file of the same sound read
 * the same. */
function channelWeights(channels: number): number[] {
  // L R C LFE Ls Rs
  if (channels === 6) return [1, 1, 1, 0, 1.41, 1.41];
  if (channels === 1) return [2];
  return Array.from({ length: channels }, () => 1);
}

/** Power to LUFS: −0.691 cancels the K-weighting's gain at 997 Hz, so a
 * full-scale sine there reads −3.01 LUFS in one channel. */
const lufs = (power: number) => (power > 0 ? -0.691 + 10 * Math.log10(power) : -Infinity);
const fromLufs = (l: number) => 10 ** ((l + 0.691) / 10);

/* ------------------------------------------------------- true peak */

/** Half the interpolator's taps: each phase reads this many samples on each
 * side of the point it estimates. */
const HALF_TAPS = 8;
const TAPS = HALF_TAPS * 2;

/** How far the curve between two samples is taken to rise over the louder
 * of them. Audio rises about 3 dB there at the very worst (a quarter-rate
 * tone sampled either side of its crest); twice that is the margin. A point
 * whose neighbours could not reach the peak in hand times this is never
 * interpolated, which is what keeps the meter cheap on a dense mix. */
const OVERSHOOT = 2;

/**
 * The 4× interpolator, as three fractional-delay filters: the values a
 * quarter, a half and three quarters of the way from one sample to the next.
 * The sample itself is the fourth phase. Each filter is a Kaiser-windowed
 * sinc normalized to unity gain at DC.
 */
function interpolatorPhases(factor: number): Float64Array[] {
  const besselI0 = (x: number) => {
    let sum = 1;
    let term = 1;
    for (let k = 1; k < 32; k++) {
      term *= (x / (2 * k)) ** 2;
      sum += term;
    }
    return sum;
  };
  const beta = 6;
  const span = HALF_TAPS + 0.5;
  const phases: Float64Array[] = [];
  for (let p = 1; p < factor; p++) {
    const frac = p / factor;
    const taps = new Float64Array(TAPS);
    let total = 0;
    for (let j = 0; j < TAPS; j++) {
      // Tap j reads the sample at offset j - (HALF_TAPS - 1) from the left
      // neighbour of the point, which sits `frac` past it.
      const d = frac - (j - (HALF_TAPS - 1));
      const sinc = d === 0 ? 1 : Math.sin(Math.PI * d) / (Math.PI * d);
      const r = d / span;
      const w = Math.abs(r) >= 1 ? 0 : besselI0(beta * Math.sqrt(1 - r * r)) / besselI0(beta);
      taps[j] = sinc * w;
      total += taps[j];
    }
    for (let j = 0; j < TAPS; j++) taps[j] /= total;
    phases.push(taps);
  }
  return phases;
}

/** Oversampling that reads a true peak at a rate: 4× up to 96 kHz, 2× to
 * 192 kHz, and the samples themselves above that. */
function oversampling(sampleRate: number): number {
  return sampleRate >= 176400 ? 1 : sampleRate >= 88200 ? 2 : 4;
}

/** The oversampled curve between samples. */
class Interpolator {
  /** Up to three phases' taps; a phase the rate does not use is all zeros
   * and reads as silence, which never wins the peak. */
  private readonly h1: Float64Array;
  private readonly h2: Float64Array;
  private readonly h3: Float64Array;

  constructor(sampleRate: number) {
    const phases = interpolatorPhases(oversampling(sampleRate));
    const zero = new Float64Array(TAPS);
    // 2× has one phase, the midpoint; 4× has three.
    this.h1 = phases.length === 3 ? phases[0] : zero;
    this.h2 = phases.length === 3 ? phases[1] : (phases[0] ?? zero);
    this.h3 = phases.length === 3 ? phases[2] : zero;
  }

  /** The loudest interpolated value between x[i] and x[i + 1], where the
   * window x[i - HALF_TAPS + 1 .. i + HALF_TAPS] is all in range. Every
   * phase is read in one pass over the window. */
  between(x: Float32Array | Float64Array, i: number): number {
    const base = i - (HALF_TAPS - 1);
    const { h1, h2, h3 } = this;
    let y1 = 0;
    let y2 = 0;
    let y3 = 0;
    for (let j = 0; j < TAPS; j++) {
      const v = x[base + j];
      y1 += h1[j] * v;
      y2 += h2[j] * v;
      y3 += h3[j] * v;
    }
    const a1 = y1 < 0 ? -y1 : y1;
    const a2 = y2 < 0 ? -y2 : y2;
    const a3 = y3 < 0 ? -y3 : y3;
    return a1 > a2 ? (a1 > a3 ? a1 : a3) : a2 > a3 ? a2 : a3;
  }
}

/* ------------------------------------------------------- the meter */

/** What a stretch of audio measures. */
export interface LoudnessMeasure {
  /** Gated programme loudness, LUFS; −Infinity when nothing clears the
   * absolute gate. */
  integratedLufs: number;
  /** The loudest point of the waveform, sample or in between, dBTP. */
  truePeakDbtp: number;
  /** The loudest sample, dBFS. */
  samplePeakDbfs: number;
  /** Spread of the short-term loudness, LU (EBU Tech 3342). */
  loudnessRangeLu: number;
  /** The loudest 400 ms block, LUFS. */
  maxMomentaryLufs: number;
  /** The loudest 3 s window, LUFS. */
  maxShortTermLufs: number;
  /** Seconds measured. */
  seconds: number;
}

/**
 * A streaming BS.1770 meter. Push planar chunks of any length; read the
 * result at the end.
 *
 * The weighted power of every 100 ms step is kept — ten numbers a second —
 * and the blocks, the gates and the range are all computed from those at the
 * end, so a chunk boundary can land anywhere without changing the answer.
 */
export class LoudnessMeter {
  private readonly stages: [Biquad, Biquad];
  /** Per channel: the two biquads' state, x1 x2 y1 y2 for each. */
  private readonly state: Float64Array[];
  private readonly weights: number[];
  private readonly stepLength: number;
  private stepPower = 0;
  private stepFill = 0;
  /** Weighted mean square of every finished step. */
  private steps: number[] = [];
  private samples = 0;
  private samplePeak = 0;
  private truePeak = 0;
  private readonly interp: Interpolator;
  /** The last samples of each channel, for interpolating across chunks. */
  private tails: Float32Array[];

  constructor(
    readonly sampleRate: number,
    readonly channels: number
  ) {
    this.stages = kWeighting(sampleRate);
    this.state = Array.from({ length: channels }, () => new Float64Array(8));
    this.weights = channelWeights(channels);
    this.stepLength = Math.round(sampleRate * STEP_S);
    this.interp = new Interpolator(sampleRate);
    // The stream opens on silence: the first samples interpolate against
    // zeros, the way a converter starting from rest would draw them.
    this.tails = Array.from({ length: channels }, () => new Float32Array(TAPS - 1));
  }

  /** Measure `chunk`: one array per channel, all the same length. */
  push(chunk: ArrayLike<number>[]): void {
    const n = chunk[0]?.length ?? 0;
    if (n === 0) return;
    this.weigh(chunk, n);
    this.peaks(chunk, n);
    this.samples += n;
  }

  private weigh(chunk: ArrayLike<number>[], n: number) {
    const [s1, s2] = this.stages;
    const [p0, p1, p2] = s1.b;
    const [, pa1, pa2] = s1.a;
    const [q0, q1, q2] = s2.b;
    const [, qa1, qa2] = s2.a;
    let offset = 0;
    while (offset < n) {
      const take = Math.min(n - offset, this.stepLength - this.stepFill);
      let power = 0;
      for (let c = 0; c < this.channels; c++) {
        const w = this.weights[c] ?? 1;
        const x = chunk[c];
        const st = this.state[c];
        let [ax1, ax2, ay1, ay2, bx1, bx2, by1, by2] = st;
        let sum = 0;
        for (let i = offset; i < offset + take; i++) {
          const v = x[i];
          const y = p0 * v + p1 * ax1 + p2 * ax2 - pa1 * ay1 - pa2 * ay2;
          ax2 = ax1;
          ax1 = v;
          ay2 = ay1;
          ay1 = y;
          const z = q0 * y + q1 * bx1 + q2 * bx2 - qa1 * by1 - qa2 * by2;
          bx2 = bx1;
          bx1 = y;
          by2 = by1;
          by1 = z;
          sum += z * z;
        }
        st[0] = ax1;
        st[1] = ax2;
        st[2] = ay1;
        st[3] = ay2;
        st[4] = bx1;
        st[5] = bx2;
        st[6] = by1;
        st[7] = by2;
        if (w !== 0) power += w * sum;
      }
      this.stepPower += power;
      this.stepFill += take;
      offset += take;
      if (this.stepFill === this.stepLength) {
        this.steps.push(this.stepPower / this.stepLength);
        this.stepPower = 0;
        this.stepFill = 0;
      }
    }
  }

  private peaks(chunk: ArrayLike<number>[], n: number) {
    const keep = TAPS - 1;
    for (let c = 0; c < this.channels; c++) {
      const x = chunk[c];
      // The window is the previous chunk's tail followed by this chunk, so
      // the points between the two are measured too.
      const ext = new Float32Array(keep + n);
      ext.set(this.tails[c], 0);
      for (let i = 0; i < n; i++) {
        const v = x[i];
        ext[keep + i] = v;
        const a = v < 0 ? -v : v;
        if (a > this.samplePeak) this.samplePeak = a;
      }
      if (this.samplePeak > this.truePeak) this.truePeak = this.samplePeak;
      this.truePeak = Math.max(this.truePeak, scanBetween(this.interp, ext, this.truePeak));
      this.tails[c] = ext.slice(ext.length - keep);
    }
  }

  /** The measurement of everything pushed so far. */
  result(): LoudnessMeasure {
    // The curve past the last samples, as it falls back to rest.
    let truePeak = this.truePeak;
    for (const tail of this.tails) {
      const ext = new Float32Array(tail.length + HALF_TAPS + 1);
      ext.set(tail, 0);
      truePeak = Math.max(truePeak, scanBetween(this.interp, ext, truePeak));
    }
    const blocks = windowMeans(this.steps, BLOCK_STEPS);
    const shortTerm = windowMeans(this.steps, SHORT_TERM_STEPS);
    return {
      integratedLufs: integratedFrom(blocks),
      truePeakDbtp: 20 * Math.log10(truePeak || 1e-10),
      samplePeakDbfs: 20 * Math.log10(this.samplePeak || 1e-10),
      loudnessRangeLu: rangeFrom(shortTerm),
      maxMomentaryLufs: lufs(blocks.reduce((m, p) => (p > m ? p : m), 0)),
      maxShortTermLufs: lufs(shortTerm.reduce((m, p) => (p > m ? p : m), 0)),
      seconds: this.samples / this.sampleRate,
    };
  }
}

/** The mean power of every `n`-step window, one step apart. */
function windowMeans(steps: number[], n: number): number[] {
  const means: number[] = [];
  for (let j = 0; j + n <= steps.length; j++) {
    let p = 0;
    for (let k = 0; k < n; k++) p += steps[j + k];
    means.push(p / n);
  }
  return means;
}

/** The loudest point between samples in `x` that could beat `floor`. Points
 * whose window cannot reach it are never interpolated. */
function scanBetween(interp: Interpolator, x: Float32Array, floor: number): number {
  let peak = floor;
  const first = HALF_TAPS - 1;
  const last = x.length - HALF_TAPS - 1;
  for (let i = first; i <= last; i++) {
    const a = x[i] < 0 ? -x[i] : x[i];
    const b = x[i + 1] < 0 ? -x[i + 1] : x[i + 1];
    if ((a > b ? a : b) * OVERSHOOT <= peak) continue;
    const v = interp.between(x, i);
    if (v > peak) peak = v;
  }
  return peak;
}

/** Integrated loudness from block powers: the absolute gate, then the
 * relative gate 10 LU under what the absolute gate kept. */
export function integratedFrom(blocks: number[]): number {
  const abs = fromLufs(ABSOLUTE_GATE);
  const loud = blocks.filter((p) => p > abs);
  if (loud.length === 0) return -Infinity;
  const ungated = loud.reduce((s, p) => s + p, 0) / loud.length;
  const rel = fromLufs(lufs(ungated) + RELATIVE_GATE);
  const kept = loud.filter((p) => p > rel);
  if (kept.length === 0) return -Infinity;
  return lufs(kept.reduce((s, p) => s + p, 0) / kept.length);
}

/** Loudness range from short-term powers (EBU Tech 3342): gate at −70 LUFS
 * and 20 LU under the mean, then the 10th to the 95th percentile. */
function rangeFrom(shortTerm: number[]): number {
  const abs = fromLufs(ABSOLUTE_GATE);
  const loud = shortTerm.filter((p) => p > abs);
  if (loud.length === 0) return 0;
  const mean = loud.reduce((s, p) => s + p, 0) / loud.length;
  const rel = fromLufs(lufs(mean) + RANGE_GATE);
  const kept = loud
    .filter((p) => p > rel)
    .map(lufs)
    .sort((a, b) => a - b);
  if (kept.length === 0) return 0;
  const at = (q: number) => {
    const pos = q * (kept.length - 1);
    const lo = Math.floor(pos);
    const hi = Math.min(kept.length - 1, lo + 1);
    return kept[lo] + (kept[hi] - kept[lo]) * (pos - lo);
  };
  return at(0.95) - at(0.1);
}

/** Measure whole planar buffers in one go. */
export function measureLoudness(channels: ArrayLike<number>[], sampleRate: number): LoudnessMeasure {
  const meter = new LoudnessMeter(sampleRate, channels.length);
  meter.push(channels);
  return meter.result();
}

/** `measureLoudness` in half-second slices with a yield between them, for a
 * whole mix measured on the page's thread. */
export async function measureLoudnessSliced(channels: Float32Array[], sampleRate: number): Promise<LoudnessMeasure> {
  const meter = new LoudnessMeter(sampleRate, channels.length);
  for await (const slice of halfSeconds(channels, sampleRate, "view")) meter.push(slice);
  return meter.result();
}

/** How a slice of a buffer comes out: a view onto it, or a copy that later
 * writes to the buffer cannot change. */
type SliceKind = "view" | "copy";

/** Planar buffers in half-second slices, yielding the thread after each, so
 * a long mix never holds it for the whole of its length. */
async function* halfSeconds(channels: Float32Array[], sampleRate: number, kind: SliceKind): AsyncGenerator<Float32Array[]> {
  const slice = Math.max(1, Math.round(sampleRate / 2));
  const length = channels[0]?.length ?? 0;
  for (let i = 0; i < length; i += slice) {
    const end = Math.min(length, i + slice);
    yield channels.map((c) => (kind === "view" ? c.subarray(i, end) : c.slice(i, end)));
    await new Promise<void>((r) => setTimeout(r, 0));
  }
}

/** A measurement rounded for a reply: two decimals, and null where there is
 * no number (silence has no integrated loudness). */
export function roundedLoudness(m: LoudnessMeasure) {
  const r = (v: number) => (Number.isFinite(v) ? Math.round(v * 100) / 100 : null);
  return {
    integratedLufs: r(m.integratedLufs),
    truePeakDbtp: r(m.truePeakDbtp),
    loudnessRangeLu: r(m.loudnessRangeLu),
    maxShortTermLufs: r(m.maxShortTermLufs),
  };
}

/* ------------------------------------------------------- mastering */

/** What a master does to a mix: one static gain, and the limiter only when
 * the gained mix would cross the ceiling. */
interface MasterPlan {
  gainDb: number;
  limit: boolean;
  /** The true peak the gain alone would leave, dBTP. */
  peakAfterGainDbtp: number;
}

/**
 * Plan a master from a measurement. Silence has no loudness to move, so it
 * keeps its level; anything else moves by exactly the distance to the
 * target, and the limiter runs only where that gain carries the true peak
 * past the ceiling.
 */
export function masterPlan(measured: LoudnessMeasure, targetLufs: number, ceilingDbtp: number): MasterPlan {
  const gainDb = Number.isFinite(measured.integratedLufs) ? targetLufs - measured.integratedLufs : 0;
  const peakAfterGainDbtp = measured.truePeakDbtp + gainDb;
  return { gainDb, limit: peakAfterGainDbtp > ceilingDbtp, peakAfterGainDbtp };
}

/** How long the limiter looks ahead, and so how long it takes to reach a
 * reduction: long enough that the gain glides down, short enough that a
 * transient does not pull the sound before it audibly early. */
const LOOKAHEAD_S = 0.005;
/** How quickly the reduction lets go, as a time constant. Long enough to
 * avoid the flutter a fast release makes on bass, short enough that the mix
 * does not sit audibly lower after a hit. */
const RELEASE_S = 0.12;
/** Headroom kept under the ceiling for the small error between the gain the
 * limiter applies and the curve it predicts. */
const CEILING_MARGIN_DB = 0.05;

/**
 * A look-ahead true-peak limiter, linked across channels.
 *
 * For every sample it works out the gain that would keep the loudest point
 * near it — the sample, or the interpolated curve on either side — under the
 * ceiling. The gain it applies is that requirement held over the look-ahead
 * window, let go on an exponential release, and averaged over the window
 * again. Every held value that goes into a sample's average is no more than
 * that sample's requirement, so the average is no more than it either and the
 * ceiling holds; and the averaging is what makes the gain glide instead of
 * stepping, which is the difference between limiting and clipping.
 *
 * The output runs `latency` samples behind the input. `process` returns what
 * is ready and `flush` the rest, so the total comes out the same length as
 * what went in and lines up with it sample for sample.
 */
export class TruePeakLimiter {
  readonly latency: number;
  private readonly window: number;
  private readonly ceiling: number;
  private readonly release: number;
  private readonly interp: Interpolator;
  /** Input history per channel: long enough to interpolate and to delay. */
  private readonly hist: Float64Array[];
  /** The loudest channel's |x| per sample, on the same ring. */
  private readonly loudest: Float64Array;
  private readonly histMask: number;
  /** Samples fed (real and the flush's padding), real ones received, and
   * samples handed back. */
  private fed = 0;
  private received = 0;
  private emitted = 0;
  /** Required gains, a monotonic deque over them for the forward minimum,
   * and the held gains the running average reads: rings by sample index. */
  private readonly need: Float64Array;
  private readonly dq: Int32Array;
  private dqHead = 0;
  private dqTail = 0;
  private readonly held: Float64Array;
  private readonly ringMask: number;
  private heldSum: number;
  private lastHeld = 1;
  /** The interpolated peak just before the position being decided. */
  private betweenPrev = 0;
  private readonly scratch = new Float64Array(TAPS);

  constructor(
    readonly sampleRate: number,
    readonly channels: number,
    ceilingDbtp: number
  ) {
    this.window = Math.max(1, Math.round(LOOKAHEAD_S * sampleRate));
    this.ceiling = 10 ** ((ceilingDbtp - CEILING_MARGIN_DB) / 20);
    this.release = Math.exp(-1 / (RELEASE_S * sampleRate));
    this.interp = new Interpolator(sampleRate);
    // A position is decided once the interpolator can see HALF_TAPS past it,
    // and a sample's gain settles once the window after it is decided.
    this.latency = HALF_TAPS + this.window - 1;
    const histLen = 1 << Math.ceil(Math.log2(this.latency + TAPS + 2));
    this.histMask = histLen - 1;
    this.hist = Array.from({ length: channels }, () => new Float64Array(histLen));
    this.loudest = new Float64Array(histLen);
    const ring = 1 << Math.ceil(Math.log2(this.window + 2));
    this.ringMask = ring - 1;
    this.need = new Float64Array(ring);
    this.dq = new Int32Array(ring);
    // The gains before the first sample are unity.
    this.held = new Float64Array(ring).fill(1);
    this.heldSum = this.window;
  }

  /** Feed planar input; returns the planar output that is ready. */
  process(input: ArrayLike<number>[]): Float32Array[] {
    const n = input[0]?.length ?? 0;
    const out = Array.from({ length: this.channels }, () => new Float32Array(n));
    let w = 0;
    for (let i = 0; i < n; i++) {
      for (let c = 0; c < this.channels; c++) this.hist[c][this.fed & this.histMask] = input[c][i];
      this.received++;
      w = this.advance(out, w);
    }
    return w === n ? out : out.map((o) => o.subarray(0, w));
  }

  /** The output the look-ahead is still holding. */
  flush(): Float32Array[] {
    const left = this.received - this.emitted;
    const out = Array.from({ length: this.channels }, () => new Float32Array(left));
    let w = 0;
    // Silence past the end lets every held sample through.
    while (this.emitted < this.received) {
      for (let c = 0; c < this.channels; c++) this.hist[c][this.fed & this.histMask] = 0;
      w = this.advance(out, w);
    }
    return out.map((o) => o.subarray(0, w));
  }

  /** Take in the sample just written at `fed`, decide what it unlocks, and
   * emit the sample whose gain settled. */
  private advance(out: Float32Array[], w: number): number {
    const t = this.fed++;
    const m = this.histMask;
    let loud = 0;
    for (let c = 0; c < this.channels; c++) {
      const v = this.hist[c][t & m];
      const a = v < 0 ? -v : v;
      if (a > loud) loud = a;
    }
    this.loudest[t & m] = loud;
    const pos = t - HALF_TAPS;
    if (pos < 0) return w;
    const s = this.decide(pos);
    if (s < 0 || s >= this.received) return w;
    const g = this.heldSum / this.window;
    for (let c = 0; c < this.channels; c++) out[c][w] = this.hist[c][s & m] * g;
    this.emitted++;
    return w + 1;
  }

  /** Decide the requirement at `pos` and settle the held gain of the sample
   * a window before it, which is returned (negative while none has). */
  private decide(pos: number): number {
    const m = this.histMask;
    const near = Math.max(this.loudest[pos & m], this.loudest[(pos + 1) & m]);
    // The curve between pos and pos + 1, read only where it could reach the
    // ceiling.
    let between = 0;
    if (near * OVERSHOOT > this.ceiling) {
      const x = this.scratch;
      for (let c = 0; c < this.channels; c++) {
        for (let j = 0; j < TAPS; j++) {
          const i = pos - (HALF_TAPS - 1) + j;
          x[j] = i >= 0 ? this.hist[c][i & m] : 0;
        }
        const v = this.interp.between(x, HALF_TAPS - 1);
        if (v > between) between = v;
      }
    }
    const peak = Math.max(this.loudest[pos & m], between, this.betweenPrev);
    this.betweenPrev = between;
    const need = peak > this.ceiling ? this.ceiling / peak : 1;

    // The forward minimum of the requirement over [s, s + window - 1].
    const r = this.ringMask;
    this.need[pos & r] = need;
    while (this.dqTail > this.dqHead && this.need[this.dq[(this.dqTail - 1) & r] & r] >= need) this.dqTail--;
    this.dq[this.dqTail++ & r] = pos;
    const s = pos - this.window + 1;
    while (this.dq[this.dqHead & r] < s) this.dqHead++;
    if (s < 0) return s;
    const hold = this.need[this.dq[this.dqHead & r] & r];
    // Let go exponentially, never above what the window demands.
    const g = Math.min(hold, 1 - (1 - this.lastHeld) * this.release);
    this.lastHeld = g;
    if (s === 0) {
      // Nothing plays before the first sample, so the average leading into
      // it starts at the first sample's own held gain: a unity run there
      // would let the opening peaks through.
      this.held.fill(g);
      this.heldSum = this.window * g;
    } else {
      this.heldSum += g - this.held[(s - this.window) & r];
      this.held[s & r] = g;
    }
    return s;
  }
}

/** What a master did. */
export interface MasterReport {
  /** The mix as it came in. */
  measured: LoudnessMeasure;
  plan: MasterPlan;
}

/**
 * Master a stream of planar chunks to `targetLufs` under `ceilingDbtp`.
 *
 * Two reads of the same audio: the first measures it, the second applies the
 * gain and, only when the plan calls for it, the limiter. `chunks` is called
 * once per read; `write` receives the mastered audio in order, the same
 * number of samples as went in. The tab hands it its mix buffer a slice at a
 * time and the engine its rendered mix a second at a time, so both run this
 * exact code.
 */
export async function masterStream(
  chunks: () => AsyncIterable<Float32Array[]>,
  write: (chunk: Float32Array[]) => Promise<void> | void,
  opts: { sampleRate: number; channels: number; targetLufs: number; ceilingDbtp: number }
): Promise<MasterReport> {
  const meter = new LoudnessMeter(opts.sampleRate, opts.channels);
  for await (const chunk of chunks()) meter.push(chunk);
  const measured = meter.result();
  const plan = masterPlan(measured, opts.targetLufs, opts.ceilingDbtp);
  const gain = 10 ** (plan.gainDb / 20);
  const limiter = plan.limit ? new TruePeakLimiter(opts.sampleRate, opts.channels, opts.ceilingDbtp) : null;
  for await (const chunk of chunks()) {
    const gained = chunk.map((x) => {
      const y = new Float32Array(x.length);
      for (let i = 0; i < x.length; i++) y[i] = x[i] * gain;
      return y;
    });
    const out = limiter ? limiter.process(gained) : gained;
    if (out[0].length > 0) await write(out);
  }
  if (limiter) {
    const rest = limiter.flush();
    if (rest[0].length > 0) await write(rest);
  }
  return { measured, plan };
}

/** Master planar buffers in place; see `masterStream`. Reads and writes in
 * half-second slices and yields between them, so a long mix never holds the
 * thread for the whole of it. */
export async function masterInPlace(
  channels: Float32Array[],
  opts: { sampleRate: number; targetLufs: number; ceilingDbtp: number }
): Promise<MasterReport> {
  let at = 0;
  return masterStream(
    // Copies: the limiter's writes land behind the read, on the same arrays.
    () => halfSeconds(channels, opts.sampleRate, "copy"),
    (chunk) => {
      chunk.forEach((c, k) => channels[k].set(c, at));
      at += chunk[0].length;
    },
    { ...opts, channels: channels.length }
  );
}